//! Formatting context layout (block, inline, table, and flex/grid via Taffy)

use crate::solver3::layout_tree::LayoutNodeId;

use std::{

    collections::{BTreeMap, HashMap},

    sync::Arc,

};

use azul_core::{

    dom::{FormattingContext, NodeId, NodeType},

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    resources::RendererResources,

    styled_dom::{StyledDom, StyledNodeState},

};

use azul_css::{

    css::CssPropertyValue,

    props::{

        basic::{

            font::{StyleFontStyle, StyleFontWeight},

            pixel::{DEFAULT_FONT_SIZE, PT_TO_PX},

            ColorU, PhysicalSize, PropertyContext, ResolutionContext, SizeMetric,

        },

        layout::{

            ColumnCount, ColumnWidth, LayoutBorderSpacing, LayoutClear, LayoutDisplay, LayoutFloat,

            LayoutHeight, LayoutJustifyContent, LayoutOverflow, LayoutPosition, LayoutTableLayout,

            LayoutTextJustify, LayoutWidth, LayoutWritingMode, ShapeInside, ShapeOutside,

            StyleBorderCollapse, StyleCaptionSide, StyleEmptyCells,

        },

        property::CssProperty,

        style::{

            BorderStyle, StyleDirection, StyleHyphens, StyleLineBreak, StyleListStylePosition,

            StyleListStyleType, StyleOverflowWrap, StyleTextAlign, StyleTextAlignLast,

            StyleTextBoxTrim, StyleTextCombineUpright, StyleTextOrientation, StyleUnicodeBidi,

            StyleVerticalAlign, StyleVisibility, StyleWhiteSpace, StyleWordBreak,

        },

    },

};

use rust_fontconfig::FcWeight;

use taffy::{AvailableSpace, LayoutInput, Line, Size as TaffySize};

#[cfg(feature = "text_layout")]

use crate::text3;

use crate::{

    debug_ifc_layout, debug_info, debug_log, debug_table_layout, debug_warning,

    font_traits::{

        ContentIndex, FontLoaderTrait, ImageSource, InlineContent, InlineImage, InlineShape,

        LayoutFragment, ObjectFit, ParsedFontTrait, SegmentAlignment, ShapeBoundary,

        ShapeDefinition, ShapedItem, Size, StyleProperties, StyledRun, TextLayoutCache,

        UnifiedConstraints,

    },

    solver3::{

        geometry::{BoxProps, EdgeSizes, IntrinsicSizes},

        getters::{

            get_css_border_bottom_width, get_css_border_top_width, get_css_box_sizing,

            get_css_height, get_css_padding_bottom, get_css_padding_top,

            get_css_width, get_direction_property, get_unicode_bidi_property,

            get_display_property, get_element_font_size, get_float, get_clear,

            get_list_style_position, get_list_style_type, get_overflow_x, get_overflow_y,

            get_parent_font_size, get_root_font_size, get_style_properties,

            get_text_align, get_text_box_edge_property, get_text_box_trim_property,

            get_text_orientation_property,

            get_vertical_align_property, get_visibility, get_white_space_property,

            get_writing_mode, MultiValue,

        },

        layout_tree::{

            AnonymousBoxType, CachedInlineLayout, LayoutNode, LayoutNodeHot, LayoutNodeWarm, LayoutNodeCold, LayoutTree, PseudoElement,

        },

        positioning::get_position_type,

        scrollbar::ScrollbarRequirements,

        sizing::extract_text_from_node,

        taffy_bridge, LayoutContext, LayoutDebugMessage, LayoutError, Result,

    },

    text3::cache::{

        AvailableSpace as Text3AvailableSpace, BreakType, ClearType, InlineBreak,

        TextAlign as Text3TextAlign,

    },

};

/// Default scrollbar width in pixels (CSS `scrollbar-width: auto`).

///

/// This is only used as a fallback when per-node CSS cannot be queried.

/// Prefer `getters::get_layout_scrollbar_width_px()` for per-node resolution.

pub const DEFAULT_SCROLLBAR_WIDTH_PX: f32 = 16.0;

// Note: DEFAULT_FONT_SIZE and PT_TO_PX are imported from pixel

/// Result of BFC layout with margin escape information

#[derive(Debug, Clone)]

pub(crate) struct BfcLayoutResult {

    /// Standard layout output (positions, overflow size, baseline)

    pub output: LayoutOutput,

    /// Top margin that escaped the BFC (for parent-child collapse)

    /// If Some, this margin should be used by parent instead of positioning this BFC

    pub escaped_top_margin: Option<f32>,

    /// Bottom margin that escaped the BFC (for parent-child collapse)

    /// If Some, this margin should collapse with next sibling

    pub escaped_bottom_margin: Option<f32>,

    /// K30b: `Some` = this BFC ran out of fragmentainer space; the token

    /// resumes it in the next fragmentainer. Always `None` on the

    /// continuous path (`constraints.fragmentainer == None`).

    pub outgoing_token: Option<crate::solver3::break_token::BreakToken>,

}

impl BfcLayoutResult {

}

/// The CSS `overflow` property behavior.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum OverflowBehavior {

    Visible,

    Hidden,

    Clip,

    Scroll,

    Auto,

}

impl OverflowBehavior {

}

/// K30b: the fragmentainer the current layout call is filling (design:

/// `scripts/BREAK_TOKENS_DESIGN.md` §4.3). `None` = continuous media — every

/// existing path passes `None` and behaves bit-for-bit as before.

#[derive(Debug, Clone, Copy, PartialEq)]

pub struct FragmentainerSpace<'a> {

    /// Block-extent remaining in the CURRENT fragmentainer, measured from

    /// this box's block-start (the pen compares against it directly).

    pub remaining_block_extent: f32,

    /// Extent of a FRESH next fragmentainer ("would it fit on the next

    /// page at all?" — monolith classification).

    pub next_fragmentainer_extent: f32,

    /// True while filling the very first fragmentainer of the flow.

    pub is_first: bool,

    /// Incoming resume state for THIS box (the page loop threads page

    /// N−1's outgoing token back in). The token rides the fragmentainer

    /// input instead of a separate parameter so the continuous path stays

    /// signature-identical.

    pub resume: Option<&'a crate::solver3::break_token::BlockBreakToken>,

}

/// Input constraints for a layout function.

#[derive(Debug)]

pub struct LayoutConstraints<'a> {

    /// The available space for the content, excluding padding and borders.

    pub available_size: LogicalSize,

    /// The CSS writing-mode of the context.

    pub writing_mode: LayoutWritingMode,

    /// Full writing mode context (writing-mode + direction + text-orientation).

    /// Used by writing-mode-aware layout code to correctly map inline/block

    /// dimensions to physical x/y coordinates.

    pub writing_mode_ctx: super::geometry::WritingModeContext,

    /// The state of the parent Block Formatting Context, if applicable.

    /// This is how state (like floats) is passed down.

    pub bfc_state: Option<&'a mut BfcState>,

    // Other properties like text-align would go here.

    pub text_align: TextAlign,

    /// The size of the containing block (parent's content box).

    /// This is used for resolving percentage-based sizes and as `parent_size` for Taffy.

    pub containing_block_size: LogicalSize,

    /// The semantic type of the available width constraint.

    ///

    /// This field is crucial for correct inline layout caching:

    /// - `Definite(w)`: Normal layout with a specific available width

    /// - `MinContent`: Intrinsic minimum width measurement (maximum wrapping)

    /// - `MaxContent`: Intrinsic maximum width measurement (no wrapping)

    ///

    /// When caching inline layouts, we must track which constraint type was used

    /// to compute the cached result. A layout computed with `MinContent` (width=0)

    /// must not be reused when the actual available width is known.

    pub available_width_type: Text3AvailableSpace,

    /// K30b fragmentation: `None` = continuous (screen) layout, identical

    /// to pre-token behavior. `Some` arms the fit checks in `layout_bfc`.

    pub fragmentainer: Option<FragmentainerSpace<'a>>,

}

/// Manages all layout state for a single Block Formatting Context.

/// This struct is created by the BFC root and lives for the duration of its layout.

#[derive(Debug, Clone)]

pub struct BfcState {

    /// The current position for the next in-flow block element.

    pub pen: LogicalPosition,

    /// The state of all floated elements within this BFC.

    pub floats: FloatingContext,

    /// The state of margin collapsing within this BFC.

    pub margins: MarginCollapseContext,

}

impl Default for BfcState {

}

impl BfcState {

}

/// Manages vertical margin collapsing within a BFC.

#[derive(Copy, Debug, Default, Clone)]

pub struct MarginCollapseContext {

    /// The bottom margin of the last in-flow, block-level element.

    /// Can be positive or negative.

    pub last_in_flow_margin_bottom: f32,

}

/// The result of laying out a formatting context.

#[derive(Debug, Default, Clone)]

pub struct LayoutOutput {

    /// The final positions of child nodes, relative to the container's content-box origin.

    pub positions: BTreeMap<usize, LogicalPosition>,

    /// The total size occupied by the content, which may exceed `available_size`.

    pub overflow_size: LogicalSize,

    // +spec:inline-formatting-context:f7eebb - baseline along inline axis for glyph alignment

    /// The baseline of the context, if applicable, measured from the top of its content box.

    pub baseline: Option<f32>,

}

/// Text alignment options

#[derive(Debug, Clone, Copy, Default)]

pub enum TextAlign {

    #[default]

    Start,

    End,

    Center,

    Justify,

}

/// Represents a single floated element within a BFC.

#[derive(Debug, Clone, Copy)]

struct FloatBox {

    /// The type of float (Left or Right).

    kind: LayoutFloat,

    /// The rectangle of the float's content box (origin includes top/left margin offset).

    rect: LogicalRect,

    /// The margin sizes (needed to calculate true margin-box bounds).

    margin: EdgeSizes,

}

/// Manages the state of all floated elements within a Block Formatting Context.

// +spec:block-formatting-context:a4e6f9 - float rules reference only elements in the same BFC (scoped via BfcState)

// +spec:floats:2fa329 - Float positioning (left/right shift), content flow along sides, and clear property

/// +spec:floats:970b4c - Implements CSS2§9.5 float positioning and flow interaction

#[derive(Debug, Default, Clone)]

pub struct FloatingContext {

    /// All currently positioned floats within the BFC.

    pub floats: Vec<FloatBox>,

}

impl FloatingContext {

    /// Add a newly positioned float to the context

    // +spec:box-model:0c9b13 - line boxes next to floats are shortened to make room

    // +spec:floats:148fcd - floating boxes reduce available line box width between containing block edges

    // +spec:floats:49a491 - Line boxes stacked with no separation except float clearance, never overlap

    // +spec:floats:8974e6 - text flows into vacated space by narrowing line boxes around floats

    // +spec:floats:af94f2 - content displaced by float: line boxes shrink to avoid float margin boxes

    // +spec:floats:e5961b - remaining text flows into vacated space via available_line_box_space

    // +spec:inline-formatting-context:7cbe58 - shortened line boxes due to floats; shift down if too small

    /// Finds the available space on the cross-axis for a line box at a given main-axis range.

    // +spec:containing-block:4b0c44 - line boxes shortened by floats resume containing block width after float

    ///

    /// Returns a tuple of (`cross_start_offset`, `cross_end_offset`) relative to the

    /// BFC content box, defining the available space for an in-flow element.

    // +spec:inline-formatting-context:e70328 - line box width reduced by floats between containing block edges

            // Get the logical main-axis span of the existing float's MARGIN BOX.

            // Check for overlap on the main axis.

                // CSS 2.2 § 9.5: border box must not overlap MARGIN BOX of floats,

                // so we include the float's margins in the cross-axis bounds.

                // +spec:floats:17a63f - float left/right map to line-left/line-right via logical coords

                // +spec:writing-modes:e55820 - line-relative mappings: left/right interpreted as line-left/line-right per writing mode

        }

    // +spec:block-formatting-context:d06e6e - clearance computation for clear property on blocks and floats (CSS 2.2 § 9.5.2)

    // +spec:floats:31a3d5 - Clearance computation: places border edge even with bottom outer edge of lowest float to be cleared

    // +spec:floats:f9bef1 - clear property moves element below preceding floats

    /// Returns the main-axis offset needed to be clear of floats of the given type.

    // +spec:block-formatting-context:7f6bde - CSS 2.2 § 9.5.2 clear property: clearance places border edge below bottom outer edge of cleared floats

    // +spec:block-formatting-context:ef493f - clearance computation: places border edge even with bottom outer edge of lowest float to be cleared; inhibits margin collapsing

    // +spec:box-model:b118fe - top border edge must be below bottom outer edge of earlier floats

    // +spec:floats:415066 - Clear property: top border edge below bottom outer edge of cleared floats

    // +spec:floats:7e4ad6 - clear property: element box may not be adjacent to earlier floats; only considers floats in same BFC

    // +spec:floats:32e45d - clear:right causes sibling to flow below right floats

    // +spec:floats:7f417a - clear property prevents content from flowing next to floats

    // +spec:floats:d06304 - clear property moves element below floats, leaving blank space

    // +spec:overflow:1a7aff - clearance calculation (incl. negative clearance) and clear on floats (constraint #10)

    // +spec:positioning:1c2508 - clearance calculation: places border edge even with bottom outer edge of lowest cleared float (CSS 2.2 § 9.5.2)

    // +spec:positioning:fe0912 - clearance computation: places border edge below bottom outer edge of cleared floats

    // (clearance = amount to place border edge even with bottom outer edge of lowest

    // float to be cleared); clearance can be negative per spec example 2

    // +spec:floats:054a1e - Clearance computation: positions border edge below bottom outer edge of cleared floats

    // +spec:floats:cb984c - Clearance can be negative per spec example 2; inhibits margin collapsing

        }

        } else {

        }

}

/// Encapsulates all state needed to lay out a single Block Formatting Context.

struct BfcLayoutState {

    /// The current position for the next in-flow block element.

    pen: LogicalPosition,

    floats: FloatingContext,

    margins: MarginCollapseContext,

    /// The writing mode of the BFC root.

    writing_mode: LayoutWritingMode,

}

// Entry Point & Dispatcher

/// Main dispatcher for formatting context layout.

///

/// Routes layout to the appropriate formatting context handler based on the node's

/// `formatting_context` property. This is the main entry point for all layout operations.

///

/// # CSS Spec References

/// - CSS 2.2 § 9.4: Formatting contexts

/// - CSS Flexbox § 3: Flex formatting contexts

/// - CSS Grid § 5: Grid formatting contexts

// +spec:block-formatting-context:b04653 - dispatches layout by formatting context type (BFC, IFC, Table, Flex, Grid)

// +spec:block-formatting-context:e46499 - inner display type determines formatting context (BFC, IFC, table, flex, grid)

#[allow(clippy::implicit_hasher)] // internal helper; only ever called with the default-hasher HashMap/HashSet

/// # Errors

///

/// Returns a `LayoutError` if laying out the formatting context fails.

    // [g147e az-web-lift DIAG] PURE-CONSTANT entry marker (0x609E0+slot) — fires before any node read,

    // so it reliably shows whether layout_formatting_context is ENTERED for the nested div nodes 1,2.

    #[cfg(feature = "web_lift")]

    unsafe { crate::az_mark(((0x609E0 + (node_index & 7) * 4)) as u32, (0xC0DE0042) as u32); }

    // [g147i az-web-lift DIAG] node REFERENCE address (0x60B80+slot) — NOT a field deref, so reliable.

    // If nodes 0,1,2 aren't spaced by sizeof(LayoutNodeHot) → tree.get(index>0) mis-lifts the Vec stride,

    // making nodes 1,2 garbage references (which would explain FC reading garbage + reads destabilizing).

    #[cfg(feature = "web_lift")]

    unsafe { crate::az_mark(((0x60B80 + (node_index & 7) * 4)) as u32, ((node as *const _ as usize) as u32) as u32); }

    // [g147 az-web-lift] Recompute the IFC decision from the DOM: on the lift, the stored

    // `node.formatting_context` reads GARBAGE for nested inline divs (2026-06-10 re-test WITHOUT

    // this bypass: nodes 1/2 dispatch to the `_` arm + determine_formatting_context_for_display's

    // markers never fire → the FC ASSIGNMENT path itself mis-lifts upstream — NOT fixed by the

    // repr(C,u8) guard, NOT fixed by the leak-gated SP restore; same family as the enum/jump-table

    // devirt class). The styled_dom IS reliable, so a block container whose children are all

    // inline-level establishes an IFC (CSS 2.2 §9.2.1) — semantically valid recomputation, not a

    // hack on top of garbage. web_lift-gated → native untouched. Remove when the FC-assignment

    // mis-lift is root-caused (follow-up: bisect LayoutTreeBuilder's determine_/display match).

    #[cfg(feature = "web_lift")]

    {

        let force_ifc = node

            .dom_node_id

            .map_or(false, |dom_id| {

                crate::solver3::layout_tree::has_only_inline_children(ctx.styled_dom, dom_id)

            });

        if force_ifc {

            unsafe { crate::az_mark(((0x60BA0 + (node_index & 7) * 4)) as u32, (0xC0DE1FC0) as u32); }

            return layout_ifc(ctx, text_cache, tree, node_index, constraints)

                .map(BfcLayoutResult::from_output);

        }

    }

    // [g147b az-web-lift DIAG] per-node FormattingContext discriminant at layout_formatting_context

    // entry (0x609A0+slot). Pairs with the dispatch-arm marker (0x609C0+slot) inside each match arm:

    // if a text-div's FC reads Inline(2) but the arm marker shows Block(1) → match dispatch mis-lifts;

    // if FC reads Block(1) → tree-construction FC assignment is wrong; if 0x609A0 stays unset for the

    // div node → layout_formatting_context is never called for it (cache-hit short-circuit upstream).

    #[cfg(feature = "web_lift")]

    unsafe {

        let fc_disc = match node.formatting_context {

            FormattingContext::Block { .. } => 1u32,

            FormattingContext::Inline => 2,

            FormattingContext::InlineBlock => 3,

            FormattingContext::Flex => 4,

            FormattingContext::Grid => 5,

            FormattingContext::Table => 6,

            FormattingContext::TableCell => 7,

            FormattingContext::TableCaption => 8,

            _ => 0,

        };

        crate::az_mark(((0x609A0 + (node_index & 7) * 4)) as u32, (fc_disc | 0xC0DE0000) as u32);

    }

        node_index,

        node.formatting_context,

        constraints.available_size

    );

    // +spec:block-formatting-context:06a24f - CSS 2.2 § 9.4: block-level boxes → BFC, inline-level → IFC

    // +spec:block-formatting-context:9428cf - block container can establish both BFC and IFC simultaneously

    // +spec:inline-formatting-context:8bfe73 - display:flow generates inline box (Inline) or block container (Block) based on outer display type

        FormattingContext::Block { .. } => {

            #[cfg(feature = "web_lift")]

            unsafe { crate::az_mark(((0x609C0 + (node_index & 7) * 4)) as u32, (0xC0DE0001) as u32); }

        }

        // +spec:inline-formatting-context:a180ed - IFC establishment: inline-level boxes fragmented into line boxes with baseline alignment

        FormattingContext::Inline => {

            #[cfg(feature = "web_lift")]

            unsafe { crate::az_mark(((0x609C0 + (node_index & 7) * 4)) as u32, (0xC0DE0002) as u32); }

        }

        FormattingContext::InlineBlock => {

            #[cfg(feature = "web_lift")]

            unsafe { crate::az_mark(((0x609C0 + (node_index & 7) * 4)) as u32, (0xC0DE0003) as u32); }

            // +spec:display-property:1f5ddf - inline-level boxes with non-flow inner display establish new formatting context

            // +spec:inline-formatting-context:1ad004 - atomic inline (inline-block) establishes new formatting context

            // CSS 2.2 § 9.4.1: "inline-blocks... establish new block formatting contexts"

            // +spec:inline-block:8d21f6 - inline-block generates inline-level block container (BFC inside, atomic inline outside)

            // InlineBlock ALWAYS establishes a BFC for its contents.

            // The element itself participates as an atomic inline in its parent's IFC,

            // but its children are laid out in a BFC, not an IFC.

        }

        // +spec:table-layout:753687 - CSS 2.2 §17.2 table model: display values map to FormattingContext variants and dispatch table layout

        FormattingContext::Table => {

            #[cfg(feature = "web_lift")]

            unsafe { crate::az_mark(((0x609C0 + (node_index & 7) * 4)) as u32, (0xC0DE0006) as u32); }

        }

        // Table-internal flex items are blockified during tree construction

        // (blockify_flex_item_if_table_internal in layout_tree.rs), so they arrive

        // here as Block, not TableCell etc.

        FormattingContext::Flex | FormattingContext::Grid => {

            #[cfg(feature = "web_lift")]

            unsafe { crate::az_mark(((0x609C0 + (node_index & 7) * 4)) as u32, (0xC0DE0004) as u32); }

        }

        // that are not block boxes, so they establish new BFCs for their contents

        FormattingContext::TableCell | FormattingContext::TableCaption => {

            #[cfg(feature = "web_lift")]

            unsafe { crate::az_mark(((0x609C0 + (node_index & 7) * 4)) as u32, (0xC0DE0007) as u32); }

        }

        _ => {

            // [g147g az-web-lift DIAG] read the RAW discriminant byte (offset 0 under repr(C,u8)) of the

            // node that fell through to `_`. node 0 won't hit `_`; nodes 1,2 (divs) write their disc to

            // 0x60B40+slot. disc=1 ⇒ value IS Inline but the dispatch match mis-branched (match/jump-table

            // lift bug); disc≠1 ⇒ tree-construction stored the wrong/garbage FC for the nested div.

            #[cfg(feature = "web_lift")]

            unsafe {

                crate::az_mark(((0x609C0 + (node_index & 7) * 4)) as u32, (0xC0DE0009) as u32);

                let disc: u8 = core::ptr::read_volatile((&node.formatting_context) as *const FormattingContext as *const u8);

                crate::az_mark(((0x60B40 + (node_index & 7) * 4)) as u32, (0xC0DE0000 | (disc as u32)) as u32);

            }

            // Unknown formatting context - fall back to BFC

            )

        }

    }

// Flex / grid layout (taffy Bridge)

// containing block determined by grid-placement properties; Taffy handles this internally

// (grid auto-placement §8.5 and abspos grid items use grid-area CB, not just padding box)

/// Lays out a Flex or Grid formatting context using the Taffy layout engine.

///

/// # CSS Spec References

///

/// - CSS Flexbox § 9: Flex Layout Algorithm

/// - CSS Grid § 12: Grid Layout Algorithm

// gutters on either side of collapsed tracks collapse including distributed alignment space,

// minimum contribution = outer size from min-width/min-height if specified size is auto else

// min-content contribution) — all handled by Taffy grid implementation

///

/// # Implementation Notes

///

/// - Resolves explicit CSS dimensions to pixel values for `known_dimensions`

/// - Uses `InherentSize` mode when explicit dimensions are set

/// - Uses `ContentSize` mode for auto-sizing (shrink-to-fit)

#[allow(clippy::too_many_lines)] // large but cohesive: single-purpose layout/render/parse routine (one branch per case)

    // Available space comes directly from constraints - margins are handled by Taffy

    // from flex line's cross size (clamped by min/max) when align-self:stretch, cross-size:auto,

    // and neither cross-axis margin is auto. Otherwise uses hypothetical cross size.

    // NOTE: visibility:collapse strut size for flex items is handled internally by Taffy.

    //

    // Resolve explicit CSS dimensions to pixel values.

    // This is CRITICAL for align-items: stretch to work correctly!

    // Taffy uses known_dimensions to calculate cross_axis_available_space for children.

    // FIX: For root nodes or nodes where the parent provides a definite size,

    // use the available_size as known_dimensions if no explicit CSS width/height is set.

    // This is critical for `align-self: stretch` to work - Taffy needs to know the

    // cross-axis size of the container to stretch children to fill it.

    // `constraints.available_size` is the root's CONTENT-BOX (produced by

    // `prepare_layout_context::inner_size(final_used_size)`), not the viewport

    // border-box. Previously, the code used it as if it were border-box,

    // causing taffy to subtract padding a second time and shrink the content

    // area by 2x padding. For the root, pull the actual border-box from

    // `node.used_size` (set by `calculate_used_size_for_node` before this call).

                // Fallback: convert content-box to border-box.

            } else {

            }

    } else {

        // Non-root flex/grid container with `width: auto`: for a block-level

        // child the parent's block layout has ALREADY resolved the used width

        // (auto → fill containing block) before descending into this FC — pass

        // it through as the definite border-box width, exactly like the root

        // branch does with its used_size. Without this, known_dimensions.width

        // stays None and taffy treats a column container's cross axis as

        // INDEFINITE, so `align-items: stretch` items get the flex line's

        // max-content width instead of the container width (live bug: under

        // the injected Html menubar wrapper, AzulPaint's body laid out its

        // header AND canvas at 315.776px — the header text's max-content —

        // instead of the body's 624px).

    };

            // An auto-height root's `used_size` is content-derived and is

            // still ZERO here (children have not been laid out yet).

            // Handing that to taffy as a DEFINITE main size makes a column

            // flex container think it has -60px of free space, so every

            // item with the default `flex-shrink: 1` collapses to 0 — a

            // fixed-height toolbar under `body { display: flex;

            // flex-direction: column }` simply vanished.

            //

            // CSS Flexbox §9.7: a container whose main size is INDEFINITE

            // sizes items to their hypothetical main size and performs no

            // shrinking. Leaving the dimension unknown is what makes taffy

            // content-size the container.

            None => {

                } else {

                }

            }

        }

    } else {

        // Non-root height pass-through, mirroring the width arm above,

        // but ONLY for absolutely/fixed-positioned containers: their

        // used height was resolved by the §10.6.4 equations (stretch-fit

        // between insets) BEFORE this run — a >0 value is the DEFINITE

        // containing-block size, exactly like the width case. Without

        // this, `inset:0; display:flex; align-items:center` centered

        // within the CONTENT height (taffy re-derived the main size and

        // clobbered the solved stretch-fit — miniword ENGINE-ISSUE 5a).

        // In-flow auto-height containers stay None (content-sized;

        // their used_size may hold a stale height on warm re-layouts).

            LayoutPosition::Absolute

                | LayoutPosition::Fixed

        );

        }

    };

    // Taffy interprets known_dimensions as border-box. CSS width/height default

    // to content-box, so explicit values need +padding+border added. For the

    // ROOT element, however, we auto-apply box-sizing: border-box — the common

    // CSS reset pattern — so `height:100%` + padding fits the viewport instead

    // of overflowing by padding (which the default content-box interpretation

    // would produce, since 100% of ICB is viewport-sized content, with padding

    // added outside pushing border-box past the viewport).

    } else {

    };

    } else {

    };

    // CSS Flexbox § 9.2: Use InherentSize when explicit dimensions are set,

    // ContentSize for auto-sizing (shrink-to-fit behavior).

    } else {

    };

    // parent_size tells Taffy the size of the container's parent.

    // For root nodes, the "parent" is the viewport, but since margins are already

    // handled by calculate_used_size_for_node(), we use containing_block_size directly.

    // For non-root nodes, containing_block_size is already the parent's content-box.

        node_index

    );

    // For the root with auto-applied border-box: sync node.used_size so

    // display-list rendering matches the border-box we handed taffy.

    // Without this, the root's background/border would paint at the

    // inflated size from calculate_used_size_for_node while taffy placed

    // children inside a smaller content-box.

    // Cache border values before the mutable borrow in layout_taffy_subtree

    // Adopt taffy's computed container border-box as this node's used_size. This is

    // the height/width taffy actually laid the tracks/lines into. The auto-height

    // path (cache.rs apply_content_based_height) otherwise derives the container

    // height from taffy's `content_size`, but for a GRID that field measures each

    // item relative to its OWN grid area (≈ the item's own height, blind to which

    // row it sits in), so a multi-row grid collapsed to a single row's height

    // (a 2×2 grid reported 16px instead of 42px). `taffy_output.size` is the correct

    // row/line sum + gaps. Flex's `output.size` already equals the correct container

    // size, so this is a no-op there. The root syncs its own used_size above.

    // Collect child positions from the tree (Taffy stores results directly on nodes).

    // Use content_size for overflow detection, not container size.

    // content_size represents the actual size of all children, which may exceed the container.

    //

    // Taffy's content_size is measured from (0,0) of the border-box, so it includes

    // border.top/left as a leading offset.  The scrollbar geometry and scroll clamp

    // both measure inside the padding-box (border stripped).  Subtract the start

    // border so that overflow_size is in the same coordinate space as the viewport

    // (padding-box), preventing extra scroll range equal to the border width.

    }

/// Resolves explicit CSS width to pixel value for Taffy layout.

/// Axis selector for `border_box_to_content`.

#[derive(Clone, Copy)]

enum Axis {

    Width,

    Height,

}

/// Convert a resolved explicit CSS dimension to the CONTENT-box value the

/// `known_dimensions` pipeline expects.

///

/// The flex/grid `known_dimensions` code resolves the explicit CSS dimension and

/// then unconditionally re-adds border+padding to reach taffy's border-box (see

/// `adjusted_width`/`adjusted_height`). That is correct only when the resolved

/// value is a content-box measurement. For `box-sizing:border-box`, an ABSOLUTE

/// length (px/em/calc) IS already the border-box size, so re-adding border+padding

/// double-counts it (a `height:100px; border:5px` container came out 110px instead

/// of 100). Subtract the axis border+padding here so the caller's re-add restores

/// the intended border-box. Percentages already resolve against the content-box

/// available size, so they are left unchanged.

        MultiValue::Exact(azul_css::props::layout::LayoutBoxSizing::BorderBox)

    );

    };

            );

                LayoutWidth::Auto

                | LayoutWidth::MinContent

                | LayoutWidth::MaxContent

                    );

                    );

                }

                    );

                }

            }

/// Resolves explicit CSS height to pixel value for Taffy layout.

            );

                LayoutHeight::Auto

                | LayoutHeight::MinContent

                | LayoutHeight::MaxContent

                    );

                    // box-sizing:border-box + an ABSOLUTE length is a border-box

                    // value; the caller re-adds border+padding to reach the

                    // taffy border-box, so convert to content-box here to avoid

                    // double-counting. (Percentages already resolve against the

                    // content-box available size, so leave those alone.)

                    );

                }

                    );

                }

            }

// +spec:floats:167a2c - Float positioning rules (CSS 2.2 § 9.5.1): left/right/none, precise placement constraints

// +spec:floats:6a1769 - Float shortens line boxes, margins never collapse, stacking order

// +spec:floats:15bfd9 - float:right positions element at line-right edge within BFC

// +spec:floats:afc8e2 - Float positioning rules (CSS 2.2 § 9.5 rules 1-8): left/right edge containment, earlier-float stacking, outer-top constraints, and "move down" when insufficient space

/// Position a float within a BFC, considering existing floats.

/// Returns the `LogicalRect` (margin box) for the float.

// +spec:box-model:db0f02 - Float positioning: line boxes shortened by floats, floats shift down if no space, BFC elements must not overlap float margin boxes

// +spec:containing-block:136e45 - Float shifted left/right until outer edge touches containing block edge or another float

// +spec:containing-block:3ebb4e - Content moves below floats when containing block too narrow

// +spec:floats:45fce7 - Float positioning: pulled out of flow, line boxes shortened around float

// +spec:floats:f6c218 - float pulled out of flow, line boxes shorten around it

// +spec:height-calculation:86142a - CSS 2.2 §9.5 float positioning, clearance, and margin non-collapsing

// +spec:width-calculation:761677 - float positioning: content flows around floats, line boxes shortened by float presence

    // Start at the current main-axis position (Y in horizontal-tb)

    // Calculate total size including margins

    // +spec:floats:3d89d8 - shift float downward when not enough horizontal room

    // Find a position where the float fits

            // +spec:floats:449158 - left float positioned at line-left, content flows on right

            // Found space that fits

                // +spec:writing-modes:84bcba - floats positioned at line-left / line-right

                // Position at line-left (avail_start)

            // Position at line-right (avail_end - size)

        // top is moved lower than earlier float's bottom (outer edge / margin box bottom)

        // Not enough space at this Y, move down past the lowest overlapping float's margin box bottom

            // No overlapping floats found, use current position anyway

        }

    };

// Block Formatting Context (CSS 2.2 § 9.4.1)

/// Lays out a Block Formatting Context (BFC).

///

/// This is the corrected, architecturally-sound implementation. It solves the

/// "chicken-and-egg" problem by performing its own two-pass layout:

///

/// 1. **Sizing Pass:** It first iterates through its children and triggers their layout recursively

///    by calling `calculate_layout_for_subtree`. This ensures that the `used_size` property of each

///    child is correctly populated.

///

/// 2. **Positioning Pass:** It then iterates through the children again. Now that each child has a

///    valid size, it can apply the standard block-flow logic: stacking them vertically and

///    advancing a "pen" by each child's outer height.

///

/// # Margin Collapsing Architecture

///

/// CSS 2.1 Section 8.3.1 compliant margin collapsing:

///

/// ```text

/// layout_bfc()

///   ├─ Check parent border/padding blockers

///   ├─ For each child:

///   │   ├─ Check child border/padding blockers

///   │   ├─ is_first_child?

///   │   │   └─ Check parent-child top collapse

///   │   ├─ Sibling collapse?

///   │   │   └─ advance_pen_with_margin_collapse()

///   │   │       └─ collapse_margins(prev_bottom, curr_top)

///   │   ├─ Position child

///   │   ├─ is_empty_block()?

///   │   │   └─ Collapse own top+bottom margins (collapse through)

///   │   └─ Save bottom margin for next sibling

///   └─ Check parent-child bottom collapse

/// ```

///

/// **Collapsing Rules:**

///

/// - Sibling margins: Adjacent vertical margins collapse to max (or sum if mixed signs)

/// - Parent-child: First child's top margin can escape parent (if no border/padding)

/// - Parent-child: Last child's bottom margin can escape parent (if no border/padding/height)

/// - Empty blocks: Top+bottom margins collapse with each other, then with siblings

/// - Blockers: Border, padding, inline content, or new BFC prevents collapsing

///

/// This approach is compliant with the CSS visual formatting model and works within

/// the constraints of the existing layout engine architecture.

// +spec:display-property:f38f52 - BFC handles normal flow, relative positioning offsets, and float extraction (CSS 2.2 § 9.8)

#[allow(clippy::too_many_lines, clippy::cognitive_complexity)] // large but cohesive: single-purpose layout/render/parse routine (one branch per case)

    // +spec:block-formatting-context:4f4ff6 - writing-mode determines block flow direction (main axis) for ordering block-level boxes in BFC

        node_index,

    );

    // Initialize FloatingContext for this BFC

    //

    // We always recalculate float positions in this pass, but we'll store them in the cache

    // so that subsequent layout passes (for auto-sizing) have access to the positioned floats

    // +spec:containing-block:42b75f - Block element establishes containing block for inline content (IFC)

    // Calculate this node's content-box size for use as containing block for children

    // CSS 2.2 § 10.1: The containing block for in-flow children is formed by the

    // content edge of the parent's content box.

    //

    // We use constraints.available_size directly as this already represents the

    // content-box available to this node (set by parent). For nodes with explicit

    // sizes, used_size contains the border-box which we convert to content-box.

    //

    // NOTE(writing-modes): The containing block size uses physical width/height.

    // In vertical writing modes, the block progression direction is horizontal,

    // so the "available width" for children maps to the physical height of

    // the containing block. The main_pen variable below tracks block progression

    // using logical main-axis coordinates; the WritingModeContext in constraints

    // determines how main/cross map to physical x/y via from_main_cross().

    // +spec:inline-block:17944a - orthogonal flow roots get infinite available inline space here (not yet detected)

    // +spec:inline-block:a60e22 - other layout models pass through infinite inline space to contained block containers

        // No used_size yet - use available_size directly (this is already content-box

        // when coming from parent's layout constraints)

        || constraints.available_size,

            // Node has used_size (border-box) - convert to content-box.

            // For auto-height containers, the pre-layout `used_size.height` is a

            // placeholder (calculate_used_size_for_node returns 0 for block-level

            // auto-height; apply_content_based_height resolves it after children lay

            // out). In that window, `constraints.available_size.height` holds the

            // containing block's height — the value children should use as their own

            // containing block for percentage-height / indefinite-height semantics.

            } else {

            }

    );

    // +spec:overflow:ffe6f7 - scrollbar space subtracted from containing block per spec §11.1.1

    // Reserve space for vertical scrollbar when appropriate.

    //

    // - overflow: scroll  → ALWAYS reserve (CSS spec: scrollbar always shown)

    // - overflow: auto    → Reserve ONLY when a previous pass already determined

    //   a scrollbar is needed.

    //   On the very first pass the node has no scrollbar_info yet, so no space

    //   is reserved.  After `compute_scrollbar_info` detects overflow it sets

    //   `reflow_needed_for_scrollbars = true`, triggering a second pass where

    //   `node.scrollbar_info.needs_vertical == true` and space IS reserved.

    //   Each pass replaces `scrollbar_info` with the current state; the outer

    //   layout loop's iteration cap handles oscillation safety.

                LayoutOverflow::Scroll => {

                }

                LayoutOverflow::Auto => {

                    } else {

                    }

                }

            }

    // === Pass 1: Pre-compute child sizes (restored two-pass BFC) ===

    //

    // Inspired by Taffy's two-pass approach: first measure, then position.

    //

    // This was removed in commit 1a3e5850 and replaced with a single-pass approach

    // that computed sizes just-in-time during positioning. The single-pass approach

    // caused regression 8e092a2e because positioning decisions (margin collapsing,

    // float clearance, available width after floats) depend on knowing ALL sibling

    // sizes upfront, not just the ones visited so far.

    //

    // With the per-node cache (§9.1-§9.2), the re-added Pass 1 is efficient:

    // - Each child subtree is computed once and stored in NodeCache

    // - Pass 2 positioning reads sizes from tree nodes (used_size set by Pass 1)

    // - When calculate_layout_for_subtree recurses into children after layout_bfc

    //   returns, it hits the per-node cache (same available_size) — O(1) per child.

    //

    // Performance: O(n) for the tree. No double-computation thanks to caching.

    {

        // [g147c az-web-lift DIAG] layout_bfc Pass-1 child-sizing loop: record bfc_children.len per parent

        // node (0x60A00+slot). If body shows len=2 but the divs never get the per-child "sized" marker

        // (0x60A40+childslot) below → the loop skips them; if they DO get it but layout_formatting_context

        // (0x609A0) stays unset → calculate(child,ComputeSize) cache-hit (vs 0x60A60 miss-flag in cache.rs).

        #[cfg(feature = "web_lift")]

        unsafe { crate::az_mark(((0x60A00 + (node_index & 7) * 4)) as u32, (bfc_children.len() as u32 | 0xC0DE0000) as u32); }

            // +spec:positioning:447b06 - Absolute positioning pulls element out of flow, skip from normal layout

            // +spec:positioning:77a2d2 - Absolutely positioned children are ignored for auto height

            // +spec:positioning:b47ac2 - Only normal flow children taken into account for auto height

            // Skip absolutely/fixed positioned children — they're laid out separately

            // +spec:positioning:c7e5c5 - out-of-flow elements ignored for word boundary / hyphenation

            // +spec:positioning:7dd6d1 - Absolutely positioned boxes are taken out of the normal flow (no impact on later siblings, no margin collapsing)

            // Compute the child's full subtree layout with temporary positions.

            // Position (0,0) is intentionally wrong — Pass 1 only cares about sizing.

            // The correct positions are determined in Pass 2 below.

            // [g147c] this child IS reached by Pass-1 sizing (per-child slot).

            #[cfg(feature = "web_lift")]

            unsafe { crate::az_mark(((0x60A40 + (child_index & 7) * 4)) as u32, (0xC0DE0000 | (child_index as u32 & 0xffff)) as u32); }

        }

    }

    // +spec:block-formatting-context:98b633 - CSS 2.2 § 9.4.1: boxes laid out vertically, margins collapse

    // === Pass 2: Position children using known sizes ===

    //

    // All children now have used_size set from Pass 1. This pass handles:

    // - Margin collapsing (parent-child + sibling-sibling)

    // - Float positioning and clearance

    // - Normal flow block positioning

    // Track escaped margins separately from content-box height

    // CSS 2.2 § 8.3.1: Escaped margins don't contribute to parent's content-box height,

    // but DO affect sibling positioning within the parent

    // Track all inter-sibling margins (collapsed) - these are also not part of content height

    // Margin collapsing state

    // Parent's own margins (for escape calculation)

    // margins do not collapse across formatting context boundaries: an independent

    // BFC (float, overflow != visible, display: flex/grid, etc.) isolates its

    // children's margins. The DOM root is NOT a BFC boundary for this purpose —

    // its first child's margin still collapses through it (then gets absorbed at

    // the root, since there's no grandparent to escape to).

    // parent_has_*_blocker inhibits parent-child margin collapse per CSS 2.2 §8.3.1.

    // An explicit border/padding blocks, and an independent BFC blocks, but the