//! solver3/mod.rs

//!

//! Next-generation CSS layout engine with proper formatting context separation

pub mod cache;

pub mod calc;

pub mod counters;

pub mod display_list;

pub mod fc;

pub mod geometry;

pub mod getters;

pub mod layout_tree;

pub use layout_tree::LayoutNodeId;

pub mod page_breaks;

pub mod break_token;

pub mod paged_layout;

pub mod pagination;

pub mod positioning;

pub mod scrollbar;

pub mod sizing;

pub mod taffy_bridge;

/// Lazy `debug_info` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_info {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_info_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_warning` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_warning {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_warning_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_error` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_error {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_error_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_log` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_log {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_log_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_box_props` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_box_props {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_box_props_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_css_getter` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_css_getter {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_css_getter_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_bfc_layout` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_bfc_layout {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_bfc_layout_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_ifc_layout` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_ifc_layout {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_ifc_layout_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_table_layout` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_table_layout {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_table_layout_inner(format!($($arg)*));

        }

    };

}

/// Lazy `debug_display_type` macro - only evaluates format args when `debug_messages` is Some

#[macro_export]

macro_rules! debug_display_type {

    ($ctx:expr, $($arg:tt)*) => {

        if $ctx.debug_messages.is_some() {

            $ctx.debug_display_type_inner(format!($($arg)*));

        }

    };

}

use std::{collections::{BTreeMap, HashMap}, sync::Arc};

use azul_core::{

    dom::{DomId, NodeId},

    geom::{LogicalPosition, LogicalRect, LogicalSize},

    hit_test::{DocumentId, ScrollPosition},

    resources::RendererResources,

    selection::{TextCursor, TextSelection},

    styled_dom::StyledDom,

};

/// Sentinel value for "position not yet computed". No real position is ever `f32::MIN`.

pub(crate) const POSITION_UNSET: LogicalPosition = LogicalPosition { x: f32::MIN, y: f32::MIN };

/// Maximum number of scrollbar-induced reflow iterations before layout gives up.

/// Scrollbar appearance can change container size, which may trigger further scrollbar

/// changes. This limit prevents infinite loops in pathological layouts.

const MAX_SCROLLBAR_REFLOW_ITERATIONS: usize = 10;

/// Vec-based position storage indexed by layout-tree node index.

/// Replaces `BTreeMap<usize, LogicalPosition>` for O(1) access and cache-friendly iteration.

pub type PositionVec = Vec<LogicalPosition>;

/// Get position for node index, returning None if unset.

///

/// Note: only the `x` component is checked against the sentinel. This is sufficient

/// because `POSITION_UNSET` always sets both `x` and `y` to `f32::MIN`, and `pos_set`

/// always writes both components together.

#[inline]

/// Set position for node index. Grows the vec if needed.

#[inline]

/// Check if position has been set for node index.

#[inline]

use azul_css::{

    props::property::{CssProperty, CssPropertyCategory},

    LayoutDebugMessage, LayoutDebugMessageType,

};

use self::{

    display_list::generate_display_list,

    geometry::IntrinsicSizes,

    getters::get_writing_mode,

    layout_tree::{generate_layout_tree, LayoutTree},

    sizing::calculate_intrinsic_sizes,

};

#[cfg(feature = "text_layout")]

pub use crate::font_traits::TextLayoutCache;

use crate::{

    font_traits::ParsedFontTrait,

    solver3::{

        cache::LayoutCache,

        display_list::DisplayList,

        fc::LayoutConstraints,

        layout_tree::DirtyFlag,

    },

};

/// Central context for a single layout pass.

#[derive(Debug)]

pub struct LayoutContext<'a, T: ParsedFontTrait> {

    pub styled_dom: &'a StyledDom,

    /// Per-document memo for [`crate::solver3::getters::get_style_properties`].

    ///

    /// Resolving a node's style allocates ~6.5 KB (a font stack of heap

    /// `String`s, a background-content Vec, a font-features Vec, a cloned

    /// family list), and the sizing pass and the inline-layout pass each

    /// resolve the same node independently. heaptrack measured 6.33 MB of

    /// peak heap over 966 calls on a 3-page document.

    ///

    /// It lives HERE, on the context, so its lifetime is exactly the

    /// document's. An earlier attempt used a thread-local keyed on

    /// `ptr::from_ref(styled_dom)`, which passed every library test and

    /// reddened sixteen reftests: a `StyledDom` is dropped and the next one

    /// reuses the address, so the second document was served the first

    /// one's styles. Ownership makes that unrepresentable rather than

    /// merely unlikely.

    pub style_cache: getters::StyleCache,

    #[cfg(feature = "text_layout")]

    pub font_manager: &'a crate::font_traits::FontManager<T>,

    #[cfg(not(feature = "text_layout"))]

    pub font_manager: core::marker::PhantomData<&'a T>,

    /// Text selections for rendering highlights. Populated from `MultiCursorState`.

    pub text_selections: &'a BTreeMap<DomId, TextSelection>,

    pub debug_messages: &'a mut Option<Vec<LayoutDebugMessage>>,

    pub counters: &'a mut HashMap<(usize, String), i32>,

    pub viewport_size: LogicalSize,

    /// Fragmentation context for CSS Paged Media (PDF generation)

    /// When Some, layout respects page boundaries and generates one `DisplayList` per page

    pub fragmentation_context: Option<&'a mut crate::paged::FragmentationContext>,

    /// Per-pass record: layout-tree indices of IFC roots whose LINE LAYOUT

    /// was recomputed this pass (`layout_flow` ran — `GlyphSwap` reuse does

    /// NOT count). The DL-patching invalidation signal: a re-flowed IFC's

    /// text items changed shape and must re-emit; everything else can be

    /// copied+translated. Drained into the patch machinery by

    /// `layout_document`; empty on GlyphSwap-only passes.

    pub reflowed_ifcs: std::collections::BTreeSet<usize>,

    /// Whether the text cursor should be drawn (managed by `CursorManager` blink timer)

    /// When false, the cursor is in the "off" phase of blinking and should not be rendered.

    /// When true (default), the cursor is visible.

    pub cursor_is_visible: bool,

    /// All active cursor locations from `MultiCursorState` / `CursorManager`.

    /// Each entry is (`dom_id`, `node_id`, cursor). Multiple entries = multi-cursor mode.

    /// Empty = no active cursor. The last entry is the primary cursor.

    pub cursor_locations: Vec<(DomId, NodeId, TextCursor)>,

    /// IME preedit (composition) text to render inline at the cursor position.

    /// When Some, the text should be rendered with an underline decoration.

    pub preedit_text: Option<String>,

    /// Per-node multi-slot cache (Taffy-inspired 9+1 architecture).

    /// Moved out of `LayoutCache` via `std::mem::take` for the duration of layout,

    /// then moved back after the layout pass completes.

    pub cache_map: cache::LayoutCacheMap,

    /// Image cache for resolving `background-image: url(...)` references.

    pub image_cache: &'a azul_core::resources::ImageCache,

    /// Content overlay for resolving quickly-mutable node content (swapped

    /// images, produced callback frames): readers resolve overlay→DOM via

    /// [`crate::overlay::ResolvedContent`]. `None` outside a live window

    /// (standalone paged/PDF layout, unit tests) — the DOM is then authoritative.

    pub content_overlay: Option<&'a crate::overlay::ContentOverlay>,

    /// System style containing colors, fonts, metrics, and theme information.

    /// Used for selection colors, caret styling, and other system-themed elements.

    pub system_style: Option<std::sync::Arc<azul_css::system::SystemStyle>>,

    /// Callback to get the current system time. Used for profiling inside layout.

    /// On WASM targets (where `std::time::Instant::now()` panics), callers should

    /// supply a no-op or platform-specific implementation.

    pub get_system_time_fn: azul_core::task::GetSystemTimeCallback,

    /// Memoised `get_scrollbar_style` results, keyed by DOM node id.

    /// `compute_scrollbar_info_core` is called many times per node

    /// per layout pass (BFC path + Taffy flex/grid path + display

    /// list), and each call previously did 9 cascade walks. Once

    /// populated, subsequent callers in the same `LayoutContext`

    /// (a single render) return a clone.

    ///

    /// Uses `RefCell` so shared `&self` borrows (e.g. in the Taffy

    /// bridge's `get_core_container_style`) can mutate the cache

    /// without lifting the ctx to `&mut`. Keyed by `NodeId` so

    /// entries span DOMs in iframe-style nested documents if that

    /// ever becomes a thing.

    pub scrollbar_style_cache:

        core::cell::RefCell<HashMap<NodeId, getters::ComputedScrollbarStyle>>,

}

impl<T: ParsedFontTrait> LayoutContext<'_, T> {

    /// The one overlay→DOM content read order for this context's DOM.

    /// Layout (intrinsic sizing) and display-list build resolve node content

    /// exclusively through this — never via `NodeType::Image` directly.

    #[must_use]

    /// Internal method - called by `debug_log`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_info`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_warning`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_error`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_box_props`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_css_getter`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_bfc_layout`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_ifc_layout`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_table_layout`! macro after checking `debug_messages.is_some()`

    #[inline]

    /// Internal method - called by `debug_display_type`! macro after checking `debug_messages.is_some()`

    #[inline]

}

/// Main entry point for the incremental, cached layout engine.

///

/// `new_dom` is borrowed, not owned — every use inside is `&new_dom`,

/// so taking ownership was a pure formality that forced every caller

/// to `styled_dom.clone()` the DOM before calling. The clone was

/// ~2 MiB per render on excel.html; kept at the borrow now.

#[cfg(feature = "text_layout")]

/// Web-backend opt-out for display-list generation.

///

/// When set, [`layout_document`] runs the full positioning pipeline

/// (intrinsic sizing, taffy block/flex/grid, relative/sticky/absolute

/// adjustment → `calculated_positions`) but **skips

/// `generate_display_list`**, returning an empty [`DisplayList`]. The

/// web backend emits TLV DOM patches, not a display list, so it needs

/// the geometry in `calculated_positions` but nothing the painter

/// produces. This also lets the AArch64→wasm lift drop the entire

/// `display_list` painter surface (those symbols are classified `Leaf`

/// in `dll/src/web/symbol_table.rs::classify_for_name`, so the

/// transitive lifter never descends into them). Defaults `false` →

/// desktop/native behaviour is unchanged.

pub static SKIP_DISPLAY_LIST: core::sync::atomic::AtomicBool =

    core::sync::atomic::AtomicBool::new(false);

/// Set [`SKIP_DISPLAY_LIST`].

///

/// Provided as a function (rather than the

/// caller touching the static directly) so the web backend's

/// `dll`-crate caller reaches it through a normal `bl` into this

/// `azul_layout` function — keeping the static's address computation

/// intra-crate (direct `adrp+add`) instead of a cross-crate GOT load,

/// which the AArch64→wasm lift mirrors more reliably.

// M12.7: keep this out-of-line so the web lift sees it as its own wasm fn

// (not inlined into layout_dom_recursive). An opt-folded infinite loop in the

// solver (a mis-lifted loop exit) is otherwise hidden inside the giant inlined

// layout_dom_recursive; de-inlining lets AZ_FUEL/AZ_WASM_DEBUG name the actual

// source fn — and may itself prevent the inlining-induced fold. No perf cost on

// desktop (called once per layout).

#[inline(never)]

// node counts / indices / tree-len values fed to az_mark debug markers as u32; bounded.

#[allow(clippy::cast_possible_truncation)]

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

/// # Errors

///

/// Returns a `LayoutError` if document layout fails.

    use crate::window::LayoutWindow;

    // Secondary mapping: anonymous wrappers (dom_node_id == None)

    // by (parent_new_idx, ordinal-among-anon-siblings). An

    // unchanged DOM produces the same anon wrappers in the same

    // order under the same parent — matching by position here

    // preserves their cache slots too. Without this, anon

    // wrappers re-allocate empty every reconcile and invalidate

    // their ancestors via `mark_dirty`.

        }

    // Reset IFC ID counter at the start of each layout pass

    // This ensures IFCs get consistent IDs across frames when the DOM structure is stable

    // in layout_document returns the rc=5 Err (the error enum can't be captured

    // reliably in the lift). The last value seen = the step that errored next.

    // If 0 here → the LogicalRect HFA arg was lost across the lifted call.

    // Create temporary context without counters for tree generation

    // --- Step 0: record DOM pointer / viewport for diagnostics only ---

    //

    // NOTE: there is intentionally NO pointer-identity fast path here.

    // Comparing `new_dom as *const StyledDom as usize` against a stored

    // pointer is UNSOUND across layout passes: each `regenerate_layout`

    // builds a fresh `StyledDom`, and after the previous one is dropped

    // (e.g. `layout_and_generate_display_list` calls `layout_results.clear()`

    // before re-laying out), the allocator/stack frequently hands the new,

    // *different* StyledDom the SAME address. A pointer match therefore does

    // NOT prove the content is unchanged — it would return the previous

    // frame's display list for a structurally different DOM (e.g. an image

    // removed from the tree would still appear in `scan_used_images`,

    // breaking resource GC). The Step 1.1 structural-identity cache below

    // (root `subtree_hash` + viewport) is the correct, content-based skip;

    // it costs one ~600 µs reconcile pass but cannot be fooled by address

    // reuse.

    // --- Step 1: Reconciliation & Invalidation ---

    // RESIZE-ONLY SKIP: the incremental-relayout resize path hands solver3

    // the SAME StyledDom object with zero DOM/style dirt — the viewport is

    // the only delta. Reconcile would walk 1209 nodes to rediscover

    // "everything reused, nothing dirty" (~9.6 ms/pass on big.md) and the

    // cache_map remap would rebuild an identity mapping. Take the retained

    // tree as-is instead: indices are unchanged (so the per-node size/layout

    // caches keep working WITHOUT a remap), layout_roots={root} re-runs the

    // top-down pass at the new size, and the censuses read full-reuse. The

    // hint is a one-shot latch set ONLY by the resize-latch call sites

    // (common/layout.rs incremental_relayout_for_resize); restyle-driven

    // incremental relayouts keep full reconcile — they NEED its fingerprint

    // diff for paint-dirty classification. The dom-id sanity check guards

    // against a stale hint meeting a swapped DOM.

        // DL-patching input: the sizes the PREVIOUS pass computed — the

        // layout pass below overwrites used_size in place (same tree

        // object), so this is the only moment they can be captured.

    } else {

        // DL-patching input for the STRUCTURE-PRESERVED case (a text edit):

        // the sizes the previous pass computed, captured before reconcile

        // consumes the old tree.

    };

    // The reuse census, persisted where a test can read it — see the field

    // docs on LayoutCache for why this pair is the ONLY external observable

    // that distinguishes "reused the warm tree" from "rebuilt it from

    // scratch" (both produce identical pixels).

    // Structure preserved = the same-shaped tree: full reuse+fresh

    // accounting at an UNCHANGED node count (content changes make their

    // node FRESH — a text edit — but assign the same indices in the same

    // traversal; adds/removes change the count and disqualify). Fresh nodes

    // are force-re-emitted by the DL patch below, so a same-count REPLACE is

    // sound too: its new content never splices stale items.

    // [g56 FIX] Box the LayoutTree onto the HEAP. The lifted `&mut new_tree` passed to

    // calculate_intrinsic_sizes was mis-lifted (callee saw nodes.len()=0 while the caller saw 2)

    // because a stack/SROA'd `new_tree`'s address doesn't survive the cross-function lifted call

    // (taking `&new_tree` lifted to 0x0). A heap allocation has a stable absolute wasm address

    // that lifts reliably (cf. M8.4 "heap allocations work fine"). Deref coercion handles the

    // `&new_tree`/`&mut new_tree`/`new_tree.field` sites unchanged.

    // [az-diag g51 REVERT] 0x71 = reconcile_and_invalidate returned OK (no InvalidTree in reconcile).

    // [az-diag g54 REVERT] 0x40740 = new_tree.nodes.len() RIGHT AFTER reconcile. If 0 → reconcile

    // built an empty LayoutTree (the bug is in reconcile_recursive/create_node_from_dom). If 2 →

    // reconcile is fine and the tree gets emptied/mis-lifted downstream (check 0x40744 at the loop).

    // --- Step 1.1: Structural-identity display-list cache ---

    //

    // If the reconciled root subtree_hash matches the cached one AND

    // the viewport is unchanged, nothing structural has moved — skip

    // layout, positioning, AND display-list generation and return

    // the cached display list verbatim.

    //

    // This fires on re-renders of an unchanged DOM: the reconcile

    // pass still walks and hashes the tree, but that's ~600 µs vs

    // the ~4 ms it would otherwise cost to re-emit the display list.

    {

        // The GPU-KEY-POPULATION fingerprint is the third key component. The

        // emitted list is a function of which nodes carry transform/opacity

        // keys (`PushReferenceFrame` exists exactly for keyed nodes), and

        // diff-driven animation mints its keys AFTER the first layout — so on

        // (hash, viewport) alone this hit served the PRE-KEY list back:

        // no reference frames, no GPU damage, a frozen animation. Population

        // only, not values: values change every tick, and serving this cached

        // list across ticks while values flow through the GPU channel is the

        // point of the design.

        {

            #[cfg(feature = "std")]

            // The served list is IDENTICAL to the previous frame — this is

            // NOT a splice. Left stale from the last real build, the

            // renderers' patched-build damage override would replay the old

            // patch rects on an idle frame (op_add_remove_timer step 30:

            // expected no damage, got rects).

    // --- Step 1.15: fold the CSS DIFF into the solver's dirtiness ---

    //

    // Mirrors the reconcile classifier exactly (layout-affecting ->

    // intrinsic_dirty + layout_roots, the same pair a DirtyFlag::Layout node

    // gets). Paint-only entries (`RelayoutScope::None`) deliberately insert

    // NOTHING: with the Step 1.1 cache bypassed above, a clean reconcile

    // falls into the early-exit below, which reuses the whole tree and

    // re-emits the display list from the NEW styled_dom — repaint with zero

    // layout work. IfcOnly is treated as SizingOnly: over-invalidation is

    // correct (the IFC re-shapes inside the sizing pass); under-invalidation

    // is the 200px bug.

            }

            }

    // Step 1.2: Clear Taffy Caches for Dirty Nodes — and their ANCESTORS.

    //

    // The per-node `taffy_cache` persists across passes (it rides the warm

    // carry), keyed by taffy on (known_dimensions, available_space,

    // run_mode). Input changes miss by key on their own; what the key can

    // NOT see is a content change INSIDE the measured subtree — a deep text

    // edit changes what a flex item measures to at the SAME inputs. The

    // dirty node alone isn't enough: every ancestor's measure derives from

    // it, so the closure must be cleared (same propagation rule as

    // `calculate_intrinsic_sizes`' dirty_closure).

    //

    // This closure-clear is what made it safe to DELETE the unconditional

    // "clear every child before every flex layout" hammer in

    // `layout_taffy_subtree` (taffy_bridge.rs, from Nov 2025 — it predates

    // reconcile-driven dirtiness and was forcing 312 min/max-content

    // subtree re-layouts per pass on big.md, ~40% of a steady resize).

    {

        );

        }

    }

    // Step 1.3: Compute CSS Counters

    // This must be done after tree generation but before layout,

    // as list markers need counter values during formatting context layout

    // [az-diag g51 REVERT] 0x72 = compute_counters done (InvalidTree, if any, is after here).

    // Step 1.4: Resize and invalidate per-node cache (Taffy-inspired 9+1 slot cache)

    // Move cache_map out of LayoutCache for the duration of layout (avoids borrow conflicts).

    // It will be moved back after the layout pass completes.

    //

    // Critically: the old `cache_map.entries` is indexed by OLD

    // layout-tree positions. The NEW tree may have re-ordered

    // indices (anonymous wrapper slots shifted, whitespace nodes

    // dropped, etc.). A plain `resize_with(default)` would silently

    // serve the wrong node's cached result for any shifted index.

    //

    // Re-map by stable identity: build `old_layout_idx → new_layout_idx`

    // via the `(dom_node_id → layout_idx)` tables on both trees,

    // then move each surviving cache entry into its new slot. Nodes

    // without a matching DOM id (pure anonymous wrappers) fall

    // through to the default (empty, i.e. dirty) entry.

        // Primary mapping: DOM id → layout idx on both sides. This

        // covers every node that has a corresponding DOM node.

            };

                };

                {

            }

        }

        // Build old-parent → [old_anon_indices] and

        // new-parent → [new_anon_indices]; match by pair position.

        // For each new parent we know: look up its old twin by the

        // dom-id mapping we just populated, then match anon children

        // positionally within that parent.

        // Build a new→old layout-idx lookup from the primary pass.

            };

            }

        }

            };

            };

                };

                {

            }

        }

    // Now create the real context with computed counters

    // --- Step 1.5: Early Exit Optimization ---

    // M12.7: `&& cache.tree.is_some()` — this "nothing changed, reuse cached

    // layout" fast path REQUIRES a cached tree; on COLD layout cache.tree is

    // None, so entering here would hit `ok_or(InvalidTree)`. recon_result must

    // be dirty on cold (the viewport-resize dirties the root), but if

    // is_clean() mis-evaluates we'd wrongly early-exit → InvalidTree. Guarding

    // on a cached tree is both correct (can't reuse what isn't there) and

    // robust. (rc=5 post-reconcile, step=2: this was the failing `?`.)

        // The reuse census must describe THIS pass: zero sizing work, full

        // tree reuse. Leaving the previous pass's numbers in place made a

        // paint-only repaint look like it charged the cold pass's layout

        // work (the census is load-bearing — tests assert on it).

        // Use cached scroll IDs if available, otherwise compute them

            use crate::window::LayoutWindow;

        } else {

        };

        )

        // Refresh the structural-identity cache with what was JUST emitted.

        // This early exit re-emits precisely because something the cache key

        // could not see changed (a paint-only CSS diff, a GPU-key mint):

        // leaving the old entry in place would serve STALE PAINT on the next

        // call, and not storing at all would re-emit every frame for the

        // whole life of an animation.

        // Full re-emit, not a splice — clear the patched-build flags so the

        // renderers' damage override cannot replay stale patch rects.

    // [az-diag g51 REVERT] 0x80 = reached the incremental layout loop (past early-exit + remap + dirty loops).

    // [az-diag g65 PATH-B VALIDATION] new_tree is still valid here (=2). Clone it into the HEAP-backed

    // cache.tree (set AFTER the remap+early-exit which read the OLD cache.tree). cache is the stable

    // &mut arg (read correctly throughout), so cache.tree is NOT a deep-SP-relative stack local. At the

    // sizing call we read BOTH: stack new_tree (expect 0=corrupted) vs heap cache.tree (expect 2 if

    // path B sidesteps the SP-drift/wild-store). If heap=2, the full cache.tree refactor will fix it.

    // [az-diag g66] disambiguate the g65 heap=1: read BOTH right after the clone. 0x407C0 = stack

    // new_tree.nodes.len() (source), 0x407C4 = clone cache.tree.nodes.len(). If src=2 & clone=1 →

    // Vec::clone MIS-LIFTS (drops a node) → the full MOVE-based cache.tree refactor avoids it (do it).

    // If src=1=clone → corruption already reached line 758 (heisenbug) → move won't help.

    unsafe {

    }

    // --- Step 2: Incremental Layout Loop (handles scrollbar-induced reflows) ---

    loop {

        };

        // [az-diag g70 RELIABLE free-band] 0x60780 = nodes.len AFTER the in-loop calculated_positions.clone().

        {

            // [az-diag g70 RELIABLE free-band] 0x60784 = nodes.len AFTER reset_peak (before the calc Span).

            // [az-diag g70 RELIABLE free-band] 0x60788 = nodes.len AFTER the calc_intrinsic_sizes Span.

            // [az-diag g72 FIX] REMOVED the g48 `#[cfg(feature="web_lift")] panic!(...)` that lived

            // here. web-transpiler => azul-layout?/web_lift IS enabled (dll/Cargo.toml:651), so this

            // panic WAS compiled in, and with `-Z build-std-features=panic_immediate_abort` it lowered

            // to a bare `brk #0x1` right after the 0x90 marker — aborting BEFORE calculate_intrinsic_sizes.

            // The whole-session "new_tree 2→0 corruption" was a MIRAGE: the beforeCall marker store was

            // dead-code-eliminated (after the abort), so the harness read uninitialized 0, not a corrupted

            // tree. Native disasm of layout_document proved it: 0x90 marker store → `brk #0x1` → no `bl

            // calculate_intrinsic_sizes` anywhere. (The prior "string absent ⇒ web_lift off" check was

            // wrong — panic_immediate_abort strips the message string.)

            // [az-diag g65 PATH-B VALIDATION] 0x40748 = stack new_tree.nodes.len() (expect 0),

            // 0x4074C = HEAP cache.tree.nodes.len() (expect 2 if path B sidesteps the corruption).

            unsafe {

            }

        }

        // divergence is inside calculate_intrinsic_sizes (the SIMD/text intrinsic pass).

            // 0x05, the divergence is INSIDE get_containing_block_for_node (or the for-loop

            // entry); if 0x53 but not 0x55, it's the margin logic / box_props.unpack below.

            // get_containing_block_for_node(viewport)). 800 here but viewport=800 ⟹ OK;

            // 0 here with viewport=800 ⟹ get_containing_block_for_node lost it (HFA return).

            // For ROOT nodes (no parent), we need to account for their margin.

            // The containing block position from viewport is (0, 0), but the root's

            // content starts at (margin + border + padding, margin + border + padding).

            // We pass margin-adjusted position so calculate_content_box_pos works correctly.

                )

            } else {

            };

            // DEBUG: Log containing block info for this root

                        root_idx,

                        dom_name,

                        cb_pos.x,

                        cb_pos.y,

                        adjusted_cb_pos.x,

                        adjusted_cb_pos.y,

                        cb_size.width,

                        cb_size.height,

                        viewport.size.width,

                        viewport.size.height,

                        root_bp.margin.left,

                        root_bp.margin.top

                    ),

                ));

            // Purge after intrinsic sizing — frees child_intrinsics Vecs,

            // IntrinsicSizeCalculator temporaries, text measurement caches.

            // 0x57 = it RETURNED. If step stays 0x55, calculate_layout_for_subtree diverges.

            // This is exactly what calc_used_size reads as `viewport`. 0 here pinpoints the

            // loss to the ctx build (viewport.size → ctx.viewport_size copy).

            // 0x5E = Err. Do NOT propagate (continue to the cache store) so layout-real can

            // see whether the geometry was computed regardless of a (possibly spurious,

            // niche-Result-mis-discriminated) Err.

                )

            };

            // CRITICAL: Insert the root node's own position into calculated_positions

            // This is necessary because calculate_layout_for_subtree only inserts

            // positions for children, not for the root itself.

            //

            // For root nodes, the position should be at (margin.left, margin.top) relative

            // to the viewport origin, because the margin creates space between the viewport

            // edge and the element's border-box.

                // Calculate the root's border-box position by adding margins to viewport origin

                // This is different from non-root nodes which inherit their position from

                // their containing block.

                );

                // DEBUG: Log root positioning

                            root_idx,

                            dom_name,

                            root_position.x,

                            root_position.y,

                            root_bp2.margin.top,

                            root_bp2.margin.right,

                            root_bp2.margin.bottom,

                            root_bp2.margin.left

                        ),

                    ));

        }

        // (step 6). If step stays 5, the divergence is in calculate_layout_for_subtree.

                loop_count

            );

            // Deliberately NOT touching intrinsic_dirty. A scrollbar toggle

            // changes AVAILABLE SPACE (container inner width shrinks/grows by

            // scrollbar_width); intrinsic min/max-content widths are CONTENT-

            // derived and cannot change because a scrollbar appeared. This

            // line used to mark EVERY node intrinsic-dirty

            // (`(0..nodes.len()).collect()`), so any resize that toggled a

            // scrollbar re-measured the whole document's intrinsics — 75 ms

            // of the measured 166 ms on big.md's first in-range resize, and

            // the same sledgehammer pattern as the old drop-the-tree-on-

            // viewport-change. Nodes whose intrinsics genuinely changed are

            // already in the set from reconciliation; the root layout_root

            // above re-resolves every SIZE against the new inner width.

    }

    // +spec:positioning:8d1286 - normal flow, relative, float, absolute positioning dispatch

    // +spec:positioning:bdfc81 - Layout divided into sizing (Step 2) then positioning (Step 3)

    // --- Step 3: Adjust Relatively Positioned Elements ---

    // +spec:positioning:a831e8 - inline content width uses pre-relative-offset positions (satisfied by post-layout relative adjustment)

    // +spec:positioning:e2647b - Relative positioning applied after line height calculation, so line height is not adjusted for relative offsets

    // +spec:positioning:77a2d2 - Relatively positioned boxes considered without their offset during auto height

    // +spec:positioning:b47ac2 - Relatively positioned boxes considered without their offset for block auto height

    // Relative offsets applied AFTER layout, so auto-height calculation sees normal-flow positions.

    // This must be done BEFORE positioning out-of-flow elements, because

    // relatively positioned elements establish containing blocks for their

    // absolutely positioned descendants. If we adjust relative positions after

    // positioning absolute elements, the absolute elements will be positioned

    // relative to the wrong (pre-adjustment) position of their containing block.

    // Pass the viewport to correctly resolve percentage offsets for the root element.

    // --- Step 3.25: Adjust Sticky Positioned Elements ---

    // Sticky elements are laid out in normal flow, then their visual position

    // is clamped based on scroll offset and inset properties relative to the

    // nearest scrollport. Must happen after relative positioning but before

    // absolute positioning (sticky elements establish containing blocks).

    // --- Step 3.5: Position Out-of-Flow Elements ---

    // This must be done AFTER adjusting relative positions, so that absolutely

    // positioned elements are positioned relative to the final (post-adjustment)

    // position of their relatively positioned containing blocks.

    // --- Step 3.75: Compute Stable Scroll IDs ---

    // This must be done AFTER layout but BEFORE display list generation

    // --- Step 4: Generate Display List & Update Cache ---

    // (changed-node set, geometry-base rects) of a PATCHED build; consumed

    // after the final list exists to add the changed nodes' ITEM visual

    // bounds from both the old and the new list (shadow fringes).

        // Web backend: positions are done; the painter is dead weight.

    } else {

        // DL PATCHING (task 12 round 2): on a resize-skip pass the tree

        // object and its indices are unchanged, so the previous display

        // list's per-node item runs can substitute for the paint calls of

        // every node that neither re-flowed its inline content nor changed

        // size — their items just translate by the node's position delta.

        // `AZ_NO_DL_PATCH=1` is the runtime escape hatch (and the A/B lever

        // for the golden-equality test).

        // Two ways in: the resize-skip pass (same tree object), or a

        // STRUCTURE-PRESERVED reconcile with no CSS dirt — a text edit

        // reflowed its IFC, everything else splices (per-IFC text patching,

        // USER mandate 2026-08-17). CSS-dirty passes must not splice: their

        // items changed paint without reflowing.

        // Cascade-context equality: an @media/theme/OS flip restyles REUSED

        // nodes without touching NodeData or css_dirty (the reconcile is

        // blind to the cascade), so the structure-preserved arm must also

        // prove the context the cached DL was built under is unchanged.

        // The resize-skip arm keeps its own contract (the harvested

        // breakpoints guarantee no answer flips between crossings).

            #[cfg(feature = "std")]

                            a.viewport_width, b.viewport_width,

                            a.viewport_height, b.viewport_height,

                            a.window_focused, b.window_focused,

                        );

                    }

                }

            }

        };

        #[cfg(feature = "std")]