//! Window layout management for solver3/text3

//!

//! This module provides the high-level API for managing layout

//! state across frames, including caching, incremental updates,

//! and display list generation.

//!

//! The main entry point is `LayoutWindow`, which encapsulates all

//! the state needed to perform layout and maintain consistency

//! across window resizes and DOM updates.

//!

//! Key subsystems managed by `LayoutWindow`:

//! - **Text editing**: cursor/selection management, IME preedit,

//!   undo/redo, and incremental text relayout

//! - **Accessibility**: tree construction and incremental updates

//!   for screen readers via accesskit

//! - **VirtualView**: callback invocation and recursive layout for

//!   virtualized scrollable content

//! - **Scrolling**: scroll state, scrollbar opacity, and

//!   scroll-into-view for cursors and selections

use std::{

    collections::{BTreeMap, BTreeSet, HashMap},

    sync::{

        atomic::{AtomicUsize, Ordering},

        Arc,

    },

};

use azul_core::{

    animation::UpdateImageType,

    callbacks::{FocusTarget, HidpiAdjustedBounds, VirtualViewCallbackReason, Update},

    dom::{

        AccessibilityAction, AttributeType, Dom, DomId, DomIdVec, DomNodeId, NodeId, NodeType, On,

    },

    events::{EasingFunction, EventFilter, FocusEventFilter, HoverEventFilter},

    geom::{LogicalPosition, LogicalRect, LogicalSize, OptionLogicalPosition},

    gl::OptionGlContextPtr,

    gpu::{GpuScrollbarOpacityEvent, GpuValueCache},

    hit_test::{DocumentId, ScrollPosition, ScrollbarHitId},

    refany::{OptionRefAny, RefAny},

    resources::{

        Epoch, FontKey, GlTextureCache, IdNamespace, ImageCache, ImageMask, ImageRef, ImageRefHash,

        OpacityKey, RendererResources,

    },

    selection::{

        CursorAffinity, GraphemeClusterId, Selection, SelectionAnchor, SelectionFocus,

        SelectionRange, SelectionState, TextCursor, TextSelection,

    },

    styled_dom::{

        collect_nodes_in_document_order, is_before_in_document_order, NodeHierarchyItemId,

        StyledDom,

    },

    task::{

        Duration, Instant, SystemTickDiff, SystemTimeDiff, TerminateTimer, ThreadId, ThreadIdVec,

        ThreadSendMsg, TimerId, TimerIdVec,

    },

    window::{CursorPosition, MonitorVec, RawWindowHandle, RendererType},

    FastBTreeSet, OrderedMap,

};

use azul_css::{

    css::Css,

    props::{

        basic::FontRef,

        property::{CssProperty, CssPropertyVec},

    },

    AzString, LayoutDebugMessage, OptionString,

};

use rust_fontconfig::FcFontCache;

#[cfg(feature = "icu")]

use crate::icu::IcuLocalizerHandle;

use crate::{

    callbacks::{

        Callback, ExternalSystemCallbacks, MenuCallback,

    },

    managers::{

        gpu_state::GpuStateManager,

        virtual_view::VirtualViewManager,

        scroll_state::{ScrollManager, ScrollStates},

    },

    solver3::{

        self, cache::LayoutCache as Solver3LayoutCache, display_list::DisplayList,

        layout_tree::LayoutTree,

    },

    text3::{

        cache::{

            FontManager, FontSelector, FontStyle, InlineContent, TextShapingCache as TextLayoutCache,

            LayoutError, ShapedItem, StyleProperties, StyledRun, TextBoundary, UnifiedConstraints,

            UnifiedLayout,

        },

        default::PathLoader,

    },

    thread::{OptionThreadReceiveMsg, Thread, ThreadReceiveMsg, ThreadWriteBackMsg},

    timer::Timer,

    window_state::{FullWindowState, WindowCreateOptions},

};

// Global atomic counters for generating unique IDs

static DOCUMENT_ID_COUNTER: AtomicUsize = AtomicUsize::new(0);

static ID_NAMESPACE_COUNTER: AtomicUsize = AtomicUsize::new(0);

/// Helper function to create a unique DocumentId

/// Direction for cursor navigation

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

pub enum CursorNavigationDirection {

    /// Move cursor up one line

    Up,

    /// Move cursor down one line

    Down,

    /// Move cursor left one character

    Left,

    /// Move cursor right one character

    Right,

    /// Move cursor to start of current line

    LineStart,

    /// Move cursor to end of current line

    LineEnd,

    /// Move cursor to start of document

    DocumentStart,

    /// Move cursor to end of document

    DocumentEnd,

}

/// Result of a cursor movement operation

#[derive(Debug, Clone)]

pub enum CursorMovementResult {

    /// Cursor moved within the same text node

    MovedWithinNode(TextCursor),

    /// Cursor moved to a different text node

    MovedToNode {

        dom_id: DomId,

        node_id: NodeId,

        cursor: TextCursor,

    },

    /// Cursor is at a boundary and cannot move further

    AtBoundary {

        boundary: TextBoundary,

        cursor: TextCursor,

    },

}

/// Error when no cursor destination is available

#[derive(Debug, Clone)]

pub struct NoCursorDestination {

    pub reason: String,

}

/// Action to take for the cursor blink timer when focus changes

///

/// This enum is returned by `LayoutWindow::handle_focus_change_for_cursor_blink()`

/// to tell the platform layer what timer action to take.

#[derive(Debug, Clone)]

pub enum CursorBlinkTimerAction {

    /// Start the cursor blink timer with the given timer configuration

    Start(crate::timer::Timer),

    /// Stop the cursor blink timer

    Stop,

    /// No change needed (timer already in correct state)

    NoChange,

}

/// Action for the tooltip-delay timer, returned by

/// `LayoutWindow::handle_hover_change_for_tooltip()`. Platform layer translates

/// these to `start_timer` / `stop_timer` calls on `TOOLTIP_DELAY_TIMER_ID`.

#[derive(Debug, Clone)]

pub enum TooltipTimerAction {

    /// Start the tooltip-delay timer with the given configuration

    Start(crate::timer::Timer),

    /// Stop the tooltip-delay timer and hide the tooltip if shown

    Stop,

    /// No change needed (timer already in correct state)

    NoChange,

}

/// Helper function to create a unique IdNamespace

// ============================================================================

// Cursor Blink Timer Callback

// ============================================================================

/// Destructor for cursor blink timer RefAny (no-op since we use null pointer)

    // No cleanup needed - we use a null pointer RefAny

/// Callback for the cursor blink timer

///

/// This function is called every ~530ms to toggle cursor visibility.

/// It checks if enough time has passed since the last user input before blinking,

/// to avoid blinking while the user is actively typing.

///

/// The callback returns:

/// - `TerminateTimer::Continue` + `Update::RefreshDom` if cursor toggled

/// - `TerminateTimer::Terminate` if focus is no longer on a contenteditable element

    use azul_core::callbacks::{TimerCallbackReturn, Update};

    use azul_core::task::TerminateTimer;

    // Get current time

    // We need to access the LayoutWindow through the info

    // The timer callback needs to:

    // 1. Check if focus is still on a contenteditable element

    // 2. Check time since last input

    // 3. Toggle visibility or keep solid

    // For now, we'll queue changes via the CallbackInfo system

    // The actual state modification happens in apply_user_change

    // Check if we should blink or stay solid

    // This is done by checking CursorManager.should_blink(now) in the layout window

    // Since we can't access LayoutWindow directly here (it's not passed to timer callbacks),

    // we use a different approach: the timer callback always toggles, and the visibility

    // check is done in display_list.rs based on CursorManager state.

    // Simply toggle cursor visibility

    // Continue the timer and request a redraw.

    // DoNothing here because the SetCursorVisibility change (queued above)

    // already toggles blink state and returns ShouldUpdateDisplayListCurrentWindow,

    // which sets display_list_dirty. RefreshDom would trigger a full DOM rebuild

    // from the user callback; since the DOM is structurally unchanged (only cursor

    // visibility differs), is_layout_equivalent() returns LayoutUnchanged and the

    // display list change is lost.

// ============================================================================

// Tooltip Delay Timer Callback

// ============================================================================

/// Callback for the tooltip-delay timer.

///

/// Fires once after `InputMetrics::hover_time_ms` has elapsed while a node with

/// a tooltip-bearing attribute was continuously hovered. The callback looks up

/// the `title` / `aria-label` / `alt` attribute on the currently-hovered node,

/// emits a `ShowTooltip` CallbackChange, and terminates — a single-shot timer.

/// Movement to a different node (or any hover loss) removes and re-adds the

/// timer from the platform layer, so the callback itself never needs to

/// reschedule.

    use azul_core::callbacks::{TimerCallbackReturn, Update};

    use azul_core::task::TerminateTimer;

        // Priority: aria-label > alt > title (mirrors DOM get_accessible_label).

/// Result of a layout pass for a single DOM, before display list generation

#[derive(Debug)]

pub struct DomLayoutResult {

    /// The styled DOM that was laid out

    pub styled_dom: StyledDom,

    /// The layout tree with computed sizes and positions

    pub layout_tree: LayoutTree,

    /// Absolute positions of all nodes

    pub calculated_positions: crate::solver3::PositionVec,

    /// The viewport used for this layout

    pub viewport: LogicalRect,

    /// The generated display list for this DOM.

    pub display_list: DisplayList,

    /// Stable scroll IDs computed from node_data_hash

    /// Maps layout node index -> external scroll ID

    pub scroll_ids: HashMap<usize, u64>,

    /// Mapping from scroll IDs to DOM NodeIds for hit testing

    /// This allows us to map WebRender scroll IDs back to DOM nodes

    pub scroll_id_to_node_id: HashMap<u64, NodeId>,

}

/// State for tracking scrollbar drag interaction

#[derive(Debug, Clone)]

pub struct ScrollbarDragState {

    pub hit_id: ScrollbarHitId,

    pub initial_mouse_pos: LogicalPosition,

    pub initial_scroll_offset: LogicalPosition,

}

/// Information about the last text edit operation

/// Allows callbacks to query what changed during text input

// Re-export PendingTextEdit from text_input manager

pub use crate::managers::text_input::PendingTextEdit;

/// Cached text layout constraints for a node

/// These are the layout parameters that were used to shape the text

#[derive(Debug, Clone)]

pub struct TextConstraintsCache {

    /// Map from (dom_id, node_id) to their layout constraints

    pub constraints: BTreeMap<(DomId, NodeId), UnifiedConstraints>,

}

impl Default for TextConstraintsCache {

}

/// A text node that has been edited since the last full layout.

/// This allows us to perform lightweight relayout without rebuilding the entire DOM.

#[derive(Debug, Clone)]

pub struct DirtyTextNode {

    /// The new inline content (text + images) after editing

    pub content: Vec<InlineContent>,

    /// The new cursor position after editing

    pub cursor: Option<TextCursor>,

    /// Whether this edit requires ancestor relayout (e.g., text grew taller)

    pub needs_ancestor_relayout: bool,

}

/// Result of applying a text changeset

pub struct TextChangesetResult {

    /// Nodes that need dirty marking

    pub dirty_nodes: Vec<azul_core::dom::DomNodeId>,

    /// Whether the text size changed enough to require full re-layout

    /// (e.g., for scroll container recomputation)

    pub needs_relayout: bool,

}

/// A window-level layout manager that encapsulates all layout state and caching.

///

/// This struct owns the layout and text caches, and provides methods dir_to:

/// - Perform initial layout

/// - Incrementally update layout on DOM changes

/// - Generate display lists for rendering

/// - Handle window resizes efficiently

/// - Manage multiple DOMs (for VirtualViews)

pub struct LayoutWindow {

    /// M12.7 web/headless: skip the GPU transform/opacity sync in

    /// `layout_dom_recursive`. That sync only feeds the display list (which

    /// the web backend skips), has no GPU, and `GpuValueCache::synchronize`

    /// currently mis-lifts to wasm (out-of-bounds). Gated via this heap field

    /// (a normal struct read — reliable in the lift, unlike the

    /// `SKIP_DISPLAY_LIST` `__bss` static, whose store/load is inconsistent

    /// in the lifted wasm). Default false → desktop is unaffected.

    pub skip_gpu_sync: bool,

    /// Fragmentation context for this window (continuous for screen, paged for print)

    #[cfg(feature = "pdf")]

    pub fragmentation_context: crate::paged::FragmentationContext,

    /// Layout cache for solver3 (incremental layout tree) - for the root DOM

    pub layout_cache: Solver3LayoutCache,

    /// Text layout cache for text3 (shaped glyphs, line breaks, etc.)

    pub text_cache: TextLayoutCache,

    /// Font manager for loading and caching fonts

    pub font_manager: FontManager<FontRef>,

    /// Cache to store decoded images

    pub image_cache: ImageCache,

    /// CPU-backend resolution of `RenderImageCallback` images: the produced

    /// image for each callback-image node, keyed by the ORIGINAL callback

    /// image's hash. Populated by [`LayoutWindow::invoke_cpu_image_callbacks`]

    /// before each CPU `render_frame`; consumed by cpurender (which otherwise

    /// draws a grey placeholder for `DecodedImage::Callback`). Empty on the GPU

    /// path (WebRender invokes callbacks itself via `process_image_callback_updates`).

    pub cpu_image_callback_results: BTreeMap<ImageRefHash, ImageRef>,

    /// Cached layout results for all DOMs (root + virtualized views)

    pub layout_results: BTreeMap<DomId, DomLayoutResult>,

    /// Scroll state manager for all nodes across all DOMs

    pub scroll_manager: ScrollManager,

    /// Gesture and drag manager for multi-frame interactions (moved from FullWindowState)

    pub gesture_drag_manager: crate::managers::gesture::GestureAndDragManager,

    /// Focus manager for keyboard focus and tab navigation

    pub focus_manager: crate::managers::focus_cursor::FocusManager,

    /// Unified text editing manager (cursor + selection + dirty flag)

    pub text_edit_manager: crate::managers::text_edit::TextEditManager,

    /// File drop manager for cursor state and file drag-drop

    pub file_drop_manager: crate::managers::file_drop::FileDropManager,

    /// Clipboard manager for system clipboard integration

    pub clipboard_manager: crate::managers::clipboard::ClipboardManager,

    /// Drag-drop manager for node and file dragging operations

    pub drag_drop_manager: crate::managers::drag_drop::DragDropManager,

    /// Hover manager for tracking hit test history over multiple frames

    pub hover_manager: crate::managers::hover::HoverManager,

    /// VirtualView manager for all nodes across all DOMs

    pub virtual_view_manager: VirtualViewManager,

    /// GPU state manager for all nodes across all DOMs

    pub gpu_state_manager: GpuStateManager,

    /// Accessibility manager for screen reader support

    pub a11y_manager: crate::managers::a11y::A11yManager,

    /// Permission manager — cross-platform capability state for camera /

    /// microphone / geolocation / biometric / sensors / photo-library /

    /// notifications / etc. The platform backend drains

    /// `take_pending_permission_events` once per frame and routes each

    /// `Subscribe` / `Release` through `dll::desktop::extra::permission::apply_diff_events`.

    /// See `SUPER_PLAN_2.md` §1.5 + research/08 for the architecture.

    pub permission_manager: crate::managers::permission::PermissionManager,

    /// Geolocation manager — `LocationFix` storage + per-frame diff

    /// against the `NodeType::GeolocationProbe`s in the styled DOM.

    /// The platform backend (`dll::desktop::extra::geolocation`)

    /// drains diff events and starts / stops native

    /// `CLLocationManager` / `LocationManager` / `geoclue`

    /// subscriptions.

    pub geolocation_manager: crate::managers::geolocation::GeolocationManager,

    /// Cross-platform biometric-auth state — latest result + sync

    /// availability. The platform backend (`dll::desktop::extra::biometric`)

    /// shows the OS prompt and parks results in the async channel that the

    /// layout pass folds into this manager (request-driven; no probe node).

    pub biometric_manager: crate::managers::biometric::BiometricManager,

    /// Cross-platform keyring state — outcome of the last secret-store op.

    /// The platform backend (`dll::desktop::extra::keyring`) reads/writes

    /// the OS keyring (Keychain / KeyStore / libsecret / CredentialLocker)

    /// and parks results in the async channel the layout pass folds in here.

    pub keyring_manager: crate::managers::keyring::KeyringManager,

    /// Cross-platform motion-sensor state — latest accel / gyro / mag

    /// reading. The platform backend (`dll::desktop::extra::sensors`)

    /// subscribes to CoreMotion / Android `SensorManager` and parks

    /// readings in the async channel the layout pass folds in here.

    pub sensor_manager: crate::managers::sensors::SensorManager,

    /// Cross-platform gamepad / controller state. The dll's platform backend

    /// (gilrs / GCController / InputDevice) parks per-pad states in the async

    /// channel the layout pass folds in here.

    pub gamepad_manager: crate::managers::gamepad::GamepadManager,

    /// Safe-area insets (notch / system-UI margins) for this window, in logical

    /// px. Set by the platform shell (macOS NSScreen.safeAreaInsets, iOS

    /// UIView.safeAreaInsets, Android WindowInsets); zero where none.

    pub safe_area_insets: azul_css::system::SafeAreaInsets,

    /// Timers associated with this window

    pub timers: BTreeMap<TimerId, Timer>,

    /// Threads running in the background for this window

    pub threads: BTreeMap<ThreadId, Thread>,

    /// Currently loaded fonts and images present in this renderer (window)

    pub renderer_resources: RendererResources,

    /// Renderer type: Hardware-with-software-fallback, pure software or pure hardware renderer?

    pub renderer_type: Option<RendererType>,

    /// Windows state of the window of (current frame - 1): initialized to None on startup

    pub previous_window_state: Option<FullWindowState>,

    /// Window state of this current window (current frame): initialized to the state of

    /// WindowCreateOptions

    pub current_window_state: FullWindowState,

    /// A "document" in WebRender usually corresponds to one tab (i.e. in Azuls case, the whole

    /// window).

    pub document_id: DocumentId,

    /// ID namespace under which every font / image for this window is registered

    pub id_namespace: IdNamespace,

    /// The "epoch" is a frame counter, to remove outdated images, fonts and OpenGL textures when

    /// they're not in use anymore.

    pub epoch: Epoch,

    /// Currently GL textures inside the active CachedDisplayList

    pub gl_texture_cache: GlTextureCache,

    /// State for tracking scrollbar drag interaction

    currently_dragging_thumb: Option<ScrollbarDragState>,

    /// Text input manager - centralizes all text editing logic

    pub text_input_manager: crate::managers::text_input::TextInputManager,

    /// Undo/Redo manager for text editing operations

    pub undo_redo_manager: crate::managers::undo_redo::UndoRedoManager,

    /// Cached text layout constraints for each node

    /// This allows us to re-layout text with the same constraints after edits

    pub text_constraints_cache: TextConstraintsCache,

    /// Tracks which nodes have been edited since last full layout.

    /// Key: (DomId, NodeId of IFC root)

    /// Value: The edited inline content that should be used for relayout

    pub dirty_text_nodes: BTreeMap<(DomId, NodeId), DirtyTextNode>,

    /// Pending VirtualView updates from callbacks (processed in next frame)

    /// Map of DomId -> Set of NodeIds that need re-rendering

    pub pending_virtual_view_updates: BTreeMap<DomId, FastBTreeSet<NodeId>>,

    /// Lifecycle events produced by DOM reconciliation, waiting to be dispatched.

    ///

    /// `regenerate_layout` appends `diff::reconcile_dom`'s `DiffResult.events` here

    /// (Mount / Update / Resize SyntheticEvents — note: NOT Unmount; see

    /// `pending_unmount_invocations`). The shell's event loop drains and

    /// dispatches them via `dispatch_events_propagated`, which routes

    /// `EventFilter::Component(_)` filters through `matches_component_filter`.

    /// Drain-and-clear is the caller's responsibility; nothing inside

    /// `LayoutWindow` ages or discards these on its own.

    pub pending_lifecycle_events: Vec<azul_core::events::SyntheticEvent>,

    /// Resolved BeforeUnmount invocations queued for dispatch.

    ///

    /// Unmount events target OLD NodeIds that disappear once the new layout

    /// is committed to `layout_results`, so the shell cannot resolve them

    /// via DOM lookup at dispatch time. `regenerate_layout` resolves the

    /// callback against the OLD node data while it still has access, then

    /// pushes a `(CoreCallbackData, SyntheticEvent)` pair here. The shell's

    /// dispatcher invokes each pair directly.

    pub pending_unmount_invocations: Vec<(

        azul_core::callbacks::CoreCallbackData,

        azul_core::events::SyntheticEvent,

    )>,

    /// System style (colors, fonts, metrics) for resolving system color keywords

    /// Set via `set_system_style()` from the shell after window creation

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

    /// Shared monitor list — initialized once at app start, updated by the platform

    /// layer on monitor topology changes. Arc<Mutex> allows zero-cost sharing

    /// across all CallbackInfoRefData without cloning the Vec each time.

    pub monitors: std::sync::Arc<std::sync::Mutex<MonitorVec>>,

    /// XOR of all tier2b.font_family_hash values from the last resolved DOM.

    /// Used to skip font chain resolution on frames where the font requirements

    /// haven't changed (e.g. scroll-only frames).

    font_stacks_hash: u64,

    /// Snapshot of inline content before IME preedit injection.

    /// Saved on first setMarkedText so each subsequent call injects into

    /// clean original text instead of accumulating old preedits.

    pre_preedit_content: Option<Vec<crate::text3::cache::InlineContent>>,

    /// Configurable input interpreter: maps raw events → SystemChange actions.

    /// Default: `default_input_interpreter` (standard desktop keybindings).

    /// Replace to implement vim, game controls, accessibility remaps, etc.

    pub input_interpreter: azul_core::events::InputInterpreterCallback,

    /// Configurable post-callback filter.

    /// Default: `default_post_filter` (scroll-into-view after cursor ops).

    pub post_filter: azul_core::events::PostFilterCallback,

    /// Registered routes from AppConfig.  Set once at window creation.

    /// Used by `CallbackChange::SwitchRoute` to look up layout callbacks.

    pub routes: azul_core::resources::RouteVec,

    /// ICU4X localizer handle for internationalized formatting (numbers, dates, lists, plurals)

    /// Initialized from system language at startup, can be overridden

    #[cfg(feature = "icu")]

    pub icu_localizer: IcuLocalizerHandle,

}

/// Helper function to convert Duration to milliseconds

///

/// Duration is an enum with System (std::time::Duration) and Tick variants.

/// We need to handle both cases for proper time calculations.

        #[cfg(feature = "std")]

        }

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

        Duration::System(system_diff) => {

            // Manual calculation: secs * 1000 + nanos / 1_000_000

            system_diff.secs * 1000 + (system_diff.nanos / 1_000_000) as u64

        }

            // Assume tick = 1ms for simplicity (platform-specific)

        }

    }

impl LayoutWindow {

    /// Create a new layout window with empty caches.

    ///

    /// For full initialization with WindowInternal compatibility, use `new_full()`.

    /// The single place every `LayoutWindow` field is initialized; the public

    /// constructors below are thin wrappers over this (deduplicated 2026-05-21,

    /// so adding a field touches one site instead of three).

    /// Create a new layout window with empty caches.

    ///

    /// For full initialization with WindowInternal compatibility, use `new_full()`.

    /// Create a new layout window that shares already-parsed fonts with

    /// Create a LayoutWindow from a `FontContext` — shares all font data,

    /// starts with fresh layout cache, text cache, and all other state.

    /// Create from shared fc_cache + parsed_fonts Arcs.

    /// Create a new layout window for paged media (PDF generation).

    ///

    /// This constructor initializes the layout window with a paged fragmentation context,

    /// which will cause content to flow across multiple pages instead of a single continuous

    /// scrollable container.

    ///

    /// # Arguments

    /// - `fc_cache`: Font configuration cache for font loading

    /// - `page_size`: The logical size of each page

    ///

    /// # Returns

    /// A new `LayoutWindow` configured for paged output, or an error if initialization fails.

    #[cfg(feature = "pdf")]

    pub fn new_paged(

        fc_cache: FcFontCache,

        page_size: LogicalSize,

    ) -> Result<Self, crate::solver3::LayoutError> {

        let mut lw = Self::from_font_manager(FontManager::new(fc_cache)?);

        lw.fragmentation_context = crate::paged::FragmentationContext::new_paged(page_size);

        Ok(lw)

    }

    /// Perform layout on a styled DOM and generate a display list.

    ///

    /// This is the main entry point for layout. It handles:

    /// - Incremental layout updates using the cached layout tree

    /// - Text shaping and line breaking

    /// - VirtualView callback invocation and recursive layout

    /// - Display list generation for rendering

    /// - Accessibility tree synchronization

    ///

    /// # Arguments

    /// - `styled_dom`: The styled DOM to layout

    /// - `window_state`: Current window dimensions and state

    /// - `renderer_resources`: Resources for image sizing etc.

    /// - `debug_messages`: Optional vector to collect debug/warning messages

    ///

    /// # Returns

    /// The display list ready for rendering, or an error if layout fails.

        // Clear previous results for a full relayout

        // CRITICAL: Reset VirtualView invocation flags so check_reinvoke() returns

        // InitialRender for every tracked VirtualView. Without this, the VirtualViewManager

        // still has was_invoked=true from the previous frame, so it skips

        // re-invocation — but the child DOM was just destroyed by clear().

        // Start recursive layout from the root DOM. Passes ownership — the

        // StyledDom ends up inside `layout_results` without a clone.

        );

        } else {

        }

        // After successful layout, update the accessibility tree

        #[cfg(feature = "a11y")]

        // After layout, automatically scroll cursor into view if there's a focused text input

    /// Run the real layout solver for a single StyledDom + viewport

    /// (taffy block/flex/grid → `layout_cache.calculated_positions`).

    ///

    /// Made `pub` for the web backend (`AzStartup_solveLayoutReal`),

    /// which lifts this from ARM to wasm to position the headless

    /// StyledDom. On web the display-list step inside `layout_document`

    /// is hot-patched out at lift time (web emits TLV patches, not a

    /// display list); positions are written to the cache *before* that

    /// step, so the lifted path still produces correct geometry.

        // Child DOMs (VirtualView / iframe) must NOT lay out into the root's

        // live cache: the impl below writes tree + calculated_positions into

        // `self.layout_cache`, so a child pass CLOBBERS the root's geometry —

        // `get_node_layout_rect` and the next incremental relayout then read

        // the child's tree instead of the root's (live bug: azul-maps' header

        // laid out 640x0/None → toolbar invisible and unclickable while the

        // map child DOM rendered fine). Children lay out cold by design, so

        // give a child a fresh scratch cache and restore the root's cache

        // afterwards; the per-DOM snapshot lives in `layout_results`. Nested

        // children stack their swaps.

            );

        )

        } else {

        };

        // Children enter with a fresh scratch cache (see the wrapper above);

        // reset_incremental() is kept as belt-and-braces for any direct

        // callers and is a no-op on a fresh cache.

        // Get the platform from system_style, falling back to compile-time detection

        // Font Resolution And Loading

        // This must happen BEFORE layout_document() is called

        {

            use crate::{

                solver3::getters::collect_and_resolve_font_chains_with_registration,

                text3::default::PathLoader,

            };

            // Per-node font dirty tracking (P4):

            // Check font_dirty_nodes populated by build_compact_cache(),

            // which compares each node's font_family_hash against the

            // previous frame. This replaces the collision-prone global XOR

            // approach: XOR(a,b,a,b) == 0 even though fonts changed.

            //

            // Additional guard: compute an FxHash signature of

            // `prev_font_hashes` and compare against the one we stashed

            // after the last successful chain resolution. If it matches,

            // the DOM's font stacks are identical to what's already in

            // `font_chain_cache` — no resolver call needed. This catches

            // the common "repeated layout on unchanged DOM" case that

            // `font_dirty_nodes.len() == 0` misses, because the dirty

            // list is only re-computed inside `build_compact_cache`,

            // which most layouts do NOT re-run.

                // Fast polynomial rolling hash over the `prev_font_hashes`

                // slice. Mixes each u64 with a multiplier + bit-rotation,

                // which is collision-resistant enough for our one-at-a-time

                // "did this DOM's font stacks change" comparison and an

                // order of magnitude cheaper than SipHash for ~300 nodes.

            // Skip all font resolution steps if NO node's font_family_hash

            // changed AND the font_chain_cache has already been populated,

            // OR if the font-stacks signature matches the one we stashed

            // after the last successful resolution.

            } else {

                // Merge font hash→families from compact cache into FontManager

                // so the reverse map accumulates across DOMs.

                // Resolve chains (including the coverage-based prune

                // and the per-document scripts_hint), then delegate

                // the load-the-missing-ones dance to FontManager's

                // shared helper. Same logic that lives at

                // `FontContext::load_fonts_for_chains` and the CPU

                // rasterizer's preview pre-fill — one implementation,

                // three callers.

                    )

                };

                // [g80] localize where font_chain_cache drops to 0: chains right after collect_and_resolve.

                // WEB-LIFT last resort (the DEFINITIVE spot — the layout's own `chains` that

                // feed load_missing_for_chains below): the lifted font-query path can leave a

                // chain with NO fonts even when a fallback IS registered (generic→OS-name +

                // token/unicode query is lift-fragile). Append the first registered font to any

                // empty chain so load_missing loads it + text shapes instead of measuring 0.

                // Done here (azul-layout), NOT rust-fontconfig (which re-codegens the fragile

                // with_memory_fonts into a trapping shape).

                }

                // [g80] chains after the window.rs last-resort loop (values_mut path).

                // [az-web-lift 2026-06-05] REMOVED a WASM-ONLY diagnostic probe that computed

                // nchains/total_fonts/nreg here purely to write debug markers. Its

                // `chains.chains.values().map(|c| …).sum()` closure-iterator chain (and/or the

                // `fc_cache.list()` call) MIS-LIFTS on the web backend → memory-access-OOB → a

                // slice panic whose abort path spins in the OUTLINED_FUNCTION_2 dispatch (localized

                // via the 0x406C0=0xC0DE0007 marker: the explicit `for …values_mut()` loop ABOVE

                // lifts fine, only this closure-iterator form traps — same class as the css.rs

                // `map+collect → for-loop` lift fix). It was revert-able scaffolding; the chains

                // are sound (the for-loop iterated them), so load_missing_for_chains below proceeds.

                // Phase 3 (scout-on-demand): no snapshot-refresh

                // step is needed any more. rust-fontconfig 4.1

                // made `FcFontCache` a shared-state handle backed

                // by `Arc<RwLock<_>>`, so builder writes performed

                // during the `request_and_resolve_with_scripts`

                // call above are immediately visible to every

                // downstream `FontFallbackChain::resolve_char`

                // lookup without any explicit refresh.

                    )

                };

                // Step 5: Update font chain cache (and stash the

                // `prev_font_hashes` signature so the next layout with

                // an identical DOM skips the resolver entirely).

                // [g80] fc_chains after into_fontconfig_chains (the BTreeMap rebuild) — does it drop them?

                );

                // [g80] font_chain_cache right after set (does set_font_chain_cache_with_sig persist it?).

            }

        }

        // Synchronize CSS transform / opacity keys with the current StyledDom

        // BEFORE building the display list. `display_list.rs` reads

        // `css_transform_keys` / `css_current_transform_values` (and the

        // opacity equivalents) to emit reference frames and opacity stacking

        // contexts — these maps are only populated by

        // `GpuValueCache::synchronize`. The returned events are merged into

        // `gpu_state_manager.pending_changes` so the renderer can later push

        // matching WebRender transactions alongside scrollbar transform

        // events.

        // The GPU transform/opacity sync only feeds the display list

        // (reference frames + opacity stacking contexts read by

        // display_list.rs). The web backend skips the display list

        // (SKIP_DISPLAY_LIST) and has no GPU, so skip this too — layout

        // geometry never depends on it (transforms are render-time). This

        // also avoids GpuValueCache::synchronize, which currently mis-lifts

        // to wasm (out-of-bounds access). Desktop is unaffected.

        // M12.7: in the headless web path the GPU cache is empty (sync skipped),

        // and `.clone()` of an empty hashbrown table drives RawTable::clone's

        // RawIterRange — which mis-lifts to wasm and loops forever. Use a fresh

        // empty cache instead (geometry doesn't use it). Desktop unchanged.

        } else {

        };

        };

        // Hint the allocator to return freed pages after the layout pass

        // drops its transient allocations (intrinsic sizing Vecs, etc.).

        // M12.7: the headless web path needs the per-node geometry. Everything below —

        // scrollbar TransformKey registration, GPU-cache opacity/transform sync,

        // update_scrollbar_transforms — is webrender/display-list bookkeeping that web

        // doesn't use, and it contains an ARM loop whose lift to wasm never terminates

        // (an opt-folded `br self`; routing value resolves to a webrender code pointer).

        // So publish the geometry (tree + calculated_positions) to `layout_results` HERE

        // — the same DomLayoutResult the code below would store at the tail — so the

        // headless extractor (get_node_size / get_node_position, which read

        // layout_results via dom_to_layout) finds it; then skip the GPU bookkeeping.

        // Desktop (skip_gpu_sync == false) is unchanged.

        // Optional memory-breakdown print for the CSS property cache.

        // Gated on AZ_MEM_BREAKDOWN=1; off costs one env-var read on

        // the first call (`OnceLock`-cached) and nothing after.

        static MEM_BREAKDOWN_ENABLED: std::sync::OnceLock<bool> =

            std::sync::OnceLock::new();

            // solver3 LayoutCache breakdown

            // text shaping cache breakdown

            #[cfg(feature = "probe")]

            {

                let (rss, _virt) = crate::probe::current_rss_bytes();

                let peak = crate::probe::peak_rss_bytes_pub();

                eprintln!("[MEM] after layout: current rss={:.1} MiB  peak rss={:.1} MiB  (unreturned={:.1} MiB)",

                    rss as f64 / 1048576.0, peak as f64 / 1048576.0,

                    (peak.saturating_sub(rss)) as f64 / 1048576.0);

                eprintln!("[MEM] accounted / rss = {:.1}% — the gap is allocator overhead + unreturned transient pages + fonts/images + misc",

                    grand_total as f64 * 100.0 / (rss as f64).max(1.0));

            }

        // Optional AZ_PROFILE=cpu dump: per-phase wall-clock timings from

        // `Probe::span` spans (layout, style, cascade, paint, text-shape,

        // callbacks, …). Drains the thread-local buffer once per pass so

        // the printout reflects ONE layout/relayout frame — which makes it

        // easy to see which phase spiked during a stuttering frame.

        static CPU_ENABLED: std::sync::OnceLock<bool> = std::sync::OnceLock::new();

        // Optional AZ_PROFILE=cascade dump: top-N CSS properties by

        // cascade-walk count per layout pass. Narrow diagnostic for

        // prop-cache triage — not a general CPU profile.

        static CASCADE_ENABLED: std::sync::OnceLock<bool> = std::sync::OnceLock::new();

        // Get scroll IDs from cache (they were computed during layout_document)

        // Register scrollbar thumb TransformKeys from the display list into the GPU cache.

        // paint_scrollbars() creates TransformKey::unique() for each thumb. We need to

        // register those keys in the GPU cache so that update_scrollbar_transforms() can

        // update the values during GPU-only scroll (without display list rebuild).

        // Also register opacity keys from the display list the same way.

        {

            use crate::solver3::display_list::{DisplayListItem, ScrollbarDrawInfo};

                        // Register transform keys

                                }

                                }

                            }

                        // Register opacity keys (same pattern as transform keys).

                        // The display list always generates an OpacityKey for each

                        // scrollbar. We mirror these into the GPU cache so that

                        // synchronize_scrollbar_opacity can update the values and

                        // synchronize_gpu_values can push them to WebRender.

                        //

                        // Initial opacity depends on visibility mode:

                        //   Always       → 1.0 (legacy scrollbar, always visible)

                        //   WhenScrolling → 0.0 (overlay scrollbar, hidden until scroll)

                        //   Auto         → 0.0 (same as WhenScrolling)

                        } else {

                        };

                                }

                                }

                            }

            }

        }

        // Synchronize scrollbar transforms AFTER layout

        // Scan for VirtualViews *after* the initial layout pass

        // Pass styled_dom directly — layout_results isn't populated yet at this point