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

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_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_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, 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>,

}

impl BfcLayoutResult {

}

/// The CSS `overflow` property behavior.

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

pub enum OverflowBehavior {

    Visible,

    Hidden,

    Clip,

    Scroll,

    Auto,

}

impl OverflowBehavior {

}

/// 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,

}

/// 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 BfcState {

}

/// Manages vertical margin collapsing within a BFC.

#[derive(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,

}

/// Result of a formatting context layout operation

#[derive(Debug, Default)]

pub struct LayoutResult {

    pub positions: Vec<(usize, LogicalPosition)>,

    pub overflow_size: Option<LogicalSize>,

    pub baseline_offset: f32,

}

// 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)

        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 { .. } => {

        }

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

        FormattingContext::InlineBlock => {

            // +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

        // 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 => {

        }

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

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

        }

        _ => {

            // 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)

    // 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 {

    };

            } else {

            }

    } else {

    };

    // 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

    // 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.

            );

                    );

                }

                }

            }

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

            );

                    );

                }

                }

            }

// +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)

            } else {

                // 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

            } else {

            }

        }

    };

// 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)

    // +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

        // 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 resolution and indefinite-height semantics.

        } else {

        }

    } else {

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

        // when coming from parent's layout constraints)

    };

    // +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 / the anti-jitter

    //   merge (`merge_scrollbar_info`) 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.

    //   The merge uses `||` (keep once detected), preventing cross-frame jitter.

            use azul_css::props::layout::LayoutOverflow;

                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.

    {

            // +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.

        }

    }

    // +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

    // root on its own does not.

    // Track accumulated top margin for first-child escape

    // Track if first child's margin escaped (for return value)

    // Track if we have any actual content (non-empty blocks)

    // +spec:display-property:9f6e18 - BFC dispatches normal flow, floats, and relative positioning (CSS 2.2 §9.8)

        // +spec:floats:2cec1b - 'position' and 'float' determine the positioning algorithm

        // +spec:positioning:dccad6 - floats only apply to non-absolutely-positioned boxes

        // +spec:floats:2cec1b - float property determines positioning algorithm (float path)

        // +spec:floats:f6c0b2 - floats only processed in BFC; other formatting contexts (flex/grid) inhibit floating

        // Check if this child is a float - if so, position it at current main_pen

                // Calculate float size just-in-time if not already computed

                    None => {

                    }

                };

                // Re-borrow after potential mutation

                // +spec:floats:d0d163 - clear on floats adds constraint #10: float top below cleared floats' bottom

                // +spec:floats:7adb9d - Clear on floats: constraint #10, top outer edge must be below earlier cleared floats

                } else {

                    // +spec:floats:ef96cb - Float margins never collapse with adjacent margins

                    // CSS 2.2 § 9.5: Float margins don't collapse with any other margins.

                };

                    child_index,

                    float_type,

                    float_size,

                    float_y,

                    main_pen,

                    last_margin_bottom

                );

                // Position the float at the CURRENT main_pen + last margin (respects DOM order!)

                    // Include last_margin_bottom since float margins don't collapse!

                );

                // Add to float context BEFORE positioning next element

                // Store position in output

                    child_index,

                    main_pen

                );

                // Floats are taken out of normal flow - DON'T advance main_pen

                // Continue to next child

        } else {

        };

        // Early exit for floats (already handled above)

        // From here: normal flow (non-float) children only

        // Track first and last in-flow children for parent-child collapse

        // Calculate child's used_size just-in-time if not already computed

        // This replaces the old "Pass 1" that recursively laid out grandchildren with wrong positions

            None => {

                // Calculate size without recursive layout

                // Update the node with computed size (we need to re-borrow mutably)

            }

        };

        // Re-borrow child_node after potential mutation

            child_index,

            child_margin.top,

            child_margin.right,

            child_margin.bottom,

            child_margin.left

        );

        // +spec:block-formatting-context:0f802c - margins use containing block's writing mode for collapsing/auto expansion in orthogonal flows

        // CSS 2.2 § 8.3.1: If a child has no top blocker (no padding/border) and its

        // own BFC layout produced an escaped_top_margin, that margin represents the

        // collapsed value of (child's margin, child's first child's margin, ...).

        // Use it for sibling collapse instead of the child's own margin.

            child_index,

            child_margin_top,

            child_margin_bottom

        );

        // Check if this child has border/padding that prevents margin collapsing

        // +spec:floats:dc195a - Clear property only applies to block-level elements (CSS 2.2 § 9.5.2)

        // Check for clear property FIRST - clearance affects whether element is considered empty

        // CSS 2.2 § 9.5.2: "Clearance inhibits margin collapsing"

        // An element with clearance is NOT empty even if it has no content

        } else {

        };

            child_index,

            child_clear

        );

        // PHASE 1: Empty Block Detection & Self-Collapse

        // Handle empty blocks FIRST (they collapse through and don't participate in layout)

        // EXCEPTION: Elements with clear property are NOT skipped even if empty!

        // CSS 2.2 § 9.5.2: Clear property affects positioning even for empty elements

        {

            // Empty block: collapse its own top and bottom margins FIRST

            // Then collapse with previous margin (sibling or parent)

                // Empty first child: its collapsed margin can escape with parent's

                    // Parent has blocker: add margins

                }

            // Skip positioning and pen advance (empty has no visual presence)

        // From here on: non-empty blocks only (or empty blocks with clear property)

        // Apply clearance if needed

        // +spec:floats:148ee6 - clear:left pushes element below float; clearance added above top margin