lumen_scene/

spawn.rs

//! `LayoutIR::spawn_into` walks the IR tree and spawns entities into the main world.
//!
//! Maps:
//!
//! * `width` / `height` / `flex` / `padding` / `margin` -> [`Style`].
//! * `bg` + `radius` + `shadow` -> [`Visuals`].
//! * `text` -> [`TextContent`]; color/size/align/wrap/max-lines -> [`TextStyle`].
//! * `scroll` -> [`Scroll`] (with inline velocity) + [`ScrollOffset`].
//! * `tab-index` -> [`TabIndex`].
//! * Every spawned entity carries [`DirtyLayout`] so taffy runs on first tick.
//! * Children link to parents via [`ChildOf`].

use crate::computed::{ComputedStyle, StyleContext};
use lumen_core::components::AuthoredStrings;
use lumen_core::style_overrides::{Live, StyleOwner, StyleValues};

use lumen_core::property_store::PropertyStore;
use lumen_core::signals::signal_is_truthy;
use lumen_ir::interpolate::{Scope, element_carries_placeholder, substitute_element};
use lumen_ir::layout_ir::{Attributes, BindKind, Element, LayoutIR};
use lumen_ir::translate::{TranslatedStrings, translate};

/// `<if mode="...">` policy. `Render` despawn/respawns the subtree on
/// each transition (default; cheap state-wise but loses focus / scroll
/// / per-row signals across show/hide). `Hide` mounts once and toggles
/// `Visible(bool)` on every descendant, preserving state.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum IfMode {
    /// Despawn the body on falsy -> truthy -> despawn each transition.
    #[default]
    Render,
    /// Mount once; toggle `Visible` on falsy / truthy.
    Hide,
}

impl From<lumen_ir::layout_ir::IfModeSpec> for IfMode {
    fn from(s: lumen_ir::layout_ir::IfModeSpec) -> Self {
        use lumen_ir::layout_ir::IfModeSpec;
        match s {
            IfModeSpec::Render => IfMode::Render,
            IfModeSpec::Hide => IfMode::Hide,
        }
    }
}

/// Empty marker added alongside [`IfMarker`] for entities spawned from
/// a `<dialog>` tag. Drives Esc-to-close + the focus trap
/// (`lumen_core::components::FocusBoundary` is inserted alongside).
/// The `IfMarker` carries the bound `open` signal name; this marker
/// just distinguishes dialogs from generic `<if>` blocks.
#[derive(bevy_ecs::component::Component, Clone, Copy, Debug, Default)]
pub struct DialogMarker;

/// The typography role an element was written with (`style="title-lg"`).
/// Its text size is computed from it, and a restyle recomputes that from
/// here; the attribute is the element's own, not a style a rule can set.
#[derive(bevy_ecs::component::Component, Clone, Debug, PartialEq, Eq)]
pub struct TypographyRole(pub std::sync::Arc<str>);

/// `autofocus="true"` marker: when the containing `<dialog>` opens,
/// [`manage_dialog_lifecycle`] moves focus here first.
#[derive(bevy_ecs::component::Component, Clone, Copy, Debug, Default)]
pub struct AutoFocus;

/// `<button default="true">` marker: the dialog's DEFAULT button (Qt
/// `QPushButton::setDefault`). Enter anywhere in the dialog activates
/// it ([`activate_dialog_default_on_enter`]), and a close that went
/// through it fires the `accepted` hook instead of `rejected`.
#[derive(bevy_ecs::component::Component, Clone, Copy, Debug, Default)]
pub struct DefaultButton;

/// Per-dialog open/close bookkeeping maintained by
/// [`manage_dialog_lifecycle`] - mirrors
/// `lumen_primitives::PopupNavSession` for popups.
#[derive(bevy_ecs::component::Component, Clone, Debug, Default)]
pub struct DialogSession {
    /// Open state last observed (edge detector).
    pub open: bool,
    /// Initial focus still pending: the dialog body mounts via
    /// deferred commands one tick after the open edge, so the focus
    /// pass retries until a target exists.
    pub needs_focus: bool,
    /// Focus holder at open time, restored on close (Qt/web modal
    /// focus-restore contract).
    pub prev_focus: Option<Entity>,
    /// Whether the pre-open holder carried `FocusVisible`.
    pub prev_focus_visible: bool,
    /// The default button was activated during this open cycle -
    /// resolves the close as `accepted` (exactly one of
    /// accepted/rejected fires, on the close edge).
    pub pending_accept: bool,
}

/// Marker for an `<if signal="...">` block. The reconciler mounts /
/// dismounts the subtree based on the named signal's truthiness, or -
/// when [`Self::eq`] is `Some`- on value equality.
///
/// A hidden [`IfMode::Hide`] block holds `display: none` in
/// [`StyleOverrides`](lumen_core::style_overrides::StyleOverrides) (spec
/// section 17.4: space is released and the relayout comes free via
/// `Changed<Style>`), and lets go when it shows, so it shows with the
/// display its styles give it then.
#[derive(bevy_ecs::component::Component, Clone, Debug)]
#[require(lumen_core::style_overrides::StyleOverrides)]
pub struct IfMarker {
    /// Signal name to evaluate.
    pub signal_name: String,
    /// Markup children kept around as the body template - spawned when
    /// truthy, despawned when not.
    pub body: Vec<Element>,
    /// Last-known mount state so we can detect transitions cheaply.
    pub currently_mounted: bool,
    /// How to handle the transition (despawn vs hide).
    pub mode: IfMode,
    /// When `Some(expected)`, mounts only when `Signals[signal_name] == expected`.
    /// When `None`, mounts when `Signals[signal_name]` is non-empty and not literal `"false"`/`"0"`.
    pub eq: Option<String>,
    /// [`IfMode::Hide`] only: the visibility state last applied to the
    /// entity (`None` = never applied). The reconciler only touches
    /// `Style` / `Visible` on a transition - re-inserting every tick
    /// kept `FrameDirty` permanently set (D5).
    pub applied_visible: Option<bool>,
}

impl StyleOwner for IfMarker {
    const RANK: u8 = 20;
}

impl StyleOwner for ForMarker {
    const RANK: u8 = 20;
}

/// Marker for a `<for each="...">` block. The reconciler reads the referenced [`ArraySignals`] entry each tick,
/// expands `body` once per item (substituting `{field}` placeholders against the item record), and spawns/despawns child entities to match.
/// The reconciler compares the key sequence it built last tick with the new one: an unchanged sequence mounts
/// nothing, an appended prefix spawns only the new rows, a truncated prefix despawns only the trailing rows, and
/// anything else (reorder, mid-insert, mid-remove) is a full despawn-and-respawn. A row whose key is kept but whose
/// record changed is updated in place, on the entities it already has. `key_field` names the record field the keys
/// come from; without it the item index is the key.
///
/// A virtualized block holds its width and height in
/// [`StyleOverrides`](lumen_core::style_overrides::StyleOverrides), sized
/// to every row it could show.
#[derive(bevy_ecs::component::Component, Clone, Debug)]
#[require(lumen_core::style_overrides::StyleOverrides)]
pub struct ForMarker {
    /// Name of the `ArraySignals` entry to iterate.
    pub array_name: String,
    /// Template body - the markup children of the `<for>` element.
    pub body: Vec<Element>,
    /// Stable-id field within each record (e.g. `"id"`). Optional; without
    /// it the reconciler keys rows by item index.
    pub key_field: Option<String>,
    /// Cache of the keys (or item indices when `key_field` is absent)
    /// currently materialized as children, so the reconciler can detect
    /// no-op frames without re-walking the body template.
    pub cached_keys: Vec<String>,
    /// `<for virtualized="true">` opt-in. When set, and when the scene policy
    /// leaves the windowing to the reconciler, it spawns only rows in the
    /// visible scroll window plus a small buffer; each row is
    /// absolute-positioned via inline `inset` from `row_height * row_index`.
    pub virtualized: bool,
    /// Per-row pixel height used by the virtualization windowing math.
    /// Required when `virtualized = true`. Default 32 px when authors
    /// turn on `virtualized` without specifying `row-height`.
    pub row_height: f32,
    /// Virtualized only: the `(row_index, key)` pairs currently mounted,
    /// in child-list order (each entry owns `body.len()` consecutive
    /// children). Spec section 15.3 windowed reuse - a window shift keeps every
    /// row whose `(index, key)` is unchanged instead of respawning the
    /// whole band.
    pub win_rows: Vec<(usize, String)>,
    /// Virtualized only: the body template with the CSS cascade already
    /// applied (cascade-once-per-template). `None` until first use and
    /// after every stylesheet change; rebuilt lazily by the reconciler.
    /// Skipped (per-row cascade instead) when the template's `id` /
    /// `class` attrs contain `{...}` placeholders, because then selector
    /// matching depends on per-row substitution results.
    pub cascaded_body: Option<std::sync::Arc<Vec<Element>>>,
    /// The record each mounted row was built from, in the order of
    /// [`Self::cached_keys`] (or of [`Self::win_rows`] when virtualized).
    /// A kept row whose record no longer matches its entry here has its
    /// placeholders resolved again and written onto the entities it
    /// already has.
    pub row_items: Vec<ArrayItem>,
}

/// Who mounts the rows of a virtualized `<for>`.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Virtualization {
    /// The reconciler windows the rows itself: it reads the nearest
    /// `<scroll>` ancestor, mounts the visible band plus an overscan buffer,
    /// and absolute-positions each row. What a desktop app does.
    #[default]
    Enabled,
    /// The presentation layer already windows long lists, so the reconciler
    /// mounts every row and leaves `virtualized="true"` to it.
    HostManaged,
}

/// Who resolves the styles of a `<for>` row.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum RowStyle {
    /// The reconciler runs the CSS cascade over each row it builds, so the
    /// spawned entities carry resolved values. What a desktop app does.
    #[default]
    Cascade,
    /// The presentation layer has its own cascade over the same stylesheet,
    /// so the reconciler leaves row markup unresolved rather than doing the
    /// work twice.
    HostStyled,
}

/// What the presentation layer under this scene already does for itself, so
/// [`reconcile_for_blocks`] can stop doing it.
///
/// The defaults are what a desktop app needs, and a world with no policy
/// resource behaves as the defaults do. A host that brings its own windowing
/// or its own cascade inserts a policy saying so.
#[derive(bevy_ecs::resource::Resource, Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct ScenePolicy {
    /// Who mounts the rows of a virtualized `<for>`.
    pub virtualization: Virtualization,
    /// Who resolves the styles of a `<for>` row.
    pub row_style: RowStyle,
}

use bevy_ecs::prelude::*;
use lumen_core::prelude::*;
use lumen_core::signals::ArrayItem;

// The typography-role -> px table moved to `lumen-ir` (it backs the
// `Attributes -> TextStyle` conversion, which the orphan rule forced into
// `lumen-ir`). Re-export it so `crate::spawn::typography_role_to_px` - used
// by `run::restyle` - keeps resolving.
pub use lumen_ir::typography_role_to_px;

/// Spawn an IR tree into a main world. Defined as a local extension trait
/// because [`LayoutIR`] now lives in `lumen-ir` and an inherent `impl` on a
/// foreign type isn't allowed; the spawn logic (which drives `lumenc`'s ECS
/// walker) stays here.
pub trait SpawnIntoWorld {
    /// Spawn the IR tree into the given main world. Returns the root entity.
    fn spawn_into(&self, world: &mut World) -> Entity;
}

impl SpawnIntoWorld for LayoutIR {
    fn spawn_into(&self, world: &mut World) -> Entity {
        if let Some(sheet) = self.combined_stylesheet.clone() {
            world.insert_resource(LumenStylesheet(sheet));
        }
        let root = spawn_subtree(world, &self.root, None, Placeholders::Unresolved);
        install_document_root(world, root);
        root
    }
}

/// The entity the app's markup tree was spawned onto. Whoever writes the
/// root - `set_root_class`, the OS theme follow, the class-change
/// watcher - asks here rather than guessing from the hierarchy, so there
/// is one answer and it does not depend on the root happening to carry a
/// class or on hot reload being on. A respawn (hot reload) overwrites it.
#[derive(Resource, Debug, Clone, Copy)]
pub struct DocumentRoot(pub Entity);

/// Record `root` as the [`DocumentRoot`].
///
/// Every assembly records it, because everything that writes the root -
/// `set_root_class`, the desktop's class-change watcher - asks here rather
/// than guessing from the hierarchy. It used to be recorded by the desktop
/// alone, which is why `set_root_class` reached nothing in a page or a
/// server render.
pub fn install_document_root(world: &mut World, root: Entity) {
    world.insert_resource(DocumentRoot(root));
}

/// A compiled app spawns its tree and the fragments that tree names.
///
/// The tree alone is not the whole app: a `<template>` body and an `lmn!`
/// block travel beside it in the artifact, and a script instantiates one by
/// key while the app runs. Taking both from the artifact in one call is what
/// keeps a page, a server render and a window building the same subtree,
/// rather than each remembering to install the table on its own.
impl SpawnIntoWorld for lumen_ir::artifact::CompiledApp {
    fn spawn_into(&self, world: &mut World) -> Entity {
        crate::fragments::install(world, self.fragments.clone());
        self.ir.spawn_into(world)
    }
}

/// Whether a subtree still carries `{...}` placeholders for the spawner to
/// resolve.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Placeholders {
    /// The tree is as the markup wrote it, so a `{name}` in it names a global
    /// signal and is resolved against the app's current state on the way in.
    Unresolved,
    /// Something already walked this tree with the scope that owns it: a
    /// `<for>` row, a fragment instantiation, or the tree an `<if>` body
    /// arrived inside. What braces are left in it are text, and a second pass
    /// would read a value that arrived as data as markup.
    Resolved,
}

/// Spawn an [`Element`] subtree under `parent` (or as a new root when
/// `None`) WITHOUT touching the global [`LumenStylesheet`] resource.
///
/// Used by the dev-only devtools overlay mount: it applies its own isolated
/// stylesheet to the overlay IR before spawning, so it must not clobber the
/// app's `<for>`-reconciler stylesheet the way [`LayoutIR::spawn_into`] does.
pub fn spawn_subtree(
    world: &mut World,
    el: &Element,
    parent: Option<Entity>,
    placeholders: Placeholders,
) -> Entity {
    match with_globals_resolved(world, el, placeholders) {
        Some(resolved) => spawn_element(world, &resolved, parent),
        None => spawn_element(world, el, parent),
    }
}

/// The subtree with every `{name}` its globals answer resolved, or `None`
/// when there was nothing to resolve.
///
/// A global placeholder is read once, when the element is built. That is the
/// same moment the web emitter reads it while writing the page, which is what
/// makes a browser's first pass over a rendered document find the text it was
/// going to write already there. A value that changes afterwards wants
/// `bind-text`, which is a binding rather than a string built once.
fn with_globals_resolved(
    world: &World,
    el: &Element,
    placeholders: Placeholders,
) -> Option<Element> {
    if placeholders == Placeholders::Resolved || !tree_carries_placeholder(el) {
        return None;
    }
    let store = world.get_resource::<PropertyStore>()?;
    Some(substitute_element(el, &Scope::new(store)))
}

/// Whether anything in the subtree carries a placeholder, so a tree with none
/// is spawned from the IR itself rather than from a copy of it.
fn tree_carries_placeholder(el: &Element) -> bool {
    element_carries_placeholder(el) || el.children.iter().any(tree_carries_placeholder)
}

/// World-resource wrapper for the combined skin + user CSS so the
/// for-block reconciler can re-apply matching rules to runtime-
/// substituted template clones.
#[derive(Resource, Clone)]
pub struct LumenStylesheet(pub lumen_ir::css::Stylesheet);

/// Backing counter for [`lumen_core::components::DocumentOrder`]. One per
/// world; `next_document_order` bumps it once per spawned element.
#[derive(Resource, Default)]
struct DocumentOrderCounter(u32);

/// Next value for [`lumen_core::components::DocumentOrder`], assigned in
/// the exact sequence `spawn_element` visits the parsed tree (depth-first,
/// parent before children, siblings in markup order). Must run before the
/// entity's `world.spawn(..)` call - `EntityWorldMut` holds `world`
/// exclusively for its lifetime, so the resource bump can't be interleaved
/// once that borrow starts.
///
/// This is the seed only. A subtree that mounts later - an `<if>` body,
/// a `<for>` row, a node a script appends - continues the same counter,
/// which places it after everything already in the world rather than
/// where it sits in the tree. [`renumber_document_order`] restates the
/// value from the live hierarchy once the shape settles.
fn next_document_order(world: &mut World) -> u32 {
    let mut counter = world.get_resource_or_insert_with(DocumentOrderCounter::default);
    let n = counter.0;
    counter.0 = counter.0.wrapping_add(1);
    n
}

/// Restate [`lumen_core::components::DocumentOrder`] from the live
/// hierarchy, so it means "where this element sits in the document"
/// rather than "when it was spawned".
///
/// The spawn counter is only markup order for the tree the build walked.
/// Anything that mounts afterwards is numbered at mount time, which puts
/// it behind every element already in the world: a button inside an
/// `<if>` was thrown past the whole list beside it, and the longer that
/// list, the further Tab jumped over the button. Short lists hid the
/// defect, because a couple of stops out of place still looks right.
///
/// The walk is depth-first, parent before children, siblings in
/// `Children` order - which is the order they were attached, so it is
/// markup order for the initial tree and mount order within a
/// reconciler's own body. Roots are visited in their existing order, so
/// a second root (the error banner, the devtools overlay) keeps its
/// place. Only entities whose number actually moves are written, so a
/// steady tree costs one query and nothing else.
pub fn renumber_document_order(
    mut commands: bevy_ecs::system::Commands,
    reshaped: bevy_ecs::system::Query<(), Changed<bevy_ecs::hierarchy::Children>>,
    roots: bevy_ecs::system::Query<
        (Entity, &lumen_core::components::DocumentOrder),
        Without<bevy_ecs::hierarchy::ChildOf>,
    >,
    children: bevy_ecs::system::Query<&bevy_ecs::hierarchy::Children>,
    orders: bevy_ecs::system::Query<&lumen_core::components::DocumentOrder>,
) {
    // Nothing gained or lost a child this tick, so every relative
    // position still holds.
    if reshaped.is_empty() {
        return;
    }
    let mut top: Vec<(u32, Entity)> = roots.iter().map(|(e, d)| (d.0, e)).collect();
    top.sort_unstable();
    // Depth-first with an explicit stack: an app can nest deeper than a
    // recursive walk is comfortable with.
    let mut stack: Vec<Entity> = top.into_iter().rev().map(|(_, e)| e).collect();
    let mut n: u32 = 0;
    while let Some(e) = stack.pop() {
        if orders.get(e).ok().map(|d| d.0) != Some(n) {
            // `try_insert`, because a later system in the same stage can
            // despawn an entity this walk just numbered - a script
            // handler rebuilding a list does exactly that - and the
            // write lands after it. Losing the number is the right
            // outcome there: the entity is gone, and the despawn
            // reshapes the tree, so the next tick walks it again.
            commands
                .entity(e)
                .try_insert(lumen_core::components::DocumentOrder(n));
        }
        n = n.wrapping_add(1);
        if let Ok(kids) = children.get(e) {
            for kid in kids.iter().rev() {
                stack.push(kid);
            }
        }
    }
}

/// The strings an element shows in the app's locale.
///
/// A `translatable="key"` element reads each of them off the catalogue
/// message that key names, which is [`lumen_ir::translate::translate`]'s
/// rule, shared with the web emitter so a page built for a locale reads
/// like the app run in it. The spawner uses three of the four it returns;
/// nothing on the desktop reads `alt`.
///
/// A `format="<spec>"` then renders whatever text is left for the app's
/// locale. Both the catalogue and the formatter come off
/// [`lumen_core::i18n::AppI18n`], the app's own half of the seam, rather
/// than the process-wide hooks the script hosts use: a process running two
/// Lumen apps must not render one app's markup in the other's locale. Text
/// the spec cannot read stands as it is, so a translated sentence under a
/// `number` format is still the sentence.
///
/// The spawner calls this once per element, and
/// [`crate::i18n::retranslate_on_locale_change`] calls it again for every
/// element that kept its [`AuthoredStrings`] when the app changes locale.
/// One rule, asked twice.
pub fn resolve_strings(
    i18n: Option<&lumen_core::i18n::AppI18n>,
    authored: &AuthoredStrings,
    format: Option<&str>,
) -> TranslatedStrings {
    let mut strings = translate(authored, &|key| {
        i18n.and_then(|i18n| i18n.try_translate(key))
    });
    let (Some(text), Some(spec)) = (&strings.text, format) else {
        return strings;
    };
    if let Some(formatted) = i18n.and_then(|i18n| i18n.format(spec, text)) {
        strings.text = Some(formatted);
    }
    strings
}

/// Alpha multiplier applied to a disabled entity when neither
/// `disabled-bg` nor an explicit `:disabled { opacity }` was authored.
/// CSS `disabled-opacity` (`Attributes::disabled_opacity_default`)
/// overrides it; this is the single Rust-side fallback.
pub(crate) const DISABLED_OPACITY_DEFAULT: f32 = 0.5;

/// Read a `<toggle>` / `<switch>` track palette out of the cascaded
/// attributes: the resting `bg` while unchecked, `:checked { bg }` while
/// checked, `:disabled { bg }` while disabled.
///
/// `base` supplies each slot the cascade did not set: the built-in
/// tokens at spawn, so a control is readable with no CSS at all, and the
/// live palette on a restyle, so a theme flip that touches only one
/// state leaves the others where markup put them.
pub fn track_style_over(
    base: lumen_primitives::TrackStyle,
    attrs: &Attributes,
) -> lumen_primitives::TrackStyle {
    lumen_primitives::TrackStyle {
        checked_bg: attrs.checked_bg.map(Into::into).unwrap_or(base.checked_bg),
        unchecked_bg: attrs
            .bg
            .as_ref()
            .and_then(|b| Fill::try_from(b).ok()?.as_solid())
            .unwrap_or(base.unchecked_bg),
        disabled_bg: attrs.disabled_bg.map(Into::into).or(base.disabled_bg),
    }
}

/// Points an element's background at the image its `bg` names, or takes a
/// background image away when `bg` names a colour or a gradient instead.
///
/// The image travels the same road as an `<image src>`: an
/// [`lumen_assets::ImageSource`] the asset pipeline resolves, decodes and
/// caches, marked [`lumen_assets::BackgroundImage`] so it paints behind
/// the content and never sizes the element. An `<image>` keeps its `src` as
/// its one source, so a `bg` image on one is ignored.
///
/// `attrs` is the element's whole resolved style: with no `bg` left, an
/// image the element had is taken away, and with no `bg-fit` the image
/// covers the box.
pub fn apply_background_image(
    ent: &mut bevy_ecs::world::EntityWorldMut<'_>,
    tag: &str,
    attrs: &Attributes,
) {
    use lumen_assets::{
        AssetServer, BackgroundImage, Enqueued, ImageLoadFailed, ImageSource, LoadedImage,
        LoadedSvg,
    };
    use lumen_ir::layout_ir::BgSpec;
    if tag == "image" {
        return;
    }
    let current = ent.get::<BackgroundImage>().copied();
    match &attrs.bg {
        Some(BgSpec::Image(path)) => {
            let source = lumen_assets::resolve_source_path(path);
            if current.is_none() || ent.get::<ImageSource>().is_none_or(|s| s.0 != source) {
                // A new source starts from nothing: the old bitmap goes, and
                // a decode still out for the old path is made stale so it
                // cannot land on top of the new one.
                ent.remove::<(LoadedImage, LoadedSvg, ImageLoadFailed, Enqueued)>();
                let id = ent.id();
                ent.world_scope(|world| {
                    if let Some(mut server) = world.get_resource_mut::<AssetServer>() {
                        server.bump_request_id(id);
                    }
                });
                ent.insert(ImageSource(source));
            }
            let fit = attrs.bg_fit.map(ImageFit::from).unwrap_or(ImageFit::Cover);
            if current != Some(BackgroundImage { fit }) {
                ent.insert(BackgroundImage { fit });
            }
        }
        Some(_) | None => {
            if current.is_some() {
                ent.remove::<(
                    BackgroundImage,
                    ImageSource,
                    LoadedImage,
                    LoadedSvg,
                    ImageLoadFailed,
                    Enqueued,
                )>();
            }
        }
    }
}

/// The in-app drag source a `drag-payload` attribute publishes. An empty
/// payload names the element by its `id`.
fn drag_source(attrs: &Attributes) -> Option<lumen_os_dnd::DragSource> {
    let payload = attrs.drag_payload.as_ref()?;
    let text = if payload.is_empty() {
        attrs.id.clone().unwrap_or_default()
    } else {
        payload.clone()
    };
    Some(lumen_os_dnd::DragSource::new(text).with_effects(lumen_os_dnd::DropEffectSet::ANY))
}

fn spawn_element(world: &mut World, el: &Element, parent: Option<Entity>) -> Entity {
    // Seed any synthetic signal defaults (currently only the
    // `<tabs>` parser pass authors this - picks the first `<tab>` as
    // the default active when no script has written the signal yet).
    if let Some((name, default_value)) = &el.attrs.signal_seed
        && let Some(mut store) = world.get_resource_mut::<PropertyStore>()
        && store.get_global_str(name).is_none()
    {
        store.set_global_str(name, default_value.as_str());
    }
    // Two-way binds with an AUTHORED initial attr (`checked="true"`,
    // `value="42"`, `text="..."`) seed the signal if nothing wrote it yet,
    // so a sibling `bind-text` label shows the initial value without a
    // script. Seed-if-absent only: a script's `signal(name, default)`
    // publish or an earlier write wins, and the spawn-tick `Changed`
    // detection on the widget component is deliberately NOT pushed
    // (`push_*_to_signal` skips `is_added()` rows) - the widget's
    // component default is not an authored value.
    // The `<dropdown>` header button is excluded here: its `text` is the
    // authored `placeholder`, not an initial value for the bound signal,
    // and the dropdown pass already seeds the signal itself (above, via
    // `signal_seed`, only when there's no placeholder). Letting this
    // generic path run too would seed the value signal with the
    // placeholder string.
    if let Some(spec) = &el.attrs.bind
        && el.attrs.dropdown_button.is_none()
    {
        let authored: Option<String> = match spec.kind {
            BindKind::Checked => el
                .attrs
                .checked
                .map(|b| if b { "true" } else { "false" }.to_string()),
            BindKind::Value => el.attrs.value.map(|v| format!("{v}")),
            BindKind::Text => el.attrs.text.clone(),
        };
        if let Some(v) = authored
            && let Some(mut store) = world.get_resource_mut::<PropertyStore>()
            && store.get_global_str(&spec.name).is_none()
        {
            store.set_global_str(&spec.name, v.as_str());
        }
    }
    // Resolve the element's strings before the world is borrowed by `spawn`:
    // a `translatable="key"` element reads the loaded catalogue.
    let authored = AuthoredStrings::from(&el.attrs);
    let strings = resolve_strings(
        world.get_resource::<lumen_core::i18n::AppI18n>(),
        &authored,
        el.attrs.format.as_deref(),
    );
    let text = strings.text.clone();
    // Every style component, from the one computation a restyle runs too.
    // The parent is spawned before its children, so its `Scroll` marker is
    // already in place.
    let in_scroll = parent.is_some_and(|p| world.get::<Scroll>(p).is_some());
    let computed = ComputedStyle::new(
        &StyleContext::of_attrs(&el.tag, &el.attrs, in_scroll),
        &el.attrs,
    );
    let knob_geometry = computed.knob_geometry.unwrap_or_default();
    let knob_fill = computed.knob_fill;
    let doc_order = next_document_order(world);
    let mut entity = world.spawn((
        DirtyLayout,
        lumen_core::components::DocumentOrder(doc_order),
    ));
    if let Some(p) = parent {
        entity.insert(ChildOf(p));
    }
    computed.insert(&mut entity);
    // The typography role an element was written with (`style="title-lg"`)
    // is part of what its text style is computed from, so a restyle reads
    // it back.
    if let Some(role) = el.attrs.style_role.as_deref() {
        entity.insert(TypographyRole(role.into()));
    }
    // A use site the build could not finish: the script fills it by calling
    // the function this names. Arguments arrive in parameter order, laid out
    // when the tree was linked.
    if let Some(use_site) = &el.frag_use {
        entity.insert(lumen_core::components::PendingFill {
            function: use_site.key.clone(),
            args: use_site
                .args
                .iter()
                .map(|(_, value)| value.clone())
                .collect(),
        });
    }
    if let Some(text) = &text {
        entity.insert(TextContent(text.clone()));
    }
    if matches!(el.tag.as_str(), "input" | "textarea") {
        let default_multiline = el.tag == "textarea";
        entity.insert(TextInput {
            placeholder: strings.placeholder.clone().unwrap_or_default(),
            cursor: 0,
            selection_anchor: None,
            multiline: el.attrs.multiline.unwrap_or(default_multiline),
        });
    }
    if matches!(el.tag.as_str(), "toggle" | "switch" | "checkbox") {
        entity.insert(Toggleable {
            checked: el.attrs.checked.unwrap_or(false),
        });
    }
    if el.tag == "switch" {
        // Explicit a11y role: a switch is announced as `Role::Switch`, not
        // the `Role::CheckBox` that a bare `Toggleable` would derive.
        entity.insert(lumen_core::components::A11yRole::Switch);
    }
    if el.tag == "slider" {
        entity.insert(SliderValue::from(&el.attrs));
    }
    if el.tag == "checkbox" && el.attrs.indeterminate {
        entity.insert(lumen_primitives::Indeterminate);
    }
    if el.tag == "radio"
        && let (Some(group), Some(value)) = (&el.attrs.radio_group, &el.attrs.radio_value)
    {
        entity.insert(lumen_primitives::RadioButton {
            group: group.clone(),
            value: value.clone(),
        });
    }
    if el.tag == "progress" {
        // No `value` and no binding = indeterminate; a later `bind-value`
        // pull flips it determinate.
        let bar = lumen_primitives::ProgressBar::from(&el.attrs);
        // The accessibility walk reads `A11yValue`, not `ProgressBar`;
        // `apply_progress_bindings` keeps the two in step.
        entity.insert(lumen_core::components::A11yValue {
            now: f64::from(bar.value.unwrap_or(0.0)),
            min: 0.0,
            max: f64::from(bar.max),
            step: 0.0,
            text: None,
        });
        entity.insert(bar);
    }
    // Synthetic widget-part markers from the parser desugars.
    if let Some(part) = el.attrs.part {
        match part {
            lumen_ir::layout_ir::WidgetPart::CheckboxBox => {
                entity.insert(lumen_primitives::CheckboxBox);
            }
            lumen_ir::layout_ir::WidgetPart::RadioDot => {
                entity.insert(lumen_primitives::RadioDot);
            }
            lumen_ir::layout_ir::WidgetPart::ProgressFill => {
                entity.insert(lumen_primitives::ProgressFill);
            }
        }
    }
    // Attach Validation only when validation-specific attrs are set.
    // `<slider min max>` already enforces bounds in SliderValue itself -
    // pulling min/max into Validation for sliders would just duplicate
    // the clamp. So sliders need a `required` or `pattern` opt-in.
    // `<progress min/max>` bounds its own value in `ProgressBar` -
    // same exemption as `<slider>`.
    let validate_min_max = !matches!(el.tag.as_str(), "slider" | "progress")
        && (el.attrs.min.is_some() || el.attrs.max.is_some());
    if el.attrs.required || el.attrs.pattern.is_some() || validate_min_max {
        entity.insert(lumen_core::components::Validation {
            required: el.attrs.required,
            pattern: el.attrs.pattern.clone(),
            min: if validate_min_max { el.attrs.min } else { None },
            max: if validate_min_max { el.attrs.max } else { None },
            is_valid: true,
        });
    }
    if el.attrs.drop_target {
        entity.insert(DropTarget);
        // In-app DnD accept filter (mirrors Qt `dragEnterEvent` +
        // `acceptProposedAction`). No `accept="..."` => accept any payload,
        // matching the file-drop path's "accept anything" default.
        let accept = match &el.attrs.drop_accept {
            Some(mime) => {
                lumen_os_dnd::DropAccept::only([lumen_os_dnd::mime::MimeKind::from(mime.as_str())])
            }
            None => lumen_os_dnd::DropAccept::any(),
        }
        .with_effects(lumen_os_dnd::DropEffectSet::ANY);
        entity.insert(accept);
    }
    // In-app DnD source: `drag-payload="..."` publishes a payload; an empty
    // value derives it from the element `id`. Mirrors HTML5
    // `dataTransfer.setData` / Qt `QMimeData`. Independent of `draggable`
    // (which stays the "physically translate on drag" opt-in).
    if let Some(source) = drag_source(&el.attrs) {
        entity.insert(source);
    }
    if el.attrs.title_bar_drag {
        entity.insert(lumen_core::components::TitleBarDraggable);
    }
    if let Some(spec) = &el.attrs.tooltip {
        // `None` here means neither the inline attr nor a skin token
        // supplied a value - the runtime defaults (500 ms / 12 px) are
        // the single Rust-side fallback.
        let defaults = lumen_primitives::TooltipSource::default();
        entity.insert(lumen_primitives::TooltipSource {
            text: strings.tooltip.clone().unwrap_or_default(),
            delay_ms: spec.delay_ms.unwrap_or(defaults.delay_ms),
            offset: spec.offset.unwrap_or(defaults.offset),
        });
    }
    if let Some((signal_name, value)) = &el.attrs.tab_strip {
        entity.insert(lumen_primitives::TabStripButton {
            signal_name: signal_name.clone(),
            value: value.clone(),
        });
    }
    if let Some(spec) = &el.attrs.dropdown_button {
        entity.insert(lumen_primitives::DropdownButton {
            open_signal: spec.open_signal.clone(),
            value_signal: spec.value_signal.clone(),
            options: spec
                .options
                .iter()
                .map(
                    |(value, label, disabled)| lumen_primitives::DropdownOptionSpec {
                        value: value.clone(),
                        label: label.clone(),
                        disabled: *disabled,
                    },
                )
                .collect(),
        });
        // The header's text binding names the value signal, and the
        // closed combobox shows the selected option's label rather than
        // the value that signal holds. `apply_text_bindings` reads the
        // mapping off this component as it writes, so the header never
        // shows the raw value even for a tick.
        entity.insert(lumen_core::components::BindTextLabels(
            spec.options
                .iter()
                .map(|(value, label, _)| (value.clone(), label.clone()))
                .collect(),
        ));
    }
    if let Some((value_signal, value, open_signal)) = &el.attrs.dropdown_option {
        entity.insert(lumen_primitives::DropdownOptionButton {
            value_signal: value_signal.clone(),
            value: value.clone(),
            open_signal: open_signal.clone(),
        });
    }
    if let Some((open_signal, item_id)) = &el.attrs.menu_item {
        entity.insert(lumen_primitives::MenuItemButton {
            open_signal: open_signal.clone(),
            item_id: item_id.clone(),
        });
    }
    // A popup row is clicked whether or not a skin gives it a background,
    // so it is a pointer target either way. `tab-index="-1"` is that: in
    // reach of the pointer and of the popup's own arrow-key navigation,
    // out of the Tab chain, as a `QComboBox` or `QMenu` row is.
    if (el.attrs.dropdown_option.is_some() || el.attrs.menu_item.is_some())
        && el.attrs.tab_index.is_none()
    {
        entity.insert(TabIndex(-1));
    }
    if let Some(open_signal) = &el.attrs.popup_panel {
        entity.insert((
            lumen_primitives::PopupPanel {
                open_signal: open_signal.clone(),
            },
            // Top-layer paint band: the panel must paint over all
            // later-document-order content (inputs, textareas) it
            // floats above.
            lumen_core::render_world::OverlayLayer,
        ));
    }
    if el.tag == "image"
        && let Some(src) = &el.attrs.src
    {
        entity.insert(lumen_assets::ImageSource(std::path::PathBuf::from(src)));
    }
    apply_background_image(&mut entity, &el.tag, &el.attrs);
    if let Some(tab) = el.attrs.tab_index {
        entity.insert(TabIndex(tab));
    }
    if el.attrs.autofocus {
        entity.insert(AutoFocus);
    }
    if el.attrs.default_button {
        entity.insert(DefaultButton);
    }
    // The spec a `bind-text` write is rendered through: `resolve_strings`
    // formatted the text this element spawned with, and
    // `apply_text_bindings` formats every value the signal writes after.
    if let Some(spec) = &el.attrs.format {
        entity.insert(lumen_core::components::TextFormat(spec.clone()));
    }
    // What the markup wrote, kept so the element can be resolved again when
    // the app changes locale: `TextContent` by then holds the message the
    // old catalogue gave, or a number written the old locale's way, and
    // neither can be turned back into what the author typed.
    //
    // A `format` element is kept for the same reason a translated one is: a
    // formatted amount is locale output too, and `1.234,50` no longer says
    // what `1234.5` said. An element with no key and no format carries
    // nothing extra.
    if authored.key.is_some() || authored.tooltip_key.is_some() || el.attrs.format.is_some() {
        entity.insert(authored);
    }
    if let Some(spec) = &el.attrs.bind {
        match spec.kind {
            BindKind::Text => {
                entity.insert(BindText::from(spec.name.clone()));
                // `apply_text_bindings` queries `(&BindText, &mut
                // TextContent)`; if the markup omits `text=""` we
                // need to seed an empty TextContent so the first
                // signal write has a target to update.
                if text.is_none() {
                    entity.insert(TextContent(String::new()));
                }
            }
            BindKind::Checked => {
                entity.insert(BindChecked(spec.name.clone()));
            }
            BindKind::Value => {
                entity.insert(BindValue(spec.name.clone()));
            }
        }
    }
    // Per-entity (`$self.<field>`) and parent-entity (`$parent.<field>`)
    // binding markers. The consumer systems are no-op stubs today
    // (W-signal-design step 1) - we install the marker so the spawn
    // surface is final ahead of the follow-up commit that wires the
    // queries.
    if let Some(field) = &el.attrs.bind_self_text {
        entity.insert(BindSelfText::from(field.as_str()));
        if text.is_none() {
            entity.insert(TextContent(String::new()));
        }
    }
    if let Some(field) = &el.attrs.bind_self_value {
        entity.insert(BindSelfValue::from(field.as_str()));
    }
    if let Some(field) = &el.attrs.bind_self_checked {
        entity.insert(BindSelfChecked::from(field.as_str()));
    }
    if let Some(field) = &el.attrs.bind_parent_text {
        entity.insert(BindParentText::from(field.as_str()));
        if text.is_none() {
            entity.insert(TextContent(String::new()));
        }
    }
    if let Some(field) = &el.attrs.bind_parent_value {
        entity.insert(BindParentValue::from(field.as_str()));
    }
    if let Some(field) = &el.attrs.bind_parent_checked {
        entity.insert(BindParentChecked::from(field.as_str()));
    }
    if let Some(id) = &el.attrs.id {
        entity.insert(LumenId(id.clone()));
    }
    // `<a href="page">` - a real anchor. Attach the navigation target so a
    // click on this element switches the active page (file-based pages).
    if el.tag == "a"
        && let Some(href) = &el.attrs.href
    {
        entity.insert(crate::routing::Anchor(href.clone()));
        // An anchor is interactive, so it is a pointer target whether or
        // not it paints anything - `tab-index="-1"` is exactly HTML's
        // "focusable by pointer, not in the Tab chain". Links stay out
        // of the Tab chain by default; an author opts one in with
        // `tab-index="0"`, which wins because it was already applied
        // above.
        if el.attrs.tab_index.is_none() {
            entity.insert(TabIndex(-1));
        }
    }
    if !el.attrs.classes.is_empty() {
        entity.insert(LumenClasses::from(el.attrs.classes.clone()));
    }
    // Kept for the restyle pass, which re-runs the cascade from the
    // element's tag, classes and id alone and would otherwise let a tag
    // rule overwrite what the markup set. A value still holding a `{...}`
    // placeholder is a template's, not this element's.
    let markup: Vec<(String, String)> = el
        .attrs
        .markup_styles
        .iter()
        .filter(|(_, value)| !value.contains('{'))
        .cloned()
        .collect();
    if !markup.is_empty() {
        entity.insert(lumen_core::components::MarkupStyle(markup.into()));
    }
    // Retain the tag on EVERY spawned element so the runtime can
    // rebuild a `tag.class#id` cascade target and re-resolve computed
    // style in place on a theme / media flip (see
    // `run::reapply_computed_styles`). Pre-skins this was limited to
    // entities with an id / class, which left tag-only rules (the whole
    // per-OS skin surface: `button { ... }`, `root { bg }`, ...) frozen at
    // their spawn-time theme.
    if !el.tag.is_empty() {
        entity.insert(lumen_core::components::LumenTag(el.tag.as_str().into()));
    }
    // W5.4: writing direction + language tag cascade. Both components
    // are inherited at runtime by the respective resolver systems;
    // explicit overrides set here win against the ancestor chain.
    if let Some(dir) = el.attrs.dir {
        entity.insert(dir);
    }
    if let Some(lang) = &el.attrs.lang {
        entity.insert(lumen_core::components::Lang::from(lang.as_str()));
    }
    if el.attrs.draggable {
        entity.insert(lumen_primitives::Draggable);
    }
    // Runtime-reactive disabled: `bind-disabled="signal"` mirrors the
    // bind-checked plumbing - `apply_disabled_bindings` (dirty-gated)
    // adds/removes the `Disabled` marker from the signal, and the
    // `:disabled` styling flows through the `StateVisuals.disabled`
    // patch populated above (so it reverses cleanly on re-enable).
    // Two-way scroll-offset binding (W6 T6): `bind-scroll="signal"` on a
    // scroll container. `apply_scroll_bindings` (dirty-gated) drives the
    // vertical offset from the signal; `push_scroll_to_signal` mirrors
    // user scrolling back on settle. The component is inert without a
    // co-resident `Scroll` + `ScrollOffset` (the `<scroll>` tag spawns
    // both).
    if let Some(name) = &el.attrs.bind_scroll {
        entity.insert(lumen_core::components::BindScroll(name.clone()));
    }
    if let Some(name) = &el.attrs.bind_disabled {
        entity.insert(lumen_core::components::BindDisabled(name.clone()));
        if el.attrs.disabled {
            // Initial `disabled="true"` alongside the binding: install
            // the marker now; the runtime patch styles it on tick 1 and
            // the signal takes authority from its first write.
            entity.insert(lumen_core::components::Disabled);
        }
    } else if el.attrs.disabled {
        // Without a binding the marker is static for the element's whole
        // life, and its `:disabled` styles are its own (see
        // `ComputedStyle`).
        entity.insert(lumen_core::components::Disabled);
    }
    if let Some(axis) = el.attrs.scroll {
        let mut scroll = Scroll {
            axis: axis.into(),
            sensitivity: 1.0,
            inertia: 0.4,
            velocity: glam::Vec2::ZERO,
        };
        if let Some(s) = el.attrs.sensitivity {
            scroll.sensitivity = s;
        }
        if let Some(i) = el.attrs.inertia {
            scroll.inertia = i;
        }
        entity.insert((scroll, ScrollOffset::default()));
    } else {
        // CSS `overflow: scroll` promotes any element to a live scroll
        // container (web semantics): the walker already clips it, and
        // this component makes it wheel-/keyboard-scrollable. Skins use
        // it for the dropdown panel's max-visible-rows internal scroll
        // (`.dropdown-panel { max-height: ...; overflow-y: scroll; }`).
        use lumen_ir::layout_ir::OverflowSpec;
        let ox = el.attrs.overflow_x.or(el.attrs.overflow);
        let oy = el.attrs.overflow_y.or(el.attrs.overflow);
        let sx = matches!(ox, Some(OverflowSpec::Scroll));
        let sy = matches!(oy, Some(OverflowSpec::Scroll));
        if sx || sy {
            let axis = match (sx, sy) {
                (true, true) => lumen_core::input::ScrollAxis::Both,
                (true, false) => lumen_core::input::ScrollAxis::X,
                _ => lumen_core::input::ScrollAxis::Y,
            };
            let mut scroll = Scroll {
                axis,
                sensitivity: 1.0,
                inertia: 0.4,
                velocity: glam::Vec2::ZERO,
            };
            if let Some(s) = el.attrs.sensitivity {
                scroll.sensitivity = s;
            }
            if let Some(i) = el.attrs.inertia {
                scroll.inertia = i;
            }
            entity.insert((scroll, ScrollOffset::default()));
        }
    }
    let id = entity.id();
    // `<toggle>` / `<slider>` spawn a knob / thumb child so their state
    // is visible without author CSS. Both are absolute-positioned small
    // rounded tiles; `sync_toggle_visuals` / `sync_slider_thumb` in
    // lumen-primitives keep them in step with the control's state.
    // Knob / thumb fill: `knob-color` (markup attr or the CSS
    // `knob-color:` property, UA-seeded by the skins) wins; the runtime
    // `KNOB_FILL` constant is the single Rust-side fallback.
    if el.tag == "toggle" {
        world.spawn((
            knob_style(28.0, knob_geometry.inset),
            DirtyLayout,
            ChildOf(id),
            Visuals {
                fill: Some(Fill::Solid(knob_fill)),
                radius: 14.0,
                corner_radii: None,
                shadows: Vec::new(),
                border: None,
            },
            lumen_primitives::ToggleKnob,
        ));
    }
    if el.tag == "switch" {
        // Thumb seed: absolute-positioned tile parked at the off end.
        // `sync_switch_visuals` refines its size / radius / inset once the
        // track's laid-out rect is known and animates it on every flip.
        world.spawn((
            knob_style(20.0, knob_geometry.inset),
            DirtyLayout,
            ChildOf(id),
            Visuals {
                fill: Some(Fill::Solid(knob_fill)),
                radius: 10.0,
                corner_radii: None,
                shadows: Vec::new(),
                border: None,
            },
            lumen_primitives::SwitchThumb::default(),
        ));
    }
    if el.tag == "slider" {
        let thumb = knob_geometry.thumb_size;
        world.spawn((
            knob_style(thumb, 0.0),
            DirtyLayout,
            ChildOf(id),
            Visuals {
                fill: Some(Fill::Solid(knob_fill)),
                radius: thumb / 2.0,
                corner_radii: None,
                shadows: Vec::new(),
                border: None,
            },
            lumen_primitives::SliderThumb,
        ));
    }
    // A `<slot>` in a fragment body stands in for content the use site
    // passes; the instantiation path swaps the marked entity for the node it
    // was handed. An unfilled slot keeps whatever the body wrote inside it.
    if let Some(name) = crate::fragments::slot_name_of(el) {
        world
            .entity_mut(id)
            .insert(crate::fragments::SlotPlaceholder(name));
    }
    // An element with a registered custom tag becomes the widget registered
    // for it, built from the attributes it was written with. Its own
    // components are in place by now and its children are not, so the
    // widget sees the element the markup made and nothing it nests.
    if let Some(authored) = &el.attrs.widget_attributes
        && let Some(spawn) = lumen_widget::widget_spawner(&el.tag)
    {
        let attrs = lumen_widget::Attributes::from(authored.clone());
        spawn(id, &attrs, world);
    }
    // `<for each="...">` blocks attach a [`ForMarker`] to the spawned entity
    // and DEFER child spawning to the reconciler - children are the
    // body template, instantiated per-item against the named
    // ArraySignals at runtime.
    if el.tag == "for"
        && let Some(name) = &el.attrs.each
    {
        world.entity_mut(id).insert(ForMarker {
            array_name: name.clone(),
            body: el.children.clone(),
            key_field: el.attrs.key.clone(),
            cached_keys: Vec::new(),
            virtualized: el.attrs.virtualized,
            row_height: el.attrs.row_height.unwrap_or(32.0),
            win_rows: Vec::new(),
            cascaded_body: None,
            row_items: Vec::new(),
        });
    } else if (el.tag == "if" || el.tag == "dialog")
        && let Some(name) = &el.attrs.if_signal
    {
        world.entity_mut(id).insert(IfMarker {
            signal_name: name.clone(),
            body: el.children.clone(),
            currently_mounted: false,
            mode: el.attrs.if_mode.into(),
            eq: el.attrs.if_eq.clone(),
            applied_visible: None,
        });
        if el.tag == "dialog" {
            world.entity_mut(id).insert((
                DialogMarker,
                lumen_core::components::FocusBoundary,
                // Modal overlay: paint the dialog subtree in the
                // top-layer band, over all normal content.
                lumen_core::render_world::OverlayLayer,
            ));
        }
    } else {
        for child in &el.children {
            spawn_element(world, child, Some(id));
        }
    }
    id
}

/// Bring a just-spawned tree in line with the state the app starts in, before
/// its first tick.
///
/// `on_start` has run by the time the tree spawns and its signal writes are in
/// the store, but the `<if>` and `<for>` bodies they open are mounted by the
/// reconcilers, which run on a tick. Run here once, so the tree the first
/// tick indexes already holds them: `on_ready`, which runs on that tick, finds
/// an element inside an `<if>` that starts truthy, and a node it appends
/// there attaches. Writes queued on the external buses (a host's typed
/// signal builtins, an embedder writing before the run) are taken in first.
///
/// One pass: an `<if>` inside a body mounted here mounts on the first tick.
pub fn settle_tree(world: &mut bevy_ecs::world::World) {
    use bevy_ecs::system::RunSystemOnce;
    // A world missing what a pass reads (a bare test app) skips that pass;
    // the first tick runs the same systems with the same result.
    let _ = world.run_system_once(lumen_core::property_store::drain_external_properties);
    let _ = world.run_system_once(lumen_core::signals::drain_external_signals);
    let _ = world.run_system_once(reconcile_for_blocks);
    let _ = world.run_system_once(reconcile_if_blocks);
}

/// Reconcile every `<if>` block against the current [`PropertyStore`]
/// truthiness. Truthy: property exists AND value is not empty AND is not
/// literal `"false"` / `"0"`.
///
/// Mode policy:
///
/// * `IfMode::Render` (default) - despawn the body on falsy, respawn
///   on truthy. Cheap memory; loses focus / scroll / per-row signals
///   across the toggle.
/// * `IfMode::Hide` - mount the body once on the first truthy
///   transition. Hiding flows through `Style.display = Display::None`
///   on the if-marker entity (spec section 17.4: space is released, siblings
///   reflow on the next tick via `Changed<Style>`) and additionally
///   stamps `Visible(false)` so the render extract, hit-test, and
///   focus paths skip the subtree while all descendant state (focus,
///   scroll, per-row signals) survives. Both writes happen only on an
///   actual transition (D5) - steady ticks touch nothing, so
///   `FrameDirty` stays clear.
pub fn reconcile_if_blocks(
    store: bevy_ecs::system::Res<PropertyStore>,
    mut markers: bevy_ecs::system::Query<(
        Entity,
        &mut IfMarker,
        Option<&bevy_ecs::hierarchy::Children>,
    )>,
    mut styles: bevy_ecs::system::Query<(
        &mut lumen_core::components::Style,
        &mut lumen_core::style_overrides::StyleOverrides,
    )>,
    fade_targets: bevy_ecs::system::Query<(
        Option<&lumen_primitives::TransitionSpecs>,
        Option<&lumen_core::components::Opacity>,
    )>,
    mut commands: bevy_ecs::system::Commands,
) {
    for (parent_id, mut marker, children) in markers.iter_mut() {
        let value: Option<std::sync::Arc<str>> = store.get_global_str(&marker.signal_name);
        let value_str: Option<&str> = value.as_deref();
        let now_truthy = match &marker.eq {
            Some(expected) => value_str == Some(expected.as_str()),
            None => value_str.is_some_and(signal_is_truthy),
        };
        match marker.mode {
            IfMode::Render => {
                if now_truthy == marker.currently_mounted {
                    continue;
                }
                if now_truthy {
                    for tmpl in &marker.body {
                        // A gated body was walked with the tree it came in
                        // with, so its placeholders hold what the app was
                        // built from. That is the state the web emitter wrote
                        // the same branch with, which is what lets a browser
                        // adopt it instead of rebuilding it.
                        spawn_body_child(
                            &mut commands,
                            tmpl,
                            parent_id,
                            Placeholders::Resolved,
                            BodyChild::Gated,
                        );
                    }
                    // Entering transition on the block itself (children
                    // handle their own via `spawn_body_child`).
                    if let Ok((specs, cur)) = fade_targets.get(parent_id)
                        && let Some(bundle) = mount_fade_bundle(specs, cur.copied())
                    {
                        commands.entity(parent_id).insert(bundle);
                    }
                    marker.currently_mounted = true;
                } else {
                    if let Some(kids) = children {
                        for child in kids.iter() {
                            commands.entity(child).despawn();
                        }
                    }
                    marker.currently_mounted = false;
                }
            }
            IfMode::Hide => {
                // First-time mount happens on the first truthy tick:
                // spawn the subtree once; subsequent toggles only flip
                // visibility state.
                if now_truthy && !marker.currently_mounted {
                    for tmpl in &marker.body {
                        spawn_body_child(
                            &mut commands,
                            tmpl,
                            parent_id,
                            Placeholders::Resolved,
                            BodyChild::Gated,
                        );
                    }
                    marker.currently_mounted = true;
                }
                // D5: apply visibility only on a transition. The
                // unconditional per-tick re-insert kept Changed<Visible>
                // (and thus FrameDirty) permanently hot.
                if marker.applied_visible == Some(now_truthy) {
                    continue;
                }
                marker.applied_visible = Some(now_truthy);
                commands
                    .entity(parent_id)
                    .insert(lumen_core::components::Visible(now_truthy));
                // Entering transition on show (mount-direction only -
                // hide stays instant; CSS can't run removal transitions
                // without JS either). Check the `<if>` entity itself
                // (e.g. `<dialog>`) and its mounted body roots (e.g.
                // the synthetic dropdown / menu `.dropdown-panel`
                // children, which carry the CSS transition specs).
                if now_truthy {
                    let mut targets: Vec<Entity> = vec![parent_id];
                    if let Some(kids) = children {
                        targets.extend(kids.iter());
                    }
                    for target in targets {
                        if let Ok((specs, cur)) = fade_targets.get(target)
                            && let Some(bundle) = mount_fade_bundle(specs, cur.copied())
                        {
                            commands.entity(target).insert(bundle);
                        }
                    }
                }
                // section 17.4: hide releases the block's layout space via
                // Display::None; show lets go of it. The Style mutation
                // trips Changed<Style> -> DirtyLayout, so siblings reflow on
                // this same tick's LayoutSync.
                if let Ok((mut style, mut overrides)) = styles.get_mut(parent_id) {
                    let out = if now_truthy {
                        overrides.release::<IfMarker>()
                    } else {
                        let live = Live {
                            style: Some(&style),
                            ..Live::default()
                        };
                        let hidden = StyleValues {
                            display: Some(lumen_core::components::Display::None),
                            ..StyleValues::default()
                        };
                        overrides.hold::<IfMarker>(hidden, &live)
                    };
                    out.write_style(&mut style);
                }
            }
        }
    }
}

/// On Escape, close the top-most open popup layer - one press peels off
/// exactly one layer.
///
/// Priority mirrors paint order (later-painted popups sit on top):
///
/// 1. an open `<dropdown>` panel (`__dropdown_open:*` signal is `true`),
/// 2. otherwise an open `<menu>` panel (`__menu_open:*` signal is `true`),
/// 3. otherwise the top-most open `<dialog>`.
///
/// Dropdown / menu panels are gated by `<if eq="true" mode="hide">`
/// blocks whose [`IfMarker::signal_name`] is the synthetic open signal,
/// so the same `IfMarker` query that drives dialogs finds them too -
/// no dependency on the panel's runtime marker components (which the
/// `<if>`-body template path does not propagate). Closing writes the
/// open signal to `false` (dropdown / menu) or `""` (dialog); the next
/// `reconcile_if_blocks` tick flips `Visible(false)` on the subtree
/// (`IfMode::Hide` preserves child state across the toggle).
///
/// Bare Esc keypresses with nothing open pass through untouched.
///
/// An Escape that cancelled an in-flight press
/// (`lumen_input::cancel_press_on_escape` sets
/// [`EscapePressCancel`](lumen_core::input::EscapePressCancel) earlier
/// in the Input stage) is consumed by the cancel - the dialog stays
/// open on that keystroke.
pub fn close_dialogs_on_escape(
    mut keys: bevy_ecs::message::MessageReader<lumen_core::input::KeyPressed>,
    press_cancel: Option<bevy_ecs::system::Res<lumen_core::input::EscapePressCancel>>,
    mut store: bevy_ecs::system::ResMut<PropertyStore>,
    blocks: bevy_ecs::system::Query<(
        &IfMarker,
        Option<&lumen_core::components::Visible>,
        Option<&DialogMarker>,
    )>,
) {
    let escape_pressed = keys.read().any(|k| {
        matches!(
            &k.key,
            lumen_core::input::Key::Named(lumen_core::input::NamedKey::Escape)
        )
    });
    if !escape_pressed {
        return;
    }
    if press_cancel.is_some_and(|f| f.0) {
        return;
    }

    // 1. Top-most layer: an open dropdown panel.
    for (marker, _visible, _dialog) in &blocks {
        if marker.signal_name.starts_with("__dropdown_open:")
            && store.get_global_bool(&marker.signal_name) == Some(true)
        {
            store.set_global_bool(&marker.signal_name, false);
            return;
        }
    }
    // 2. Next: an open menu panel.
    for (marker, _visible, _dialog) in &blocks {
        if marker.signal_name.starts_with("__menu_open:")
            && store.get_global_bool(&marker.signal_name) == Some(true)
        {
            store.set_global_bool(&marker.signal_name, false);
            return;
        }
    }
    // 3. Finally: the top-most open `<dialog>`.
    for (marker, visible, dialog) in &blocks {
        if dialog.is_none() {
            continue;
        }
        let open = visible.map(|v| v.0).unwrap_or(true);
        if !open {
            continue;
        }
        let curr = store.get_global_str(&marker.signal_name);
        if curr.as_deref() != Some("") {
            store.set_global_str(&marker.signal_name, "");
            return;
        }
    }
}

/// Collect every descendant of `root` (excluding `root` itself),
/// depth-first via `Children`.
fn collect_descendants(
    root: Entity,
    children: &bevy_ecs::system::Query<&bevy_ecs::hierarchy::Children>,
    out: &mut Vec<Entity>,
) {
    if let Ok(kids) = children.get(root) {
        for kid in kids.iter() {
            out.push(kid);
            collect_descendants(kid, children, out);
        }
    }
}

/// Qt QDialog lifecycle (W5): initial focus on open, focus restore on
/// close, and the exactly-once accepted/rejected close event.
///
/// Open edge (`Visible` flips true):
/// - remember the current focus holder,
/// - focus the first `autofocus` descendant; else the first focusable
///   (`TabIndex >= 0`, enabled) descendant in markup order; else the
///   dialog panel itself. The body mounts via deferred commands one
///   tick after the edge, so the pass retries (`needs_focus`) until a
///   target exists.
///
/// Close edge:
/// - emit exactly one [`lumen_core::input::DialogClosed`] -
///   `accepted` when the default button drove the close
///   ([`DialogSession::pending_accept`]), `rejected` otherwise
///   (Escape, cancel buttons, script writes),
/// - restore focus to the pre-open holder when focus still sits
///   inside the dialog subtree (a close caused by focusing another
///   widget doesn't yank focus back) - mirrors
///   `lumen_primitives::popup_nav_lifecycle`.
///
/// The Tab focus trap itself is `lumen_input::cycle_focus_on_tab` +
/// the `FocusBoundary` the spawner puts on every `<dialog>`.
#[allow(clippy::too_many_arguments, clippy::type_complexity)]
pub fn manage_dialog_lifecycle(
    mut commands: bevy_ecs::system::Commands,
    mut tracker: bevy_ecs::system::ResMut<lumen_core::input::FocusTracker>,
    mut dialogs: bevy_ecs::system::Query<
        (
            Entity,
            Option<&lumen_core::components::Visible>,
            Option<&mut DialogSession>,
            Option<&lumen_core::components::LumenId>,
            &IfMarker,
        ),
        With<DialogMarker>,
    >,
    children: bevy_ecs::system::Query<&bevy_ecs::hierarchy::Children>,
    parents: bevy_ecs::system::Query<&bevy_ecs::hierarchy::ChildOf>,
    focusables: bevy_ecs::system::Query<
        (
            &lumen_core::components::TabIndex,
            Option<&lumen_core::components::DocumentOrder>,
        ),
        Without<lumen_core::components::Disabled>,
    >,
    autofocused: bevy_ecs::system::Query<
        Option<&lumen_core::components::DocumentOrder>,
        (With<AutoFocus>, Without<lumen_core::components::Disabled>),
    >,
    focus_visibles: bevy_ecs::system::Query<(), With<lumen_core::input::FocusVisible>>,
    live: bevy_ecs::system::Query<Entity, Without<bevy_ecs::resource::IsResource>>,
    mut closed_out: bevy_ecs::message::MessageWriter<lumen_core::input::DialogClosed>,
) {
    for (dialog_e, visible, session, lumen_id, marker) in dialogs.iter_mut() {
        let open = visible.map(|v| v.0).unwrap_or(false);
        let Some(mut session) = session else {
            // First sighting: seed the tracker WITHOUT treating the
            // initial state as an edge (a dialog that spawns closed
            // must not fire `rejected`; one that spawns open skips the
            // focus grab - it was never interactively opened).
            commands.entity(dialog_e).insert(DialogSession {
                open,
                ..Default::default()
            });
            continue;
        };
        if open && !session.open {
            // Open edge.
            session.open = true;
            session.needs_focus = true;
            session.pending_accept = false;
            session.prev_focus = tracker.0;
            session.prev_focus_visible = tracker
                .0
                .map(|e| focus_visibles.contains(e))
                .unwrap_or(false);
        } else if !open && session.open {
            // Close edge: exactly one accepted-or-rejected per cycle.
            session.open = false;
            session.needs_focus = false;
            let id = lumen_id
                .map(|i| i.0.clone())
                .unwrap_or_else(|| marker.signal_name.clone());
            closed_out.write(lumen_core::input::DialogClosed {
                entity: dialog_e,
                id,
                accepted: session.pending_accept,
            });
            session.pending_accept = false;
            // Focus restore - only when focus still sits inside the
            // dialog subtree (or on the dialog itself / nowhere).
            let focus_inside = match tracker.0 {
                None => true,
                Some(cur) => {
                    let mut e = cur;
                    loop {
                        if e == dialog_e {
                            break true;
                        }
                        match parents.get(e) {
                            Ok(co) => e = co.parent(),
                            Err(_) => break false,
                        }
                    }
                }
            };
            if focus_inside {
                if let Some(cur) = tracker.0 {
                    commands
                        .entity(cur)
                        .remove::<(lumen_core::input::Focused, lumen_core::input::FocusVisible)>();
                }
                match session.prev_focus.filter(|e| live.get(*e).is_ok()) {
                    Some(prev) => {
                        commands.entity(prev).insert(lumen_core::input::Focused);
                        if session.prev_focus_visible {
                            commands
                                .entity(prev)
                                .insert(lumen_core::input::FocusVisible);
                        }
                        tracker.0 = Some(prev);
                    }
                    None => {
                        tracker.0 = None;
                    }
                }
            }
        }
        if session.open && session.needs_focus {
            // Initial-focus pass: retried until the deferred body
            // mount produced a target.
            let mut descendants = Vec::new();
            collect_descendants(dialog_e, &children, &mut descendants);
            if descendants.is_empty() {
                continue; // body not mounted yet - retry next tick
            }
            let pick = |pred: &mut dyn FnMut(Entity) -> Option<u32>| -> Option<Entity> {
                let mut best: Option<(u32, Entity)> = None;
                for &d in &descendants {
                    if let Some(order) = pred(d) {
                        let candidate = (order, d);
                        if best.map(|b| candidate < b).unwrap_or(true) {
                            best = Some(candidate);
                        }
                    }
                }
                best.map(|(_, e)| e)
            };
            let target = pick(&mut |e| {
                autofocused
                    .get(e)
                    .ok()
                    .map(|doc| doc.map(|d| d.0).unwrap_or(u32::MAX))
            })
            .or_else(|| {
                pick(&mut |e| {
                    focusables
                        .get(e)
                        .ok()
                        .filter(|(ti, _)| ti.0 >= 0)
                        .map(|(_, doc)| doc.map(|d| d.0).unwrap_or(u32::MAX))
                })
            })
            .unwrap_or(dialog_e);
            if let Some(cur) = tracker.0
                && cur != target
            {
                commands
                    .entity(cur)
                    .remove::<(lumen_core::input::Focused, lumen_core::input::FocusVisible)>();
            }
            commands.entity(target).insert(lumen_core::input::Focused);
            tracker.0 = Some(target);
            session.needs_focus = false;
        }
    }
}

/// Enter anywhere in an open `<dialog>` activates its DEFAULT button
/// (Qt QDialog default-button contract) - unless focus sits on a
/// button (its own Enter->click path wins) or on a multiline text
/// input (Enter inserts a newline). Single-line inputs DO trigger the
/// default (Qt/web: Enter in a line edit fires the default button)
/// alongside their own commit event.
///
/// The default button is the first enabled [`DefaultButton`]
/// descendant; with none marked, the first enabled `<button>` in
/// markup order (Qt autoDefault). The synthesized [`ClickEvent`] flows
/// through the normal click dispatchers, so scripts observe a regular
/// `on_click`. Activation through THIS path always marks the close
/// `accepted` ([`DialogSession::pending_accept`]); direct pointer
/// clicks mark it only for an explicitly `default="true"` button
/// ([`mark_dialog_accept_on_default_click`]).
#[allow(clippy::too_many_arguments, clippy::type_complexity)]
pub fn activate_dialog_default_on_enter(
    mut keys: bevy_ecs::message::MessageReader<lumen_core::input::KeyPressed>,
    tracker: bevy_ecs::system::Res<lumen_core::input::FocusTracker>,
    mut dialogs: bevy_ecs::system::Query<
        (
            Entity,
            Option<&lumen_core::components::Visible>,
            Option<&mut DialogSession>,
        ),
        With<DialogMarker>,
    >,
    children: bevy_ecs::system::Query<&bevy_ecs::hierarchy::Children>,
    tags: bevy_ecs::system::Query<&lumen_core::components::LumenTag>,
    inputs: bevy_ecs::system::Query<&lumen_core::components::TextInput>,
    defaults: bevy_ecs::system::Query<(), With<DefaultButton>>,
    disabled: bevy_ecs::system::Query<(), With<lumen_core::components::Disabled>>,
    orders: bevy_ecs::system::Query<&lumen_core::components::DocumentOrder>,
    mut clicks: bevy_ecs::message::MessageWriter<lumen_core::input::ClickEvent>,
) {
    let enter = keys.read().any(|k| {
        !k.repeat
            && matches!(
                &k.key,
                lumen_core::input::Key::Named(lumen_core::input::NamedKey::Enter)
            )
    });
    if !enter {
        return;
    }
    // Focus exclusions: a focused button consumes Enter itself; a
    // multiline input inserts a newline.
    if let Some(focused) = tracker.0 {
        if tags.get(focused).is_ok_and(|t| t.0.as_ref() == "button") {
            return;
        }
        if inputs.get(focused).is_ok_and(|i| i.multiline) {
            return;
        }
    }
    // Top-most open dialog.
    let Some((dialog_e, session)) = dialogs
        .iter_mut()
        .filter(|(_, vis, _)| vis.map(|v| v.0).unwrap_or(false))
        .map(|(e, _, s)| (e, s))
        .next()
    else {
        return;
    };
    let mut descendants = Vec::new();
    collect_descendants(dialog_e, &children, &mut descendants);
    let best_by_order = |pred: &dyn Fn(Entity) -> bool| -> Option<Entity> {
        descendants
            .iter()
            .copied()
            .filter(|&e| pred(e) && !disabled.contains(e))
            .min_by_key(|&e| (orders.get(e).map(|d| d.0).unwrap_or(u32::MAX), e))
    };
    let target = best_by_order(&|e| defaults.contains(e))
        .or_else(|| best_by_order(&|e| tags.get(e).is_ok_and(|t| t.0.as_ref() == "button")));
    let Some(target) = target else {
        return;
    };
    if let Some(mut session) = session {
        session.pending_accept = true;
    }
    clicks.write(lumen_core::input::ClickEvent {
        entity: target,
        position: glam::Vec2::ZERO,
        button: lumen_core::input::PointerButton::Primary,
        local: None,
    });
}

/// A direct click on an explicitly-marked [`DefaultButton`] inside an
/// open dialog resolves that dialog's eventual close as `accepted`.
/// Text-child hit-shadowing is handled with the same ancestor walk the
/// control dispatchers use.
pub fn mark_dialog_accept_on_default_click(
    mut clicks: bevy_ecs::message::MessageReader<lumen_core::input::ClickEvent>,
    defaults: bevy_ecs::system::Query<(), With<DefaultButton>>,
    parents: bevy_ecs::system::Query<&bevy_ecs::hierarchy::ChildOf>,
    mut sessions: bevy_ecs::system::Query<&mut DialogSession, With<DialogMarker>>,
) {
    for ev in clicks.read() {
        // Resolve the clicked entity to a DefaultButton (self or
        // ancestor), then keep walking to the containing dialog.
        let mut cur = Some(ev.entity);
        let mut hit_default = false;
        while let Some(e) = cur {
            if !hit_default && defaults.contains(e) {
                hit_default = true;
            }
            if hit_default && let Ok(mut session) = sessions.get_mut(e) {
                session.pending_accept = true;
                break;
            }
            cur = parents.get(e).ok().map(|c| c.parent());
        }
    }
}

/// Reconcile every `<for>` block against the current
/// [`ArraySignals`][lumen_core::signals::ArraySignals] state.
///
/// **Reconciliation policy (alpha7):**
/// * Equal key sequence -> nothing mounts or unmounts.
/// * In every case that keeps rows, a kept row whose record changed has
///   its placeholders resolved again and written onto its existing
///   entities, so it keeps focus / scroll / animation state and shows the
///   new record. A row the template no longer lines up with (a script
///   reshaped it, or the change reaches a nested `<for>` / `<if>` body or
///   a component use site) cannot follow in place and the block rebuilds.
/// * New keys are an extension of cached (cached is a prefix of new) ->
///   spawn only the appended items. Common case: `signal_array.push(...)`
///   adds one item, only the new row spawns; existing rows keep their
///   focus / scroll / `Signals` state.
/// * Cached keys are an extension of new (new is a prefix of cached) ->
///   despawn only the trailing entities. Common case: pop / clear-tail.
/// * Anything else (reorder, mid-insert, mid-remove) -> full rebuild.
///   Real keyed reconciliation across arbitrary reorders requires
///   re-anchoring `ChildOf` in bevy_ecs and lands as a follow-up.
#[allow(clippy::too_many_arguments)]
pub fn reconcile_for_blocks(
    array_signals: bevy_ecs::system::Res<lumen_core::signals::ArraySignals>,
    // Wave-D: `InterpolationSlot::Global(name)` substitutions read the
    // canonical typed PropertyStore so `{$theme}` inside a `<for>` body
    // resolves correctly. Pre wave-D this consulted the `Signals` resource;
    // every internal write now lands on PropertyStore so reading either
    // layer would yield the same result, but PropertyStore is the
    // canonical source post wave-D.
    store: bevy_ecs::system::Res<PropertyStore>,
    mut markers: bevy_ecs::system::Query<(
        Entity,
        &mut ForMarker,
        Option<&bevy_ecs::hierarchy::Children>,
    )>,
    mut commands: bevy_ecs::system::Commands,
    lookup: RowLookup,
    // Walk the [`ChildOf`] chain to locate the nearest [`Scroll`] ancestor's [`ScrollOffset`] and [`Transform`].
    // Virtualised for-blocks consult them to spawn only rows in the visible band; plain for-blocks
    // ignore these queries entirely.
    parents: bevy_ecs::system::Query<&bevy_ecs::hierarchy::ChildOf>,
    scroll_state: bevy_ecs::system::Query<
        (
            &lumen_core::input::ScrollOffset,
            &lumen_core::components::Transform,
        ),
        With<lumen_core::input::Scroll>,
    >,
    styles: bevy_ecs::system::Query<&lumen_core::components::Style>,
    stylesheet: Option<bevy_ecs::system::Res<LumenStylesheet>>,
    policy: Option<bevy_ecs::system::Res<ScenePolicy>>,
) {
    let policy = policy.map(|p| *p).unwrap_or_default();
    // Nothing wrote an array since the last pass, so every mounted row
    // still shows the record it was built from.
    let arrays_changed = array_signals.is_changed();
    let css_changed = stylesheet.as_ref().map(|s| s.is_changed()).unwrap_or(false);
    // Under `RowStyle::HostStyled` the rows reach a cascade of their own, so
    // every substitution below hands the template on unresolved.
    let row_css = match policy.row_style {
        RowStyle::Cascade => stylesheet.as_ref().map(|s| &s.0),
        RowStyle::HostStyled => None,
    };
    for (parent_id, mut marker, children) in markers.iter_mut() {
        // The row has no entity yet, so the block stands in as the
        // discriminator that keeps a typo'd field on a 1000-row list to one
        // warning.
        let report_missing = |field: &str| warn_missing_row_field_once(parent_id, field);
        // Borrow the array in place - the old `.to_vec()` deep-cloned
        // every `ArrayItem` HashMap (5 000 rows x per-field Strings) on
        // EVERY tick, dominating the idle reconcile cost on big grids.
        let items: &[ArrayItem] = array_signals
            .get(&marker.array_name)
            .unwrap_or(&[] as &[ArrayItem]);

        // Virtualised branch: derive the visible row range from the nearest `<scroll>` ancestor's [`ScrollOffset`] and [`Transform`],
        // spawning only rows in that window plus an overscan buffer above
        // and below, and absolute-position each row at
        // `top = row_index * row_height` so layout stays predictable
        // regardless of which subset is mounted. Author opts in via
        // `<for virtualized="true" row-height="N">`.
        //
        // Spec section 15.3 windowed reuse: a window shift keeps every row whose
        // `(index, key)` is unchanged - only rows entering the window
        // spawn and rows leaving it despawn. Pre-fix, every 1-row shift
        // despawned + respawned the ENTIRE band (with a full per-row CSS
        // cascade), which is what made 5k-row wheel scrolling lag.
        if marker.virtualized && policy.virtualization == Virtualization::Enabled {
            let row_h = marker.row_height.max(1.0);
            // Walk ChildOf upward from the for-block looking for an
            // ancestor with a `Scroll` component. Read its scroll
            // offset + viewport height so the windowing math knows
            // where the user is looking. No scroll ancestor = window
            // anchored at the top with the viewport defaulting to a
            // tall default so apps still see some rows.
            let mut anc = parents.get(parent_id).ok().map(|c| c.parent());
            let mut offset_y = 0.0_f32;
            let mut viewport_h = 600.0_f32;
            while let Some(e) = anc {
                if let Ok((off, t)) = scroll_state.get(e) {
                    offset_y = off.0.y.max(0.0);
                    viewport_h = t.size.y.max(0.0);
                    break;
                }
                anc = parents.get(e).ok().map(|c| c.parent());
            }
            // Overscan: rows mounted beyond both window edges so a small
            // shift lands on already-mounted rows and the per-frame mount
            // cost amortises across several frames of scrolling.
            //
            // Considered and rejected (wave-3 scroll-p95 work): quantizing
            // the window to N-row pages to batch mounts. Measured on the
            // 10k-row bench it left p95 unchanged (per-row mount spikes
            // were never the p95 tail - external drive-loop jitter is)
            // and regressed p99 ~18.2 -> ~20.5 ms because the batched
            // 12-row mount tick costs more than any per-row tick. Per-row
            // shifting keeps the worst single tick small.
            const BUFFER_ROWS: usize = 8;
            let first = ((offset_y / row_h).floor() as i64 - BUFFER_ROWS as i64).max(0) as usize;
            let last =
                (((offset_y + viewport_h) / row_h).ceil() as usize + BUFFER_ROWS).min(items.len());

            // Pin the for-block's height to total_rows * row_h so taffy
            // gives the scroll content the right extent. Without this
            // the for-block sizes to 0 (no flex children - every row is
            // position: absolute) and rows escape upward into the
            // scroll's siblings (e.g. the toolbar/header) because the
            // containing block has no height to clip against. The size is
            // held over the block's own styles, so author CSS on it
            // (padding, etc.) stays intact and a restyle keeps the size.
            //
            // Taffy's default `flex_shrink: 1.0` clamps the for-block
            // down to the parent scroll viewport even when we set an
            // explicit `height: content_h`. Pin `min_height` to the
            // same value so Taffy can't shrink it - that's what gives
            // the scroll a content extent larger than the viewport
            // (without it the user can't scroll down past viewport).
            let content_h = items.len() as f32 * row_h;
            let extent = lumen_core::components::Length::Px(content_h);
            // D4: only write when the size differs. An
            // unconditional write every steady tick re-triggered
            // Changed<Style> -> DirtyLayout -> relayout -> FrameDirty - a
            // permanent per-tick relayout/repaint loop on virtualized
            // for-blocks.
            if styles
                .get(parent_id)
                .map(|s| s.height != extent || s.min_height != extent)
                .unwrap_or(true)
            {
                let held = StyleValues {
                    width: Some(lumen_core::components::Length::Percent(100.0)),
                    height: Some(extent),
                    min_height: Some(extent),
                    ..StyleValues::default()
                };
                commands.entity(parent_id).queue(
                    move |mut ent: bevy_ecs::world::EntityWorldMut<'_>| {
                        lumen_core::style_overrides::hold_on::<ForMarker>(&mut ent, held);
                    },
                );
            }

            // Desired `(index, key)` pairs for the current window. Keys
            // are built for WINDOW rows only - never all 5 000.
            let key_field = marker.key_field.clone();
            let key_of = |i: usize, item: &ArrayItem| -> String {
                key_field
                    .as_ref()
                    .and_then(|f| item.get(f).cloned())
                    .unwrap_or_else(|| i.to_string())
            };
            let desired: Vec<(usize, String)> = items
                .iter()
                .enumerate()
                .skip(first)
                .take(last.saturating_sub(first))
                .map(|(i, item)| (i, key_of(i, item)))
                .collect();

            // Stylesheet changed (hot reload / first insert): drop the
            // cascaded-template cache so rows restyle on next spawn.
            if css_changed {
                marker.cascaded_body = None;
            }

            // Steady state: same window -> nothing to do. Both lists run
            // in row-index order: `desired` is built that way and
            // `win_rows` is re-sorted into it at the end of this branch,
            // in step with the children list it indexes into.
            if children.is_some() && marker.win_rows == desired && !arrays_changed {
                continue;
            }

            let body_len = marker.body.len().max(1);
            let kids: Vec<Entity> = children.map(|c| c.iter().collect()).unwrap_or_default();
            // Every mounted row owns `body_len` consecutive children in
            // spawn order. If something else despawned a child out from
            // under us, alignment is gone - fall back to a full rebuild.
            let aligned = kids.len() == marker.win_rows.len() * body_len;

            // Rows to keep: `(index, key)` present in both the mounted
            // set and the desired window.
            let desired_by_idx: std::collections::HashMap<usize, &str> =
                desired.iter().map(|(i, k)| (*i, k.as_str())).collect();
            let mut new_win: Vec<(usize, String)> = Vec::new();
            let mut new_items: Vec<ArrayItem> = Vec::new();
            let mut patches: Vec<RowPatch> = Vec::new();
            let row_template = RowTemplate {
                body: &marker.body,
                store: &store,
                css: row_css,
            };
            if aligned {
                for (row_i, (idx, key)) in marker.win_rows.iter().enumerate() {
                    let slice = &kids[row_i * body_len..(row_i + 1) * body_len];
                    let was = marker.row_items.get(row_i);
                    // A mounted row's index points into the array it was
                    // built from, which may since have shrunk past it. Only
                    // a row still in the desired window reads its record,
                    // and every desired index is in bounds.
                    let item =
                        (desired_by_idx.get(idx) == Some(&key.as_str())).then(|| &items[*idx]);
                    // A kept row whose record changed follows it in place;
                    // one that cannot is dropped and mounts again below.
                    let kept = item.filter(|&item| {
                        was == Some(item)
                            || row_template.plan(
                                slice,
                                (was, item),
                                *idx,
                                &report_missing,
                                &lookup,
                                &mut patches,
                            )
                    });
                    if let Some(item) = kept {
                        new_win.push((*idx, key.clone()));
                        new_items.push(item.clone());
                    } else {
                        for child in slice {
                            commands.entity(*child).despawn();
                        }
                    }
                }
            } else {
                for child in &kids {
                    commands.entity(*child).despawn();
                }
            }
            let mounted: std::collections::HashSet<usize> =
                new_win.iter().map(|(i, _)| *i).collect();

            // Cascade-once-per-template (spec section 15.3): apply the CSS
            // cascade to the body template a single time and substitute
            // per-row placeholders into the pre-cascaded clone. Falls
            // back to per-row cascade when `id` / `class` attrs carry
            // `{...}` placeholders (selector matching would then depend on
            // the substituted values).
            let per_row_cascade = body_has_dynamic_selector_attrs(&marker.body);
            let template: std::sync::Arc<Vec<Element>> = match (per_row_cascade, row_css) {
                (true, _) | (false, None) => std::sync::Arc::new(marker.body.clone()),
                (false, Some(_)) if marker.cascaded_body.is_some() => {
                    marker.cascaded_body.clone().expect("checked above")
                }
                (false, Some(sheet)) => {
                    let cascaded: Vec<Element> = marker
                        .body
                        .iter()
                        .map(|el| {
                            let mut c = el.clone();
                            cascade_element_tree(&mut c, sheet);
                            c
                        })
                        .collect();
                    let arc = std::sync::Arc::new(cascaded);
                    marker.cascaded_body = Some(arc.clone());
                    arc
                }
            };

            for (i, key) in &desired {
                if mounted.contains(i) {
                    continue;
                }
                let item = &items[*i];
                let scope = Scope::new(&*store)
                    .with_row(item, *i)
                    .reporting_to(&report_missing);
                for tmpl in template.iter() {
                    // Substitute placeholders; run the cascade only on
                    // the per-row fallback path (pre-cascaded otherwise).
                    let inst = substitute_in_element_with_css(
                        tmpl,
                        &scope,
                        if per_row_cascade { row_css } else { None },
                    );
                    // The row lands in the absolute slot its index gives
                    // it inside the for-block: pinned at `top = i * row_h`
                    // and left = 0, with `width=100%` + `height=row_h`
                    // setting its size. Setting `right` / `bottom` too
                    // would over-constrain taffy (it expects either inset
                    // OR size, not both on the same axis) and the row
                    // collapses to content width.
                    let slot = StyleValues {
                        position: Some(lumen_core::components::Position::Absolute),
                        inset: Some(lumen_core::components::Edges {
                            top: *i as f32 * row_h,
                            right: f32::NAN,
                            bottom: f32::NAN,
                            left: 0.0,
                            ..lumen_core::components::Edges::default()
                        }),
                        height: Some(lumen_core::components::Length::Px(row_h)),
                        width: Some(lumen_core::components::Length::Percent(100.0)),
                        ..StyleValues::default()
                    };
                    spawn_body_child(
                        &mut commands,
                        &inst,
                        parent_id,
                        Placeholders::Resolved,
                        BodyChild::VirtualRow(Box::new(slot)),
                    );
                }
                new_win.push((*i, key.clone()));
                new_items.push(item.clone());
            }
            if !patches.is_empty() {
                commands.queue(move |world: &mut World| apply_row_patches(world, patches));
            }
            // Rows reach `Children` in mount order: a kept row holds the
            // slot it already had and a row entering the window appends
            // at the end, so a scroll that pulls rows in at the front
            // leaves the hierarchy out of row order. Everything that
            // walks the tree reads that order: `node.children()`, the
            // document order selectors resolve against,
            // `renumber_document_order` and the Tab order it feeds. So
            // sort the mounted rows back by row index, and move
            // `win_rows` with them since the keep-path above slices the
            // children list by its positions.
            let mut row_order: Vec<usize> = (0..new_win.len()).collect();
            row_order.sort_unstable_by_key(|&r| new_win[r].0);
            if row_order.iter().enumerate().any(|(slot, &r)| slot != r) {
                new_win = row_order.iter().map(|&r| new_win[r].clone()).collect();
                new_items = row_order.iter().map(|&r| new_items[r].clone()).collect();
                commands.queue(move |world: &mut World| {
                    sort_virtual_rows(world, parent_id, body_len, &row_order);
                });
            }
            marker.win_rows = new_win;
            marker.row_items = new_items;
            continue;
        }

        // Build the new key list. If `key_field` is set, pull that field
        // from each record; otherwise fall back to the item's index.
        let new_keys: Vec<String> = items
            .iter()
            .enumerate()
            .map(|(i, item)| {
                marker
                    .key_field
                    .as_ref()
                    .and_then(|f| item.get(f).cloned())
                    .unwrap_or_else(|| i.to_string())
            })
            .collect();

        let same_keys = new_keys == marker.cached_keys && children.is_some();
        if same_keys && !arrays_changed {
            continue;
        }

        let body_len = marker.body.len();
        let cached = marker.cached_keys.clone();
        let appended = cached.len() < new_keys.len() && new_keys[..cached.len()] == cached[..];
        let trimmed = new_keys.len() < cached.len() && cached[..new_keys.len()] == new_keys[..];
        let kids: Vec<Entity> = children.map(|c| c.iter().collect()).unwrap_or_default();

        // The rows both key lists share sit at the front, `body_len`
        // children each. One whose record changed follows it in place;
        // `None` when any of them cannot, and the block rebuilds below.
        let kept_rows =
            (same_keys || appended || trimmed).then(|| cached.len().min(new_keys.len()));
        let aligned = kids.len() == cached.len() * body_len;
        let followed = kept_rows.and_then(|kept| {
            let row_template = RowTemplate {
                body: &marker.body,
                store: &store,
                css: row_css,
            };
            let mut patches: Vec<RowPatch> = Vec::new();
            let mut moved = false;
            for (i, item) in items.iter().enumerate().take(kept) {
                let was = marker.row_items.get(i);
                if was == Some(item) {
                    continue;
                }
                moved = true;
                if !aligned {
                    return None;
                }
                let roots = &kids[i * body_len..(i + 1) * body_len];
                if !row_template.plan(
                    roots,
                    (was, item),
                    i,
                    &report_missing,
                    &lookup,
                    &mut patches,
                ) {
                    return None;
                }
            }
            Some((patches, moved))
        });

        if let Some((patches, moved)) = followed {
            if !patches.is_empty() {
                commands.queue(move |world: &mut World| apply_row_patches(world, patches));
            }
            // Append-only: new = cached + tail. Spawn just the tail.
            if appended {
                for (i, item) in items.iter().enumerate().skip(cached.len()) {
                    let scope = Scope::new(&*store)
                        .with_row(item, i)
                        .reporting_to(&report_missing);
                    for tmpl in &marker.body {
                        let inst = substitute_in_element_with_css(tmpl, &scope, row_css);
                        spawn_body_child(
                            &mut commands,
                            &inst,
                            parent_id,
                            Placeholders::Resolved,
                            BodyChild::Row,
                        );
                    }
                }
            }
            // Trim-from-tail: cached = new + tail. Despawn the tail
            // entities (`body_len` per popped item, last-spawn-first).
            if trimmed {
                let drop_count = (cached.len() - new_keys.len()) * body_len;
                for child in kids.iter().rev().take(drop_count) {
                    commands.entity(*child).despawn();
                }
            }
            if moved || !same_keys {
                marker.row_items = items.to_vec();
            }
            marker.cached_keys = new_keys;
            continue;
        }

        // Fallback: full rebuild. Despawn all children and spawn fresh.
        // Loses focus / scroll / per-row signal state - same caveat as
        // pre-alpha7. Triggered only when the diff isn't a clean append or
        // trim (e.g. midstream insert, reorder, replace).
        if let Some(kids) = children {
            for child in kids.iter() {
                commands.entity(child).despawn();
            }
        }
        for (i, item) in items.iter().enumerate() {
            let scope = Scope::new(&*store)
                .with_row(item, i)
                .reporting_to(&report_missing);
            for tmpl in &marker.body {
                let inst = substitute_in_element_with_css(tmpl, &scope, row_css);
                spawn_body_child(
                    &mut commands,
                    &inst,
                    parent_id,
                    Placeholders::Resolved,
                    BodyChild::Row,
                );
            }
        }
        marker.cached_keys = new_keys;
        marker.row_items = items.to_vec();
    }
}

/// Which of an element's placeholder-carrying strings differ between two
/// instances of the same template: the strings
/// [`lumen_ir::interpolate::substitute_attrs`] resolves, grouped by the
/// component each one lands on.
#[derive(Clone, Copy, Debug, Default)]
struct RowStringChanges {
    /// `text` or `placeholder`, which reach the element through
    /// [`resolve_strings`].
    strings: bool,
    id: bool,
    classes: bool,
    src: bool,
    style_role: bool,
    drag_payload: bool,
}

impl RowStringChanges {
    fn between(old: &Attributes, new: &Attributes) -> Self {
        Self {
            strings: old.text != new.text || old.placeholder != new.placeholder,
            id: old.id != new.id,
            classes: old.classes != new.classes,
            src: old.src != new.src,
            style_role: old.style_role != new.style_role,
            drag_payload: old.drag_payload != new.drag_payload,
        }
    }

    fn any(self) -> bool {
        self.strings || self.id || self.classes || self.src || self.style_role || self.drag_payload
    }
}

/// One in-place write a kept `<for>` row needs: the entity, the attributes
/// its template resolves to for the new record, and which of them moved.
type RowPatch = (Entity, Box<Attributes>, RowStringChanges);

/// Whether a use site passes different arguments in two instances.
fn use_args_differ(old: &Element, new: &Element) -> bool {
    match (&old.frag_use, &new.frag_use) {
        (Some(a), Some(b)) => a.args != b.args,
        (None, None) => false,
        _ => true,
    }
}

/// Whether two instances of one template subtree resolve every placeholder
/// the same way.
fn same_resolution(old: &Element, new: &Element) -> bool {
    !RowStringChanges::between(&old.attrs, &new.attrs).any()
        && !use_args_differ(old, new)
        && old.children.len() == new.children.len()
        && old
            .children
            .iter()
            .zip(&new.children)
            .all(|(a, b)| same_resolution(a, b))
}

/// The children `spawn_element` builds for an element ahead of its markup
/// children: the knob of a `<toggle>` / `<switch>` and the thumb of a
/// `<slider>`.
fn generated_children(tag: &str) -> usize {
    usize::from(matches!(tag, "toggle" | "switch" | "slider"))
}

/// Collect the writes that take the entities `entity` heads from the `old`
/// instance of a row template to the `new` one. `false` when the row cannot
/// follow in place: the tree no longer has the shape the template spawned,
/// or a change reaches something that holds its own copy of the template (a
/// nested `<for>` / `<if>` body, a component use site).
fn plan_row_element(
    entity: Entity,
    old: &Element,
    new: &Element,
    lookup: &RowLookup<'_, '_>,
    out: &mut Vec<RowPatch>,
) -> bool {
    if !new.tag.is_empty() && lookup.tags.get(entity).map(|t| &*t.0) != Ok(new.tag.as_str()) {
        return false;
    }
    if use_args_differ(old, new) {
        return false;
    }
    let changes = RowStringChanges::between(&old.attrs, &new.attrs);
    if changes.any() {
        out.push((entity, Box::new(new.attrs.clone()), changes));
    }
    if old.children.len() != new.children.len() {
        return false;
    }
    // A marker keeps its body as a template and builds from it later; a use
    // site hands its children to the fragment. Neither is walked here, so a
    // change that reaches into one cannot be followed in place.
    let holds_template = new.frag_use.is_some()
        || (new.tag == "for" && new.attrs.each.is_some())
        || (matches!(new.tag.as_str(), "if" | "dialog") && new.attrs.if_signal.is_some());
    if holds_template {
        return old
            .children
            .iter()
            .zip(&new.children)
            .all(|(a, b)| same_resolution(a, b));
    }
    if new.children.is_empty() {
        return true;
    }
    let skip = generated_children(&new.tag);
    let Some(kids) = lookup
        .children
        .get(entity)
        .ok()
        .and_then(|c| c.get(skip..skip + new.children.len()))
    else {
        return false;
    };
    kids.iter()
        .zip(old.children.iter().zip(&new.children))
        .all(|(&kid, (o, n))| plan_row_element(kid, o, n, lookup, out))
}

/// The queries a kept row's walk reads to line its entities up with its
/// template.
#[derive(bevy_ecs::system::SystemParam)]
pub struct RowLookup<'w, 's> {
    children: bevy_ecs::system::Query<'w, 's, &'static bevy_ecs::hierarchy::Children>,
    tags: bevy_ecs::system::Query<'w, 's, &'static lumen_core::components::LumenTag>,
}

/// What one `<for>` block's kept rows are rebuilt against when their
/// records change: the body template, the signals its `{$name}`
/// placeholders read, and the stylesheet its rows cascade through.
struct RowTemplate<'a> {
    body: &'a [Element],
    store: &'a PropertyStore,
    css: Option<&'a lumen_ir::css::Stylesheet>,
}

impl RowTemplate<'_> {
    /// Collect the writes that take a kept row, whose top-level entities
    /// are `roots`, from the record `old` to `new`, both at `index`.
    /// `false` when the row cannot follow in place; see
    /// [`plan_row_element`].
    fn plan(
        &self,
        roots: &[Entity],
        (old, new): (Option<&ArrayItem>, &ArrayItem),
        index: usize,
        report_missing: &dyn Fn(&str),
        lookup: &RowLookup<'_, '_>,
        out: &mut Vec<RowPatch>,
    ) -> bool {
        if roots.len() != self.body.len() {
            return false;
        }
        let unknown = ArrayItem::new();
        let old_scope = Scope::new(self.store).with_row(old.unwrap_or(&unknown), index);
        let new_scope = Scope::new(self.store)
            .with_row(new, index)
            .reporting_to(report_missing);
        roots.iter().zip(self.body).all(|(&root, tmpl)| {
            let before = substitute_in_element_with_css(tmpl, &old_scope, self.css);
            let after = substitute_in_element_with_css(tmpl, &new_scope, self.css);
            plan_row_element(root, &before, &after, lookup, out)
        })
    }
}

/// Write the planned in-place changes of kept `<for>` rows onto their
/// entities, the way `spawn_element` would have built them from the same
/// attributes.
fn apply_row_patches(world: &mut World, patches: Vec<RowPatch>) {
    use lumen_core::components::{BindText, LumenTag, TextInput};
    use lumen_core::input::Focused;
    use lumen_primitives::TooltipSource;
    let mut shown = world.query::<(
        Option<&mut TextContent>,
        Option<&mut TextInput>,
        Option<&mut TooltipSource>,
        Has<Focused>,
        Has<BindText>,
    )>();
    for (entity, attrs, changes) in patches {
        if world.get_entity(entity).is_err() {
            continue;
        }
        if changes.strings {
            let authored = AuthoredStrings::from(&*attrs);
            let strings = resolve_strings(
                world.get_resource::<lumen_core::i18n::AppI18n>(),
                &authored,
                attrs.format.as_deref(),
            );
            if world.get::<AuthoredStrings>(entity).is_some() {
                world.entity_mut(entity).insert(authored);
            }
            if let Ok((text, input, tooltip, focused, bound)) = shown.get_mut(world, entity) {
                // A `bind-text` element shows its signal, not the markup.
                let text = if bound { None } else { text };
                crate::i18n::write_strings(strings, text, input, tooltip, focused);
            }
        }
        let mut e = world.entity_mut(entity);
        // A new id, class or typography role can change what the element's
        // styles are, so the element restyles.
        if changes.id {
            match &attrs.id {
                Some(id) => e.insert(LumenId(id.clone())),
                None => e.remove::<LumenId>(),
            };
            e.insert(lumen_core::components::StyleDirty);
        }
        if changes.classes {
            if attrs.classes.is_empty() {
                e.remove::<LumenClasses>();
            } else {
                e.insert(LumenClasses::from(attrs.classes.clone()));
            }
            e.insert(lumen_core::components::StyleDirty);
        }
        if changes.src && e.get::<LumenTag>().is_some_and(|t| &*t.0 == "image") {
            match &attrs.src {
                Some(src) => e.insert(lumen_assets::ImageSource(std::path::PathBuf::from(src))),
                None => e.remove::<lumen_assets::ImageSource>(),
            };
        }
        if changes.style_role {
            match attrs.style_role.as_deref() {
                Some(role) => e.insert(TypographyRole(role.into())),
                None => e.remove::<TypographyRole>(),
            };
            e.insert(lumen_core::components::StyleDirty);
        }
        // An empty payload is the element's `id`, so a new id moves it too.
        if changes.drag_payload || changes.id {
            match drag_source(&attrs) {
                Some(source) => e.insert(source),
                None => e.remove::<lumen_os_dnd::DragSource>(),
            };
        }
    }
}

/// True when any element in the template tree carries a `{...}` placeholder
/// inside a selector-relevant attr (`id` or `class`). Such templates must
/// run the CSS cascade per row (post-substitution) because rule matching
/// depends on the substituted values; everything else can use the
/// cascade-once-per-template cache in [`ForMarker::cascaded_body`].
fn body_has_dynamic_selector_attrs(body: &[Element]) -> bool {
    fn walk(el: &Element) -> bool {
        if el.attrs.id.as_deref().is_some_and(|id| id.contains('{')) {
            return true;
        }
        if el.attrs.classes.iter().any(|c| c.contains('{')) {
            return true;
        }
        el.children.iter().any(walk)
    }
    body.iter().any(walk)
}

/// Apply the CSS cascade to `el` and every descendant, without any
/// placeholder substitution. Used to build the cascade-once template
/// cache for virtualized `<for>` rows.
fn cascade_element_tree(el: &mut Element, sheet: &lumen_ir::css::Stylesheet) {
    lumen_ir::css::reapply_detached(el, sheet, &lumen_ir::css::MediaContext::default());
    for child in el.children.iter_mut() {
        cascade_element_tree(child, sheet);
    }
}

/// Substitute the placeholders in a template subtree against `scope`, then
/// re-run the cascade over the result when a stylesheet is given.
///
/// The cascade has to come after substitution for a template whose `id` or
/// `class` holds a placeholder: what a rule matches depends on the value
/// that landed there.
pub fn substitute_in_element_with_css(
    template: &Element,
    scope: &Scope<'_>,
    css: Option<&lumen_ir::css::Stylesheet>,
) -> Element {
    let mut instance = substitute_element(template, scope);
    if let Some(sheet) = css {
        cascade_element_tree(&mut instance, sheet);
    }
    instance
}

/// Emit a `tracing::warn!` for a missing row field, deduplicated per
/// `(parent_id, field)` pair. A 1000-row `<for>` referencing a typo'd
/// field should warn once, not 1000 times.
fn warn_missing_row_field_once(parent_id: Entity, field: &str) {
    use std::collections::HashSet;
    use std::sync::Mutex;
    static SEEN: std::sync::OnceLock<Mutex<HashSet<(u64, String)>>> = std::sync::OnceLock::new();
    let key = (parent_id.to_bits(), field.to_string());
    let seen = SEEN.get_or_init(|| Mutex::new(HashSet::new()));
    let mut guard = seen.lock().expect("warn-once mutex poisoned");
    if guard.insert(key) {
        tracing::warn!(
            target: "lumenc::spawn::row",
            "<for> row field `{field}` not present on iteration record - substituting empty string"
        );
    }
}

/// `spawn_element` analogue for the reconciler - must go through
/// `Commands` (deferred mutation) because the reconciler holds a query
/// borrow.
///
/// Implementation: queue a single world-closure that runs the real
/// [`spawn_element`] at command-apply time. The previous version was a
/// hand-mirrored copy of `spawn_element` that had drifted badly - it
/// never attached `TextInput`, `Toggleable` with its knob child,
/// `SliderValue` with its thumb child, `Scroll`/`ScrollOffset`,
/// `TabIndex`, `DropdownButton`/`DropdownOptionButton`/`MenuItemButton`,
/// `TabStripButton`, `TooltipSource`, `Validation`, `DocumentOrder`, ...
/// so every widget mounted inside an `<if>` / `<for>` / `<tab>` /
/// `<dialog>` body (tab panels compile to `<if eq>` gates, i.e. most of
/// a real app) spawned as a dead visual: toggles had no knob and no
/// state, sliders no thumb, inputs weren't focusable or editable,
/// dropdown headers didn't open on click, inner `<scroll>` containers
/// ignored the wheel, and Tab-cycle skipped the whole subtree (audit
/// root causes 5, 8, 9). Routing through `spawn_element` makes the two
/// paths structurally identical, forever. Commands apply in FIFO order,
/// so despawns queued before this in the same reconcile pass still land
/// first, and `parent` (spawned earlier in the queue, or pre-existing)
/// is alive by the time the closure runs.
fn spawn_body_child(
    commands: &mut bevy_ecs::system::Commands,
    el: &Element,
    parent: Entity,
    placeholders: Placeholders,
    kind: BodyChild,
) {
    let el = el.clone();
    commands.queue(move |world: &mut World| {
        let id = spawn_subtree(world, &el, Some(parent), placeholders);
        match kind {
            // A gated body carries the attributes the load-time cascade
            // resolved, against the color scheme and viewport the app
            // started with, so a page reached by navigation after
            // `set_color_scheme`, or a dialog opened after the OS flipped
            // to dark, would mount in the scheme the app booted with. The
            // restyle that runs before the frame resolves it against the
            // live ones.
            BodyChild::Gated => {
                world
                    .entity_mut(id)
                    .insert(lumen_core::components::StyleDirty);
            }
            BodyChild::Row => {}
            // A virtualized row sits in the slot its index gives it, which
            // the reconciler holds over whatever the row's styles say.
            BodyChild::VirtualRow(slot) => {
                let mut ent = world.entity_mut(id);
                ent.insert(VirtualRow);
                lumen_core::style_overrides::hold_on::<VirtualRow>(&mut ent, *slot);
            }
        }
        // Mount-direction transition (the CSS `@starting-style`
        // analogue): an element entering the tree with a
        // `transition: opacity ...` declaration starts fully transparent
        // and fades to its computed opacity. Gives fade-in dialogs /
        // menus / rows for free. Removal transitions (fade-out before
        // despawn) are intentionally NOT implemented - CSS itself can't
        // express them without JS, and holding despawns hostage to
        // animations would complicate every reconciler.
        let specs = world.get::<lumen_primitives::TransitionSpecs>(id).cloned();
        let cur = world.get::<Opacity>(id).copied();
        if let Some(bundle) = mount_fade_bundle(specs.as_ref(), cur) {
            world.entity_mut(id).insert(bundle);
        }
    });
}

/// What a body element [`spawn_body_child`] mounts is.
enum BodyChild {
    /// The body of an `<if>` that just opened.
    Gated,
    /// A `<for>` row, which its template's cascade already styled.
    Row,
    /// A virtualized `<for>` row, held in the slot given.
    VirtualRow(Box<StyleValues>),
}

/// Marker on a virtualized `<for>` row. The slot it sits in is held in
/// [`StyleOverrides`](lumen_core::style_overrides::StyleOverrides) over
/// the row's own styles.
#[derive(bevy_ecs::component::Component, Clone, Copy, Debug, Default)]
#[require(lumen_core::style_overrides::StyleOverrides)]
pub struct VirtualRow;

impl StyleOwner for VirtualRow {
    const RANK: u8 = 20;
}

/// Put a virtualized `<for>` block's mounted rows back in row-index
/// order. `row_order[slot]` is the current position of the row that
/// belongs at `slot`, and every row owns `body_len` consecutive
/// children. Queued as a command so this tick's row spawns and despawns
/// have landed by the time it reads the child list, and so the write
/// lands before [`renumber_document_order`] walks the hierarchy.
fn sort_virtual_rows(world: &mut World, parent: Entity, body_len: usize, row_order: &[usize]) {
    let Some(kids) = world
        .get::<bevy_ecs::hierarchy::Children>(parent)
        .map(|c| c.iter().collect::<Vec<Entity>>())
    else {
        return;
    };
    // Something else touched the child list, so the per-row slices no
    // longer line up. Leave it to the next reconcile, which rebuilds the
    // block on the same mismatch.
    if kids.len() != row_order.len() * body_len {
        return;
    }
    let mut ordered: Vec<Entity> = Vec::with_capacity(kids.len());
    for &row in row_order {
        ordered.extend_from_slice(&kids[row * body_len..(row + 1) * body_len]);
    }
    world.entity_mut(parent).insert_children(0, &ordered);
}

/// Build the `(Opacity(0), OpacityTransition(0 -> target))` pair for a
/// freshly-mounted / freshly-shown element that declares a
/// `transition: opacity ...`. `None` when there is no (non-zero-duration)
/// opacity spec or the target opacity is already 0.
fn mount_fade_bundle(
    specs: Option<&lumen_primitives::TransitionSpecs>,
    current: Option<Opacity>,
) -> Option<(Opacity, lumen_primitives::OpacityTransition)> {
    let spec = specs?.for_property(lumen_primitives::TransitionProperty::Opacity)?;
    if spec.duration.is_zero() {
        return None;
    }
    let target = current.map(|o| o.0).unwrap_or(1.0);
    if target <= 0.0 {
        return None;
    }
    Some((
        Opacity(0.0),
        lumen_primitives::OpacityTransition(lumen_primitives::Transition::new(
            0.0,
            target,
            spec.duration,
            spec.easing,
        )),
    ))
}

/// The UA-origin per-tag sizing defaults (D3 / task #29) live in
/// `skins/ua.css` now - an always-on stylesheet folded into the cascade
/// beneath any skin and beneath app CSS (see `crate::skins::UA` and
/// `run::loading::load_ir`), so a skinless app still gets a sizing
/// floor without a Rust-side table to keep in sync.
///
/// Four cases don't fit a plain CSS rule and stay here, running at spawn
/// and at every restyle after the cascade and inline attrs have been folded
/// into `attrs`:
///
/// - `<switch>` wants its UA `min-width` only when `width` is ALSO
///   unset (an explicit width already gives it a usable footprint).
///   CSS has no "set this property only if that other property is
///   unset" syntax, so this stays a Rust conditional instead of a
///   `ua.css` rule.
/// - A page host box fills the window. A multi-page app mounts each page
///   inside a synthetic gate keyed on the reserved active-page signal,
///   and that gate is the page's containing block: left at its content
///   size, a page whose shell asks for `height: 100%` resolves the
///   percentage against the shell itself and the bottom of the shell
///   lands past the bottom of the window. Pinning the gate to `<root>`'s
///   padding box gives every page the same full-window rect, which is
///   what Qt's `QStackedWidget` and Slint's page containers do; taking it
///   out of flow at the same time is what keeps the gates of the pages
///   that are NOT mounted - one empty sibling per page file - from
///   dividing the window between them. The gate is spelled `<if>`, and an
///   author's own `<if>` is an ordinary in-flow element, so the rule keys
///   on the signal rather than the tag and cannot be a `ua.css` selector.
/// - A `<dialog>` covers its parent: `position: absolute` with every
///   inset `0`, unless a rule or an attribute placed it. The rule would fit
///   in `ua.css`, but that sheet also reaches the web target's stylesheet,
///   where a modal dialog sits in the browser's top layer and has to stay
///   `position: fixed`.
/// - `<input>` / `<textarea>` default to `overflow: hidden` only when
///   neither the `overflow` shorthand nor `overflow-x` / `overflow-y`
///   was authored anywhere. `lumen_ir::css` never expands the `overflow`
///   shorthand into the longhands - they're independent properties to
///   the cascade, reconciled only afterward in `lumen_ir::convert` via
///   `.or()`, which doesn't know about origin. A plain `ua.css`
///   `overflow-x` rule would therefore out-rank an author's
///   shorthand-only `overflow: visible`, instead of losing to it as the
///   current behavior requires - so this checks the fully-resolved
///   `attrs` directly instead.
pub fn apply_ua_style_defaults(tag: &str, attrs: &Attributes, page_gate: bool, style: &mut Style) {
    if tag == "switch" && attrs.width.is_none() && attrs.min_width.is_none() {
        style.min_width = Length::Px(52.0);
    }
    if page_gate && attrs.position.is_none() {
        style.position = Position::Absolute;
        style.inset = Edges::default();
    }
    if tag == "dialog" {
        if attrs.position.is_none() {
            style.position = Position::Absolute;
        }
        if attrs.inset.is_none() {
            style.inset = Edges::default();
        }
    }
    if matches!(tag, "input" | "textarea") {
        // Long values scroll horizontally under the caret-keep-visible
        // offset (`TextInputScroll`) instead of painting past the field
        // box - clip like every real toolkit does. Author markup / CSS
        // overflow attrs still win.
        if attrs.overflow.is_none() && attrs.overflow_x.is_none() {
            style.overflow_x = Overflow::Hidden;
        }
        if attrs.overflow.is_none() && attrs.overflow_y.is_none() {
            style.overflow_y = Overflow::Hidden;
        }
    }
    if let Some(axis) = attrs.scroll {
        // A scroll container's automatic minimum size is zero (CSS
        // flexbox section 4.5): a `grow="1"` scroller in a fixed-height
        // column takes the space it is given and scrolls the rest,
        // instead of growing to its content and having nothing to scroll.
        // The layout engine keys that rule on `overflow`, which the
        // `scroll` attribute does not set, so it is set here: `scroll` on
        // the axes it scrolls and `hidden` on the other, as CSS computes
        // `visible` beside `scroll` and as the web target emits it.
        // Authored overflow attrs and `min-width` / `min-height` still win.
        let axis: ScrollAxis = axis.into();
        let overflow_for = |scrolls: bool| {
            if scrolls {
                Overflow::Scroll
            } else {
                Overflow::Hidden
            }
        };
        if attrs.overflow.is_none() && attrs.overflow_x.is_none() {
            style.overflow_x = overflow_for(axis.allows_x());
        }
        if attrs.overflow.is_none() && attrs.overflow_y.is_none() {
            style.overflow_y = overflow_for(axis.allows_y());
        }
    }
}

#[cfg(test)]
mod ua_style_tests {
    use super::*;
    use lumen_ir::layout_ir::{OverflowSpec, ScrollAxisSpec};

    fn ua_style(attrs: &Attributes) -> Style {
        let mut style = Style::from(attrs);
        apply_ua_style_defaults("scroll", attrs, false, &mut style);
        style
    }

    #[test]
    fn a_scroller_scrolls_its_axes_and_clips_the_other() {
        let y = ua_style(&Attributes {
            scroll: Some(ScrollAxisSpec::Y),
            ..Attributes::default()
        });
        assert_eq!(
            (y.overflow_x, y.overflow_y),
            (Overflow::Hidden, Overflow::Scroll)
        );
        let x = ua_style(&Attributes {
            scroll: Some(ScrollAxisSpec::X),
            ..Attributes::default()
        });
        assert_eq!(
            (x.overflow_x, x.overflow_y),
            (Overflow::Scroll, Overflow::Hidden)
        );
        let both = ua_style(&Attributes {
            scroll: Some(ScrollAxisSpec::Both),
            ..Attributes::default()
        });
        assert_eq!(
            (both.overflow_x, both.overflow_y),
            (Overflow::Scroll, Overflow::Scroll)
        );
    }

    #[test]
    fn an_authored_overflow_wins_over_the_scroller_default() {
        let s = ua_style(&Attributes {
            scroll: Some(ScrollAxisSpec::Both),
            overflow: Some(OverflowSpec::Hidden),
            ..Attributes::default()
        });
        assert_eq!(
            (s.overflow_x, s.overflow_y),
            (Overflow::Hidden, Overflow::Hidden)
        );
        let s = ua_style(&Attributes {
            scroll: Some(ScrollAxisSpec::Y),
            overflow_y: Some(OverflowSpec::Visible),
            ..Attributes::default()
        });
        assert_eq!(s.overflow_y, Overflow::Visible);
    }
}

/// Absolute-position [`Style`] seed for the toggle knob / slider thumb
/// child. `size` is the initial square side; `inset_px` is the top/left
/// offset (right / bottom stay `NaN` = auto so taffy doesn't
/// over-constrain against the explicit size). The runtime sync systems
/// refine size + inset once the track's laid-out rect is known.
fn knob_style(size: f32, inset_px: f32) -> Style {
    Style {
        position: lumen_core::components::Position::Absolute,
        width: Length::Px(size),
        height: Length::Px(size),
        inset: lumen_core::components::Edges {
            left: inset_px,
            top: inset_px,
            right: f32::NAN,
            bottom: f32::NAN,
            ..Default::default()
        },
        ..Default::default()
    }
}

#[cfg(test)]
mod body_spawn_tests {
    //! The reconciler spawn path must produce the same widget behavior
    //! as the initial `spawn_element` walk. It used to be a drifted
    //! hand-mirror that skipped `TextInput`, `Toggleable` + knob,
    //! `SliderValue` + thumb, `Scroll`, `TabIndex`, `DropdownButton`,
    //! `DocumentOrder`, ... - so every widget inside an `<if>` / `<for>`
    //! / `<tab>` body spawned inert (audit RC5 / RC8 / RC9).
    use super::*;
    use bevy_ecs::system::RunSystemOnce;

    fn el(tag: &str) -> Element {
        Element {
            tag: tag.to_string(),
            ..Element::default()
        }
    }

    #[test]
    fn if_body_children_spawn_with_full_widget_behavior() {
        let mut world = World::new();
        world.insert_resource(PropertyStore::default());
        world
            .resource_mut::<PropertyStore>()
            .set_global_str("open", "1");

        let mut toggle = el("toggle");
        toggle.attrs.tab_index = Some(0);
        let mut slider = el("slider");
        slider.attrs.tab_index = Some(0);
        let mut input = el("input");
        input.attrs.tab_index = Some(0);
        let mut scroll = el("scroll");
        scroll.attrs.scroll = Some(lumen_ir::layout_ir::ScrollAxisSpec::Y);
        let mut header = el("button");
        header.attrs.dropdown_button = Some(lumen_ir::layout_ir::DropdownButtonSpec {
            open_signal: "__dropdown_open:x".to_string(),
            value_signal: "x".to_string(),
            options: vec![("a".to_string(), "A".to_string(), false)],
        });

        world.spawn(IfMarker {
            signal_name: "open".to_string(),
            body: vec![toggle, slider, input, scroll, header],
            currently_mounted: false,
            mode: IfMode::Hide,
            eq: None,
            applied_visible: None,
        });
        world.run_system_once(reconcile_if_blocks).unwrap();

        // <toggle> mounts stateful + with its knob child.
        let toggle_e = world
            .query::<(Entity, &Toggleable)>()
            .iter(&world)
            .next()
            .expect("toggle in an if-body must carry Toggleable")
            .0;
        let knob_parent = world
            .query_filtered::<&ChildOf, With<lumen_primitives::ToggleKnob>>()
            .iter(&world)
            .next()
            .expect("toggle in an if-body must spawn its knob child")
            .parent();
        assert_eq!(knob_parent, toggle_e, "knob is the toggle's child");

        // <slider> mounts stateful + with its thumb child.
        let slider_e = world
            .query::<(Entity, &SliderValue)>()
            .iter(&world)
            .next()
            .expect("slider in an if-body must carry SliderValue")
            .0;
        let thumb_parent = world
            .query_filtered::<&ChildOf, With<lumen_primitives::SliderThumb>>()
            .iter(&world)
            .next()
            .expect("slider in an if-body must spawn its thumb child")
            .parent();
        assert_eq!(thumb_parent, slider_e, "thumb is the slider's child");

        // <input> is editable/focusable; <scroll> receives the wheel;
        // the dropdown header opens on click.
        assert_eq!(
            world.query::<&TextInput>().iter(&world).count(),
            1,
            "input in an if-body must carry TextInput"
        );
        assert_eq!(
            world
                .query::<(&Scroll, &ScrollOffset)>()
                .iter(&world)
                .count(),
            1,
            "scroll in an if-body must carry Scroll + ScrollOffset"
        );
        assert_eq!(
            world
                .query::<&lumen_primitives::DropdownButton>()
                .iter(&world)
                .count(),
            1,
            "dropdown header in an if-body must carry DropdownButton"
        );
        // Unstyled controls still get UA fallback visuals: without a
        // `Visuals` component they paint nothing at all, so a skinless
        // app shows no groove and no field chrome.
        for (label, e) in [("slider", slider_e), ("toggle", toggle_e)] {
            assert!(
                world.get::<Visuals>(e).is_some(),
                "unstyled {label} must carry UA fallback Visuals"
            );
        }
        let input_e = world
            .query_filtered::<Entity, With<TextInput>>()
            .iter(&world)
            .next()
            .unwrap();
        assert!(
            world.get::<Visuals>(input_e).is_some(),
            "unstyled input must carry UA fallback Visuals"
        );

        // Tab cycle: focusables carry TabIndex + DocumentOrder.
        assert_eq!(
            world
                .query::<(&TabIndex, &lumen_core::components::DocumentOrder)>()
                .iter(&world)
                .count(),
            3,
            "if-body focusables must carry TabIndex + DocumentOrder"
        );
    }
}

#[cfg(test)]
mod document_order_tests {
    //! `DocumentOrder` is a position, not a spawn timestamp. A subtree
    //! that mounts after the initial walk - an `<if>` body, a `<for>`
    //! row - takes the counter values that were left over, which puts it
    //! behind every element already in the world. Tab then skipped a
    //! gated button into the list beside it, and the longer the list,
    //! the further the jump.
    use super::*;
    use bevy_ecs::system::RunSystemOnce;

    fn el(tag: &str) -> Element {
        Element {
            tag: tag.to_string(),
            ..Element::default()
        }
    }

    fn order_of(world: &World, e: Entity) -> u32 {
        world
            .get::<lumen_core::components::DocumentOrder>(e)
            .expect("every spawned element carries DocumentOrder")
            .0
    }

    /// `<root>` = head button, `<if>` holding one button, a long list,
    /// tail button. The gated button mounts last and must still sort
    /// between the head and the list.
    fn tree_with_a_gate(rows: usize) -> (World, Entity, Entity, Entity, Entity) {
        let mut world = World::new();
        world.insert_resource(PropertyStore::default());
        world
            .resource_mut::<PropertyStore>()
            .set_global_str("open", "1");

        let mut gate = el("if");
        gate.attrs.if_signal = Some("open".to_string());
        gate.children = vec![el("button")];
        let mut list = el("column");
        list.children = (0..rows).map(|_| el("button")).collect();
        let mut root = el("root");
        root.children = vec![el("button"), gate, list, el("button")];

        let root_e = spawn_subtree(&mut world, &root, None, Placeholders::Unresolved);
        let kids: Vec<Entity> = world
            .get::<bevy_ecs::hierarchy::Children>(root_e)
            .map(|c| c.iter().collect())
            .expect("root has children");
        let (head, gate_e, list_e, tail) = (kids[0], kids[1], kids[2], kids[3]);

        world.run_system_once(reconcile_if_blocks).unwrap();
        let gated = world
            .get::<bevy_ecs::hierarchy::Children>(gate_e)
            .and_then(|c| c.iter().next())
            .expect("the if body mounted");
        let first_row = world
            .get::<bevy_ecs::hierarchy::Children>(list_e)
            .and_then(|c| c.iter().next())
            .expect("the list has rows");
        world.run_system_once(renumber_document_order).unwrap();
        (world, head, gated, first_row, tail)
    }

    #[test]
    fn a_mounted_if_body_sorts_where_it_sits_not_where_it_landed() {
        let (world, head, gated, first_row, tail) = tree_with_a_gate(500);
        assert!(
            order_of(&world, head) < order_of(&world, gated),
            "the gated button follows the head button"
        );
        assert!(
            order_of(&world, gated) < order_of(&world, first_row),
            "the gated button precedes the list beside it"
        );
        assert!(
            order_of(&world, first_row) < order_of(&world, tail),
            "the list precedes the tail button"
        );
    }

    /// The same tree with an almost-empty list. The defect used to hide
    /// here, because being a couple of stops out of place still looks
    /// right; the ordering must not depend on the list's size at all.
    #[test]
    fn list_size_does_not_change_the_order() {
        let (world, head, gated, first_row, tail) = tree_with_a_gate(1);
        assert!(order_of(&world, head) < order_of(&world, gated));
        assert!(order_of(&world, gated) < order_of(&world, first_row));
        assert!(order_of(&world, first_row) < order_of(&world, tail));
    }

    /// The walk is a fixed point: running it over a tree that did not
    /// move leaves every number where it was.
    #[test]
    fn a_settled_tree_is_left_alone() {
        let (mut world, _, gated, _, _) = tree_with_a_gate(4);
        let before = order_of(&world, gated);
        world.clear_trackers();
        world.run_system_once(renumber_document_order).unwrap();
        assert_eq!(order_of(&world, gated), before);
    }
}

#[cfg(test)]
mod escape_tests {
    //! `close_dialogs_on_escape` - one Esc peels off the top-most open
    //! popup layer (dropdown -> menu -> dialog). Driven directly via
    //! `run_system_once` against a bare `World`.
    use super::*;
    use bevy_ecs::message::Messages;
    use bevy_ecs::system::RunSystemOnce;
    use lumen_core::input::{Key, KeyPressed, Modifiers, NamedKey};

    fn if_marker(signal: &str) -> IfMarker {
        IfMarker {
            signal_name: signal.to_string(),
            body: Vec::new(),
            currently_mounted: true,
            mode: IfMode::Hide,
            eq: None,
            applied_visible: None,
        }
    }

    fn press_escape(world: &mut World) {
        world
            .resource_mut::<Messages<KeyPressed>>()
            .write(KeyPressed {
                key: Key::Named(NamedKey::Escape),
                modifiers: Modifiers::default(),
                repeat: false,
            });
    }

    fn run(world: &mut World) {
        world.run_system_once(close_dialogs_on_escape).unwrap();
        world.resource_mut::<Messages<KeyPressed>>().clear();
    }

    #[test]
    fn escape_closes_dropdown_before_dialog() {
        let mut world = World::new();
        world.init_resource::<Messages<KeyPressed>>();
        world.insert_resource(PropertyStore::default());

        // Dropdown open on top of an open dialog.
        world
            .resource_mut::<PropertyStore>()
            .set_global_bool("__dropdown_open:fruit", true);
        world.spawn(if_marker("__dropdown_open:fruit"));
        world
            .resource_mut::<PropertyStore>()
            .set_global_str("show_dialog", "1");
        world.spawn((if_marker("show_dialog"), DialogMarker));

        // First Esc: only the dropdown collapses.
        press_escape(&mut world);
        run(&mut world);
        let store = world.resource::<PropertyStore>();
        assert_eq!(
            store.get_global_bool("__dropdown_open:fruit"),
            Some(false),
            "dropdown closed first"
        );
        assert_eq!(
            store.get_global_str("show_dialog").as_deref(),
            Some("1"),
            "dialog still open after one press"
        );

        // Second Esc: now the dialog closes.
        press_escape(&mut world);
        run(&mut world);
        assert_eq!(
            world
                .resource::<PropertyStore>()
                .get_global_str("show_dialog")
                .as_deref(),
            Some(""),
            "dialog closes on the second press"
        );
    }

    #[test]
    fn escape_closes_menu_before_dialog() {
        let mut world = World::new();
        world.init_resource::<Messages<KeyPressed>>();
        world.insert_resource(PropertyStore::default());

        world
            .resource_mut::<PropertyStore>()
            .set_global_bool("__menu_open:file", true);
        world.spawn(if_marker("__menu_open:file"));
        world
            .resource_mut::<PropertyStore>()
            .set_global_str("show_dialog", "1");
        world.spawn((if_marker("show_dialog"), DialogMarker));

        press_escape(&mut world);
        run(&mut world);
        let store = world.resource::<PropertyStore>();
        assert_eq!(store.get_global_bool("__menu_open:file"), Some(false));
        assert_eq!(store.get_global_str("show_dialog").as_deref(), Some("1"));
    }

    /// Wave 3: an Escape that cancelled an in-flight press
    /// (`lumen_input::cancel_press_on_escape` set the consumed flag
    /// earlier in the Input stage) must not also close the dialog.
    #[test]
    fn escape_consumed_by_press_cancel_leaves_dialog_open() {
        let mut world = World::new();
        world.init_resource::<Messages<KeyPressed>>();
        world.insert_resource(PropertyStore::default());
        world
            .resource_mut::<PropertyStore>()
            .set_global_str("show_dialog", "1");
        world.spawn((if_marker("show_dialog"), DialogMarker));

        // Press-cancel consumed this Escape.
        world.insert_resource(lumen_core::input::EscapePressCancel(true));
        press_escape(&mut world);
        run(&mut world);
        assert_eq!(
            world
                .resource::<PropertyStore>()
                .get_global_str("show_dialog")
                .as_deref(),
            Some("1"),
            "dialog stays open when the Escape cancelled a press"
        );

        // Next Escape (no press in flight) closes as usual.
        world.insert_resource(lumen_core::input::EscapePressCancel(false));
        press_escape(&mut world);
        run(&mut world);
        assert_eq!(
            world
                .resource::<PropertyStore>()
                .get_global_str("show_dialog")
                .as_deref(),
            Some(""),
            "un-consumed Escape still closes the dialog"
        );
    }
}

/// W5 dialog contract - initial focus, focus restore, default-button
/// Enter, and the exactly-once accepted/rejected close event. Driven
/// via `run_system_once` against a bare `World` (same style as
/// `escape_tests`).
#[cfg(test)]
mod dialog_contract_tests {
    use super::*;
    use bevy_ecs::message::Messages;
    use bevy_ecs::system::RunSystemOnce;
    use lumen_core::components::{DocumentOrder, LumenId, LumenTag, TabIndex, Visible};
    use lumen_core::input::{
        ClickEvent, DialogClosed, FocusTracker, Focused, Key, KeyPressed, Modifiers, NamedKey,
        PointerButton,
    };

    fn if_marker(signal: &str) -> IfMarker {
        IfMarker {
            signal_name: signal.to_string(),
            body: Vec::new(),
            currently_mounted: true,
            mode: IfMode::Hide,
            eq: None,
            applied_visible: None,
        }
    }

    /// Dialog with a body: an input (autofocus optional), and two
    /// buttons (Cancel, Confirm-with-default-marker).
    struct Fixture {
        dialog: Entity,
        input: Entity,
        cancel: Entity,
        confirm: Entity,
        opener: Entity,
    }

    fn build(world: &mut World, autofocus_input: bool) -> Fixture {
        world.init_resource::<Messages<DialogClosed>>();
        world.init_resource::<Messages<KeyPressed>>();
        world.init_resource::<Messages<ClickEvent>>();
        world.insert_resource(FocusTracker(None));
        let opener = world
            .spawn((LumenTag("button".into()), TabIndex(0), DocumentOrder(0)))
            .id();
        let dialog = world
            .spawn((DialogMarker, if_marker("dlg_open"), Visible(false)))
            .id();
        let mut input = world.spawn((
            LumenTag("input".into()),
            TabIndex(0),
            DocumentOrder(10),
            ChildOf(dialog),
        ));
        if autofocus_input {
            input.insert(AutoFocus);
        }
        let input = input.id();
        let cancel = world
            .spawn((
                LumenTag("button".into()),
                TabIndex(0),
                DocumentOrder(11),
                ChildOf(dialog),
            ))
            .id();
        let confirm = world
            .spawn((
                LumenTag("button".into()),
                TabIndex(0),
                DocumentOrder(12),
                DefaultButton,
                ChildOf(dialog),
            ))
            .id();
        Fixture {
            dialog,
            input,
            cancel,
            confirm,
            opener,
        }
    }

    fn run_lifecycle(world: &mut World) {
        world.run_system_once(manage_dialog_lifecycle).unwrap();
    }

    fn set_open(world: &mut World, dialog: Entity, open: bool) {
        world.entity_mut(dialog).insert(Visible(open));
    }

    fn drain_closed(world: &mut World) -> Vec<DialogClosed> {
        world
            .resource_mut::<Messages<DialogClosed>>()
            .drain()
            .collect()
    }

    #[test]
    fn open_focuses_autofocus_descendant() {
        let mut world = World::new();
        let fx = build(&mut world, true);
        world.insert_resource(FocusTracker(Some(fx.opener)));
        run_lifecycle(&mut world); // seed session (closed)
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world); // open edge + focus pass
        assert_eq!(world.resource::<FocusTracker>().0, Some(fx.input));
        assert!(world.get::<Focused>(fx.input).is_some());
    }

    #[test]
    fn open_without_autofocus_focuses_first_focusable_descendant() {
        let mut world = World::new();
        let fx = build(&mut world, false);
        world.insert_resource(FocusTracker(Some(fx.opener)));
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world);
        assert_eq!(
            world.resource::<FocusTracker>().0,
            Some(fx.input),
            "input has the lowest DocumentOrder among focusables"
        );
    }

    #[test]
    fn close_restores_previous_focus_and_fires_rejected_once() {
        let mut world = World::new();
        let fx = build(&mut world, true);
        world.insert_resource(FocusTracker(Some(fx.opener)));
        world.entity_mut(fx.opener).insert(Focused);
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world);
        assert_eq!(world.resource::<FocusTracker>().0, Some(fx.input));
        // Close (e.g. Escape wrote the signal; Visible flipped).
        set_open(&mut world, fx.dialog, false);
        run_lifecycle(&mut world);
        assert_eq!(
            world.resource::<FocusTracker>().0,
            Some(fx.opener),
            "focus returns to the pre-open holder"
        );
        let closed = drain_closed(&mut world);
        assert_eq!(closed.len(), 1, "exactly one close event");
        assert!(!closed[0].accepted, "non-default close is rejected");
        // Further idle ticks: no repeats.
        run_lifecycle(&mut world);
        run_lifecycle(&mut world);
        assert!(drain_closed(&mut world).is_empty(), "never fires twice");
    }

    #[test]
    fn default_button_click_resolves_close_as_accepted_exactly_once() {
        let mut world = World::new();
        let fx = build(&mut world, true);
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world);
        // Pointer click lands on the confirm button's TEXT CHILD
        // (hit-shadowing) - the accept marker must still resolve.
        let text_child = world.spawn(ChildOf(fx.confirm)).id();
        world
            .resource_mut::<Messages<ClickEvent>>()
            .write(ClickEvent {
                entity: text_child,
                position: glam::Vec2::ZERO,
                button: PointerButton::Primary,
                local: None,
            });
        world
            .run_system_once(mark_dialog_accept_on_default_click)
            .unwrap();
        set_open(&mut world, fx.dialog, false);
        run_lifecycle(&mut world);
        let closed = drain_closed(&mut world);
        assert_eq!(closed.len(), 1);
        assert!(closed[0].accepted, "default-button close is accepted");
        assert_eq!(closed[0].id, "dlg_open", "falls back to the open signal");
        // Re-open + Escape-close: verdict resets to rejected.
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, false);
        run_lifecycle(&mut world);
        let closed = drain_closed(&mut world);
        assert_eq!(closed.len(), 1);
        assert!(
            !closed[0].accepted,
            "pending accept never leaks into the next cycle"
        );
    }

    #[test]
    fn dialog_id_attribute_wins_over_signal_name() {
        let mut world = World::new();
        let fx = build(&mut world, true);
        world
            .entity_mut(fx.dialog)
            .insert(LumenId("demo-dialog".into()));
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, false);
        run_lifecycle(&mut world);
        let closed = drain_closed(&mut world);
        assert_eq!(closed[0].id, "demo-dialog");
    }

    fn press_enter(world: &mut World) {
        world
            .resource_mut::<Messages<KeyPressed>>()
            .write(KeyPressed {
                key: Key::Named(NamedKey::Enter),
                modifiers: Modifiers::default(),
                repeat: false,
            });
    }

    fn run_enter(world: &mut World) {
        world
            .run_system_once(activate_dialog_default_on_enter)
            .unwrap();
        world.resource_mut::<Messages<KeyPressed>>().clear();
    }

    fn synthesized_clicks(world: &mut World) -> Vec<Entity> {
        world
            .resource_mut::<Messages<ClickEvent>>()
            .drain()
            .map(|c| c.entity)
            .collect()
    }

    #[test]
    fn enter_on_non_button_focus_activates_default() {
        let mut world = World::new();
        let fx = build(&mut world, true);
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world); // focus lands on the input
        press_enter(&mut world);
        run_enter(&mut world);
        assert_eq!(
            synthesized_clicks(&mut world),
            vec![fx.confirm],
            "Enter with focus on the (single-line) input clicks the default button"
        );
        assert!(
            world
                .get::<DialogSession>(fx.dialog)
                .unwrap()
                .pending_accept,
            "Enter-default marks the accept path"
        );
    }

    #[test]
    fn enter_on_focused_button_does_not_double_activate() {
        let mut world = World::new();
        let fx = build(&mut world, false);
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world);
        // Focus the CANCEL button: Enter must go to it (via the normal
        // activate_focused_on_enter path), not the default button.
        world.insert_resource(FocusTracker(Some(fx.cancel)));
        press_enter(&mut world);
        run_enter(&mut world);
        assert!(
            synthesized_clicks(&mut world).is_empty(),
            "focused button consumes Enter itself"
        );
    }

    #[test]
    fn enter_ignores_closed_dialogs() {
        let mut world = World::new();
        let fx = build(&mut world, false);
        run_lifecycle(&mut world);
        world.insert_resource(FocusTracker(None));
        press_enter(&mut world);
        run_enter(&mut world);
        assert!(synthesized_clicks(&mut world).is_empty());
        let _ = fx;
    }

    #[test]
    fn enter_falls_back_to_first_enabled_button_without_default_marker() {
        let mut world = World::new();
        let fx = build(&mut world, false);
        world.entity_mut(fx.confirm).remove::<DefaultButton>();
        run_lifecycle(&mut world);
        set_open(&mut world, fx.dialog, true);
        run_lifecycle(&mut world);
        world.insert_resource(FocusTracker(Some(fx.input)));
        press_enter(&mut world);
        run_enter(&mut world);
        assert_eq!(
            synthesized_clicks(&mut world),
            vec![fx.cancel],
            "Qt autoDefault: first enabled button in markup order"
        );
    }
}

#[cfg(test)]
mod css_spawn_wiring_tests {
    //! Phase 2 (skin-tokens): CSS-authored values resolved into
    //! `Attributes` must reach the runtime at SPAWN, not only via a live
    //! restyle - a value that only shows up after a theme flip and not on
    //! first launch is exactly the bug these tests pin.
    use super::*;

    fn el(tag: &str) -> Element {
        Element {
            tag: tag.to_string(),
            ..Element::default()
        }
    }

    #[test]
    fn input_gets_caret_width_and_password_character_from_css() {
        let mut world = World::new();
        let mut input = el("input");
        input.attrs.caret_width = Some(3.5);
        input.attrs.password_character = Some('#');
        let e = spawn_subtree(&mut world, &input, None, Placeholders::Unresolved);

        assert_eq!(
            world.get::<lumen_core::components::CaretWidth>(e),
            Some(&lumen_core::components::CaretWidth(3.5))
        );
        assert_eq!(
            world.get::<lumen_core::components::PasswordCharacter>(e),
            Some(&lumen_core::components::PasswordCharacter('#'))
        );
    }

    /// An unauthored `<input>` still carries both components, holding the
    /// `Default` fallback - inserted unconditionally, the same contract
    /// pattern as `KnobGeometry` / `PopupGap`, not left absent.
    #[test]
    fn input_gets_default_caret_width_and_password_character_when_unauthored() {
        let mut world = World::new();
        let e = spawn_subtree(&mut world, &el("input"), None, Placeholders::Unresolved);

        assert_eq!(
            world.get::<lumen_core::components::CaretWidth>(e),
            Some(&lumen_core::components::CaretWidth::default())
        );
        assert_eq!(
            world.get::<lumen_core::components::PasswordCharacter>(e),
            Some(&lumen_core::components::PasswordCharacter::default())
        );
    }

    /// An `<a href>` is interactive, so it takes the pointer whether or
    /// not it paints: hit-testing keys on the layout rect plus
    /// interactivity. `-1` keeps links out of the Tab chain, matching
    /// HTML's "focusable by pointer, not tabbable".
    #[test]
    fn anchor_is_a_pointer_target_without_a_background() {
        let mut world = World::new();
        let mut a = el("a");
        a.attrs.href = Some("about".to_string());
        let e = spawn_subtree(&mut world, &a, None, Placeholders::Unresolved);

        assert!(
            world.get::<Visuals>(e).is_none(),
            "an unstyled anchor paints nothing"
        );
        assert_eq!(
            world.get::<TabIndex>(e).map(|t| t.0),
            Some(-1),
            "an anchor is a pointer target but not a Tab stop"
        );
    }

    /// An authored `tab-index` on a link wins - that is how an author
    /// puts one in the Tab chain.
    #[test]
    fn authored_tab_index_on_an_anchor_wins() {
        let mut world = World::new();
        let mut a = el("a");
        a.attrs.href = Some("about".to_string());
        a.attrs.tab_index = Some(0);
        let e = spawn_subtree(&mut world, &a, None, Placeholders::Unresolved);

        assert_eq!(world.get::<TabIndex>(e).map(|t| t.0), Some(0));
    }

    /// A non-text-input element must not gain either component at all -
    /// they are only meaningful on `<input>` / `<textarea>`.
    #[test]
    fn non_input_does_not_get_caret_width_or_password_character() {
        let mut world = World::new();
        let e = spawn_subtree(&mut world, &el("column"), None, Placeholders::Unresolved);

        assert!(world.get::<lumen_core::components::CaretWidth>(e).is_none());
        assert!(
            world
                .get::<lumen_core::components::PasswordCharacter>(e)
                .is_none()
        );
    }

    /// `<textarea>` gets the same wiring as `<input>` - both share the
    /// gate.
    #[test]
    fn textarea_gets_caret_width_from_css() {
        let mut world = World::new();
        let mut textarea = el("textarea");
        textarea.attrs.caret_width = Some(4.0);
        let e = spawn_subtree(&mut world, &textarea, None, Placeholders::Unresolved);

        assert_eq!(
            world.get::<lumen_core::components::CaretWidth>(e),
            Some(&lumen_core::components::CaretWidth(4.0))
        );
    }

    /// `line-height` alone (see `lumen_ir::convert`'s
    /// `line_height_alone_produces_a_text_style` for the same case at the
    /// conversion layer) reaches the spawned `TextStyle`.
    #[test]
    fn text_style_carries_authored_line_height_at_spawn() {
        let mut world = World::new();
        let mut label = el("label");
        label.attrs.line_height = Some(lumen_ir::layout_ir::LineHeightSpec::Multiplier(1.6));
        let e = spawn_subtree(&mut world, &label, None, Placeholders::Unresolved);

        let ts = world
            .get::<TextStyle>(e)
            .expect("line-height alone must still spawn a TextStyle");
        assert_eq!(
            ts.line_height,
            Some(lumen_core::components::LineHeightSpec::Multiplier(1.6))
        );
    }

    /// Every new `scrollbar-*` field spawn was silently dropping (only
    /// `thumb` / `track` / `width` reached `ScrollbarStyle`) now converts
    /// and lands, including the ms -> s duration conversion for the fade
    /// timings.
    #[test]
    fn scrollbar_style_carries_the_new_css_fields_at_spawn() {
        let mut world = World::new();
        let mut column = el("column");
        column.attrs.scrollbar_thickness = Some(10.0);
        column.attrs.scrollbar_thickness_thin = Some(5.0);
        column.attrs.scrollbar_margin = Some(3.0);
        column.attrs.scrollbar_min_thumb = Some(24.0);
        column.attrs.scrollbar_hover_boost = Some(2.5);
        column.attrs.scrollbar_fade_delay_ms = Some(2000);
        column.attrs.scrollbar_fade_duration_ms = Some(500);
        let e = spawn_subtree(&mut world, &column, None, Placeholders::Unresolved);

        let sb = world
            .get::<lumen_core::input::ScrollbarStyle>(e)
            .expect("authored scrollbar-* properties must spawn a ScrollbarStyle");
        assert_eq!(sb.thickness, 10.0);
        assert_eq!(sb.thickness_thin, 5.0);
        assert_eq!(sb.margin, 3.0);
        assert_eq!(sb.min_thumb, 24.0);
        assert_eq!(sb.hover_boost, 2.5);
        assert_eq!(sb.fade_delay_secs, 2.0, "2000ms -> 2.0s");
        assert_eq!(sb.fade_secs, 0.5, "500ms -> 0.5s");
    }

    /// A field from this batch authored ALONE - nothing else
    /// scrollbar-related - must still spawn `ScrollbarStyle`. The guard
    /// used to check only `scrollbar_color` / `scrollbar_width`, so e.g.
    /// `scrollbar-thickness` on its own never got a component at all -
    /// the same silent-drop shape as the `TextStyle` guard bug.
    #[test]
    fn scrollbar_thickness_alone_spawns_scrollbar_style() {
        let mut world = World::new();
        let mut column = el("column");
        column.attrs.scrollbar_thickness = Some(12.0);
        let e = spawn_subtree(&mut world, &column, None, Placeholders::Unresolved);

        assert!(
            world.get::<lumen_core::input::ScrollbarStyle>(e).is_some(),
            "scrollbar-thickness alone must spawn ScrollbarStyle"
        );
    }

    /// A plain element with no scrollbar properties at all must not gain
    /// a `ScrollbarStyle` - the "harmless on non-scroll entities" claim
    /// in the spawn comment depends on absence, not a zeroed component.
    #[test]
    fn no_scrollbar_properties_spawns_no_scrollbar_style() {
        let mut world = World::new();
        let e = spawn_subtree(&mut world, &el("column"), None, Placeholders::Unresolved);

        assert!(world.get::<lumen_core::input::ScrollbarStyle>(e).is_none());
    }

    /// A world whose globals hold `name`, which is the state a page arrives
    /// with in a browser: the seed is applied before the tree is built.
    fn world_holding(pairs: &[(&str, &str)]) -> World {
        let mut world = World::new();
        let mut store = PropertyStore::default();
        for (name, value) in pairs {
            store.set_global_str(name, *value);
        }
        world.insert_resource(store);
        world
    }

    #[test]
    fn a_placeholder_naming_a_global_is_resolved_when_the_element_is_built() {
        let mut world = world_holding(&[("name", "Ada")]);
        let mut label = el("label");
        label.attrs.text = Some("hello {name}".to_string());
        label.attrs.classes = vec!["tier-{name}".to_string()];
        let e = spawn_subtree(&mut world, &label, None, Placeholders::Unresolved);

        assert_eq!(
            world.get::<TextContent>(e).map(|text| text.0.as_str()),
            Some("hello Ada"),
            "the web emitter writes the same string into the page"
        );
        let classes = world
            .get::<lumen_core::components::LumenClasses>(e)
            .expect("a class list");
        assert!(
            classes.0.iter().any(|class| &**class == "tier-Ada"),
            "{:?}",
            classes.0
        );
    }

    #[test]
    fn a_placeholder_no_global_answers_stays_in_the_text() {
        let mut world = world_holding(&[]);
        let mut label = el("label");
        label.attrs.text = Some("hello {name}".to_string());
        let e = spawn_subtree(&mut world, &label, None, Placeholders::Unresolved);

        assert_eq!(
            world.get::<TextContent>(e).map(|text| text.0.as_str()),
            Some("hello {name}")
        );
    }

    #[test]
    fn a_tree_a_row_already_walked_is_not_walked_again() {
        let mut world = world_holding(&[("name", "Ada")]);
        let mut label = el("label");
        // What a row field held, written in by the row walk. It is text, and
        // reading it as a placeholder would put the global in its place.
        label.attrs.text = Some("{name}".to_string());
        let e = spawn_subtree(&mut world, &label, None, Placeholders::Resolved);

        assert_eq!(
            world.get::<TextContent>(e).map(|text| text.0.as_str()),
            Some("{name}")
        );
    }
}

#[cfg(test)]
mod virtualized_for_tests {
    //! A virtualized `<for>` remembers each mounted row by its index into
    //! the array it was built from. When the array shrinks under the
    //! window (a search filter), those indices can point past its end.
    use super::*;
    use bevy_ecs::system::RunSystemOnce;
    use lumen_core::signals::{ArrayItem, ArraySignals};

    fn rows(ids: &[usize]) -> Vec<ArrayItem> {
        ids.iter()
            .map(|i| {
                let mut m = ArrayItem::default();
                m.insert("id".to_string(), i.to_string());
                m.insert("label".to_string(), format!("row {i}"));
                m
            })
            .collect()
    }

    #[test]
    fn a_filter_that_shrinks_the_array_under_the_window_keeps_the_surviving_row() {
        let mut world = World::new();
        let mut arrays = ArraySignals::default();
        arrays.set("rows", rows(&[0, 1, 2]));
        world.insert_resource(arrays);
        world.insert_resource(PropertyStore::default());

        let mut label = Element {
            tag: "label".to_string(),
            ..Element::default()
        };
        label.attrs.text = Some("{label}".to_string());
        let block = world
            .spawn((
                lumen_core::components::Style::default(),
                ForMarker {
                    array_name: "rows".into(),
                    body: vec![label],
                    key_field: Some("id".to_string()),
                    cached_keys: Vec::new(),
                    virtualized: true,
                    row_height: 20.0,
                    win_rows: Vec::new(),
                    cascaded_body: None,
                    row_items: Vec::new(),
                },
            ))
            .id();
        world.run_system_once(reconcile_for_blocks).unwrap();
        assert_eq!(world.get::<ForMarker>(block).unwrap().win_rows.len(), 3);

        // The filter keeps only the last row: it moves to index 0, and the
        // rows mounted at indices 1 and 2 have no record left.
        world.resource_mut::<ArraySignals>().set("rows", rows(&[2]));
        world.run_system_once(reconcile_for_blocks).unwrap();

        assert_eq!(
            world.get::<ForMarker>(block).unwrap().win_rows,
            vec![(0, "2".to_string())]
        );
        let kids: Vec<Entity> = world
            .get::<bevy_ecs::hierarchy::Children>(block)
            .map(|c| c.iter().collect())
            .unwrap_or_default();
        assert_eq!(kids.len(), 1);
        assert_eq!(
            world.get::<TextContent>(kids[0]).map(|t| t.0.as_str()),
            Some("row 2")
        );
    }
}