frus_widgets/

ui.rs

//! The driver: walks the tree carrying a context (translation + clip), produces the
//! [`Scene`] and the hit-test maps (click, focus, scroll), and makes it possible to find a
//! widget by identity so that keyboard/edit events can be routed to it.

use std::hash::{Hash, Hasher};

use frus_core::{
    Affine, ClipShape, Color, FontWeight, LayerFilter, LayerTransform, Path, Point, Primitive,
    Rect, Scene, Size, TextStyle,
};
use frus_layout::{Layout, NodeId, Overflowing, Side};

use crate::shortcuts::{Intent, KeyStroke};

use crate::barrier::ModalBarrier;
use crate::dismiss::{DismissPhase, Dismissable};
use crate::dragdrop::{DragSource, DropZone};
use crate::hero::{lerp_rect, HeroSpot};
use crate::interaction::{Status, WidgetId};
use crate::pageview::PageSnap;
use crate::physics::{ScrollMetrics, ScrollPhysics};
use crate::portal::Placement;
use crate::positioned::Positioning;
use crate::refresh::Refreshable;
use crate::relayout::Constraints;
use crate::runtime::Runtime;
use crate::theme::Theme;
use crate::widget::Widget;

/// Parallax factor of the screen behind during a transition (0 = fixed, 1 = follows
/// exactly). It is what gives a native navigation its depth.
const NAV_PARALLAX: f32 = 0.3;

/// Thickness of a scrollbar, in pixels (`scrollbar.dart:12`).
const BAR_SIZE: f32 = 8.0;
/// Minimum length of a thumb (`scrollbar.dart:15`). It is the tap target: a thumb has to
/// be catchable by a pointer, whatever fraction of the content the viewport shows.
const MIN_THUMB: f32 = 48.0;
/// The thumb's opacity at rest, over `on_surface` (`scrollbar.dart:248`, `:242`). The two
/// numbers are the reference's, and which one applies follows the surface's own
/// brightness — this crate's scheme carries no brightness flag, so it is read off the
/// surface rather than declared.
/// The gap between the thumb and the edge of the viewport (`scrollbar.dart:14`).
const BAR_MARGIN: f32 = 2.0;
const THUMB_ON_DARK: f32 = 0.30;
const THUMB_ON_LIGHT: f32 = 0.10;
/// And under a pointer (`scrollbar.dart:245`, `:239`) — a five-fold change on a light
/// surface, which is what makes a bar you can barely see worth reaching for.
const THUMB_HOVER_ON_DARK: f32 = 0.65;
const THUMB_HOVER_ON_LIGHT: f32 = 0.50;
/// And while it is being dragged (`scrollbar.dart:244`, `:238`), which arrives at once:
/// the hand is already on it, and a fade would only lag behind the grab.
const THUMB_DRAG_ON_DARK: f32 = 0.75;
const THUMB_DRAG_ON_LIGHT: f32 = 0.60;

/// One **axis** of a scroll area, as a scrollbar needs to see it: which way it runs, where
/// it has got to, how far it may go, whether its numbers run backwards, and what the area
/// itself said about whether it wants a bar at all.
#[derive(Copy, Clone)]
struct Bar {
    vertical: bool,
    offset: f32,
    max: f32,
    reverse: bool,
    /// The area's own answer, over the application's. See [`crate::Scrollbars`].
    asked: Option<crate::physics::Scrollbars>,
    /// Whether the area asked for its bar to stay put instead of fading.
    visible: Option<bool>,
}

/// A scrollbar thumb (for hit-testing a drag).
#[derive(Copy, Clone, Debug)]
pub struct Scrollbar {
    /// The scrollable area the bar belongs to.
    pub id: WidgetId,
    /// Whether the bar runs vertically; otherwise it is horizontal.
    pub vertical: bool,
    /// The thumb's rectangle, in absolute coordinates.
    pub thumb: Rect,
    /// Start and length of the track, along the axis.
    pub track_start: f32,
    /// The track's length along the axis.
    pub track_len: f32,
    /// The thumb's length along the axis.
    pub thumb_len: f32,
    /// Offset maximal correspondant.
    pub max: f32,
    /// The offsets of a **reversed** axis run the other way along the track: offset 0
    /// is the far end, so the thumb rests there and a drag towards the start raises the
    /// number. See [`Scrollable::reverse_y`].
    pub reverse: bool,
    /// **How present the bar is**, `0.0..=1.0`. A bar at zero is painted by nothing and
    /// cannot be grabbed — but it is still here, because a mouse that comes near it
    /// brings it back.
    pub opacity: f32,
    /// The rectangle a **mouse** has to be inside for the bar to notice it: the track,
    /// widened to take in a tap target's worth of room around the thumb. The reference
    /// reaches out like this on purpose (`scrollbar.dart:762`) — a bar 8 pixels wide,
    /// resting at a tenth of an opacity, is not something a hand aims at precisely.
    pub reach: Rect,
}

/// A scrollable area of the frame: where it is, how far it may scroll, and how it
/// is meant to behave at its edges.
///
/// The registry the shell and the runtime both read. It carries the area's own
/// [`ScrollPhysics`] only when the widget asked for one — resolving the default is
/// the application's job, through [`Scrollable::physics_or`].
#[derive(Copy, Clone, Debug)]
pub struct Scrollable {
    /// The scrollable area's identity.
    pub id: WidgetId,
    /// The viewport, in absolute coordinates.
    pub viewport: Rect,
    /// Largest horizontal offset the content may rest at (0 = nothing to scroll).
    pub max_x: f32,
    /// Largest vertical offset the content may rest at.
    pub max_y: f32,
    /// The area's own physics, when it asked for one.
    pub physics: Option<ScrollPhysics>,
    /// The [`crate::RefreshIndicator`] area this scrollable sits inside, when there is one.
    /// Movement refused at its **top** edge feeds that area's pull instead of the
    /// overscroll glow.
    pub refresh: Option<WidgetId>,
    /// Set when this area rests **only on pages** ([`crate::PageView`]): the release
    /// springs to a page boundary instead of flinging.
    pub page: Option<PageSnap>,
    /// Whether the horizontal axis is **reversed** — offset 0 is the right-hand end of
    /// the content rather than the left.
    pub reverse_x: bool,
    /// Whether the vertical axis is **reversed** — offset 0 is the **bottom** of the
    /// content rather than the top.
    ///
    /// Offsets are measured from the end an axis starts at, which is what makes a
    /// reversed list stay where it is when content arrives: a conversation resting at
    /// offset 0 is resting at the newest message, and the newest message is wherever the
    /// end now happens to be. Measuring from the top instead would leave the view
    /// drifting away from the end every time something was appended, which is the one
    /// thing this exists to prevent.
    ///
    /// Everything the *user* does is unchanged by it. A finger pushes the content the
    /// way it moves, in either direction; only the arithmetic between that push and the
    /// number changes sign, in one place.
    pub reverse_y: bool,
    /// What the content asked to be kept in view, in the frame's coordinates.
    pub keep_visible: Option<KeepVisible>,
    /// The scroll region this one sits **inside**, when there is one.
    ///
    /// Scroll areas nest — a sideways strip inside a page that scrolls down — and
    /// bringing something into view means moving every one of them, from the nearest
    /// outwards. Identities are hashes and carry no ancestry, so the walk records it.
    pub host: Option<WidgetId>,
}

impl Scrollable {
    /// This area's physics, falling back to the application's choice.
    pub fn physics_or(&self, default: ScrollPhysics) -> ScrollPhysics {
        self.physics.unwrap_or(default)
    }

    /// Whether a finger may move this area at all, resting at `offset`.
    ///
    /// The rule the reference states plainly: the user can change the offset **if, and
    /// only if, there is content outside the viewport to reveal** — or the content is
    /// already displaced, having shrunk under an offset it no longer reaches. An area that
    /// fails this takes no drag at all: not a short one, not a refused one, and so no
    /// end-of-content glow either. An edge effect where there is no edge to meet is a
    /// statement about the content that is not true.
    ///
    /// A [`crate::RefreshIndicator`] listening above is the exception, and the same one the
    /// reference makes: a list of two items must still pull down to reload.
    pub fn accepts_user_offset(&self, offset: (f32, f32)) -> bool {
        self.max_x > 0.0
            || self.max_y > 0.0
            || offset.0 != 0.0
            || offset.1 != 0.0
            || self.refresh.is_some()
    }

    /// The horizontal axis as the physics sees it, at `offset`.
    pub fn metrics_x(&self, offset: f32) -> ScrollMetrics {
        ScrollMetrics::new(offset, self.max_x, self.viewport.width)
    }

    /// The vertical axis as the physics sees it, at `offset`.
    pub fn metrics_y(&self, offset: f32) -> ScrollMetrics {
        ScrollMetrics::new(offset, self.max_y, self.viewport.height)
    }

    /// Turns a **screen** delta — how far the content was pushed, in pixels — into the
    /// change it makes to this area's offsets.
    ///
    /// Two sign changes, and both have a reason. The content moves *opposite* the
    /// number: dragging down reveals what is above, which is a smaller offset. And a
    /// reversed axis counts from the other end, so the same drag raises it instead.
    ///
    /// One function rather than a minus sign at each of the five places a delta becomes
    /// an offset — the wheel, the drag, the release fling, and both axes of each — so
    /// that a reversed scroll is right in all of them or in none.
    pub fn offset_delta(&self, screen: (f32, f32)) -> (f32, f32) {
        (
            if self.reverse_x { screen.0 } else { -screen.0 },
            if self.reverse_y { screen.1 } else { -screen.1 },
        )
    }

    /// The edge a refusal happened at, given the refused movement **in offset space**.
    ///
    /// A negative refusal means the content was pulled towards the axis's start, and
    /// where that is on screen is exactly what reversing changes: the start of a
    /// reversed vertical axis is the **bottom**. Without this the glow would flash at
    /// the far end of a conversation the moment it refused to go further back.
    pub fn refused_edge(&self, vertical: bool, refused: f32) -> crate::overscroll::GlowEdge {
        let reversed = if vertical {
            self.reverse_y
        } else {
            self.reverse_x
        };
        crate::overscroll::edge_for(vertical, if reversed { -refused } else { refused })
    }

    /// The edge an axis **starts** at, which is where a pull-to-refresh listens.
    pub fn start_edge(&self, vertical: bool) -> crate::overscroll::GlowEdge {
        self.refused_edge(vertical, -1.0)
    }

    /// The offset that brings `target` fully inside this viewport, and how far the
    /// content moves to get there.
    ///
    /// The **least** movement that does it: a box already in view does not budge, one
    /// off the near edge comes to that edge and no further. Centring it instead would
    /// make Tab through a form scroll on every stop, which is motion nobody asked for.
    ///
    /// A target **too big** for the viewport gets its leading edge aligned, which falls
    /// out of asking about that edge first: a tall field half off the top comes down to
    /// the top rather than up to the bottom, because its start is what you read.
    ///
    /// Both halves are returned because they are not the same number. The offset is
    /// clamped to what this region can actually do, and an outer region has to be told
    /// how far the target really moved — not how far it was asked to.
    pub fn reveal(&self, target: Rect, current: (f32, f32)) -> ((f32, f32), (f32, f32)) {
        let shift = |lo: f32, hi: f32, near: f32, far: f32| {
            if near < lo {
                lo - near
            } else if far > hi {
                hi - far
            } else {
                0.0
            }
        };
        let wanted = (
            shift(
                self.viewport.x,
                self.viewport.x + self.viewport.width,
                target.x,
                target.x + target.width,
            ),
            shift(
                self.viewport.y,
                self.viewport.y + self.viewport.height,
                target.y,
                target.y + target.height,
            ),
        );
        // `offset_delta` turns a movement of the content into a movement of the offset,
        // and it is its own inverse — it negates or it does not — so the same function
        // turns the offset that was allowed back into the content movement it buys.
        let delta = self.offset_delta(wanted);
        let next = (
            (current.0 + delta.0).clamp(0.0, self.max_x),
            (current.1 + delta.1).clamp(0.0, self.max_y),
        );
        let applied = (next.0 - current.0, next.1 - current.1);
        (next, self.offset_delta(applied))
    }

    /// The offset that puts `target` in the **middle** of this viewport, and how far the
    /// content moves to get there.
    ///
    /// The same pair as [`Scrollable::reveal`], and the same clamp — which is what makes
    /// the first item of a row rest at the start rather than half off it. A target
    /// bigger than the viewport centres too, which leaves it hanging over both edges,
    /// and that is the honest answer: there is no offset that shows all of it.
    pub fn centre(&self, target: Rect, current: (f32, f32)) -> ((f32, f32), (f32, f32)) {
        let wanted = (
            (self.viewport.x + self.viewport.width / 2.0) - (target.x + target.width / 2.0),
            (self.viewport.y + self.viewport.height / 2.0) - (target.y + target.height / 2.0),
        );
        let delta = self.offset_delta(wanted);
        let next = (
            (current.0 + delta.0).clamp(0.0, self.max_x),
            (current.1 + delta.1).clamp(0.0, self.max_y),
        );
        let applied = (next.0 - current.0, next.1 - current.1);
        (next, self.offset_delta(applied))
    }

    /// The offset that brings `keep` into view under its own policy, and how far the
    /// content moves from **rest** to get there.
    ///
    /// Absolute, because [`KeepVisible::rect`] is recorded at rest: the base is offset
    /// zero, not wherever the region currently is.
    pub fn keep_offset(&self, keep: KeepVisible) -> ((f32, f32), (f32, f32)) {
        match keep.centre {
            true => self.centre(keep.rect, (0.0, 0.0)),
            false => self.reveal(keep.rect, (0.0, 0.0)),
        }
    }

    /// Where the content's leading edge sits, relative to the viewport's, at `offset`.
    ///
    /// Normally minus the offset. On a reversed axis the content is anchored to the far
    /// end, so offset 0 puts the content's *end* against the viewport's — which is also
    /// the answer for content too short to scroll, where it sits at the bottom of the
    /// box rather than the top.
    pub fn content_origin(&self, offset: (f32, f32), content: Size) -> (f32, f32) {
        let axis = |reverse: bool, offset: f32, viewport: f32, content: f32| {
            if reverse {
                viewport - content + offset
            } else {
                -offset
            }
        };
        (
            axis(self.reverse_x, offset.0, self.viewport.width, content.width),
            axis(
                self.reverse_y,
                offset.1,
                self.viewport.height,
                content.height,
            ),
        )
    }
}

/// A box a scroll region has been asked to **keep in view**, and which box it is.
///
/// A tab bar wider than its window is what this is for. Declared by the content through
/// [`Widget::keep_visible`], carried on the region so it survives a repaint boundary
/// like everything else about the region, and acted on by
/// [`crate::Runtime::sync_visible`].
#[derive(Copy, Clone, Debug, PartialEq)]
pub struct KeepVisible {
    /// Which box this is. The region acts when this **changes** and not otherwise: the
    /// box moves as the region scrolls, so a region chasing the box itself would pin
    /// the content in place and no finger could move it.
    pub key: u64,
    /// The box: in the declaring widget's own coordinates when it comes back from
    /// [`Widget::keep_visible`], and in the frame's — **as it would sit at offset zero**
    /// — when it reaches the region.
    ///
    /// At rest rather than where it is actually drawn, and that is the whole reason the
    /// answer can be trusted. A box recorded where it is drawn is a box whose position
    /// already contains the current offset, so the offset that would centre it can only
    /// be worked out **relative** to wherever the region happens to be — and on the
    /// first frame, before anything has been retained, there is no wherever to be
    /// relative to. Recorded at rest, the answer is absolute: the same number on the
    /// first frame and the hundredth.
    pub rect: Rect,
    /// Put it in the **middle** of the window rather than merely inside it. What a tab
    /// bar wants: a selected tab flush against the edge reads as the end of the row.
    /// Clamped either way, so the first tab still rests at the start.
    pub centre: bool,
}

/// Direction of arrow-key focus navigation.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FocusDirection {
    /// The up arrow: focus moves to the widget above.
    Up,
    /// The down arrow: focus moves to the widget below.
    Down,
    /// The left arrow: focus moves to the widget on the left.
    Left,
    /// The right arrow: focus moves to the widget on the right.
    Right,
}

#[derive(Clone)]
struct Hit<Msg> {
    id: WidgetId,
    rect: Rect,
    /// The message the target emits, or `None` for a target that **swallows** input
    /// without doing anything — an [`crate::AbsorbPointer`]. Such a target still wins
    /// the hit test, which is exactly what stops the click reaching what is behind it.
    msg: Option<Msg>,
    /// **Inverse** transform (screen → the flat frame) of a transformed subtree
    /// (`Transform::scale`/`rotate`/a composition): the test point is passed through it to
    /// get back to the untransformed frame where `rect` lives. `None` = an axis-aligned,
    /// untransformed rect (the common case).
    xform: Option<Affine>,
}

impl<Msg> Hit<Msg> {
    /// `true` when `point` (in screen coordinates) falls inside the target, taking any
    /// transform on the subtree into account.
    fn contains(&self, point: Point) -> bool {
        let p = self.xform.map_or(point, |inv| inv.apply(point));
        self.rect.contains(p)
    }
}

/// The painted output of a repaint-boundary subtree, cached (see `paintcache.rs`) and
/// replayed as is on a *hit*. Erased behind a `Box<dyn Any>` in the cache; brought back down
/// to `Msg` here (one `Msg` instance per app → the `downcast` always succeeds).
#[derive(Clone)]
struct BoundaryData<Msg> {
    prims: Vec<frus_core::Primitive>,
    hits: Vec<Hit<Msg>>,
    long_presses: Vec<Hit<Msg>>,
    dismisses: Vec<Msg>,
    focusables: Vec<Focusable>,
    scrollables: Vec<Scrollable>,
    draggables: Vec<(WidgetId, Rect)>,
    drag_sources: Vec<DragSource>,
    drop_zones: Vec<DropZone>,
    inks: Vec<(WidgetId, Rect)>,
    semantics: Vec<(WidgetId, Rect, frus_core::SemanticsProperties)>,
    system_ui: Vec<(Rect, crate::SystemUiOverlayStyle)>,
}

/// Lengths of the builder's collections on entering a boundary: the lower bounds of the
/// slices to capture on the way out.
struct Snapshot {
    scene: usize,
    hits: usize,
    long_presses: usize,
    dismisses: usize,
    focusables: usize,
    scrollables: usize,
    draggables: usize,
    drag_sources: usize,
    drop_zones: usize,
    inks: usize,
    semantics: usize,
    system_ui: usize,
    overlays: usize,
    focus_scope_start: Option<usize>,
}

/// Lower bounds of the **interaction** registries at the start of a transformed composition
/// (a scale/rotation layer): only what the subtree has just added is re-mapped. Distinct from
/// [`Snapshot`] (the boundary cache) because it **includes `reorderables`** — those are never
/// cached but do have to be transformed. See [`transform_interaction_registries`].
/// Lengths of the registries a [`ModalBarrier`] withholds from, on entering its subtree: the
/// point each is truncated back to on the way out. Distinct from [`XformBase`] because a
/// barrier also covers the **scene** and the **scrollbars**, and distinct from [`Snapshot`]
/// because it covers the registries that are never cached.
/// What is withdrawn from a layer of an [`crate::IndexedStack`] that is not the shown one:
/// its paint, its input and its place in the accessibility tree. Not `absorb` — the layer
/// is not a scrim over what is behind it, it is simply not there for the reader.
const HIDDEN_LAYER: crate::barrier::ModalBarrier = crate::barrier::ModalBarrier {
    pointer: true,
    absorb: false,
    paint: true,
    semantics: true,
};

struct BarrierBase {
    scene: usize,
    hits: usize,
    long_presses: usize,
    focusables: usize,
    scrollables: usize,
    scrollbars: usize,
    draggables: usize,
    drag_sources: usize,
    drop_zones: usize,
    inks: usize,
    reorderables: usize,
    interactives: usize,
    semantics: usize,
}

struct XformBase {
    hits: usize,
    long_presses: usize,
    focusables: usize,
    scrollables: usize,
    draggables: usize,
    drag_sources: usize,
    drop_zones: usize,
    inks: usize,
    reorderables: usize,
    semantics: usize,
}

/// Node count of the subtree **if** it is "plain" — that is, if the boundary and **all** its
/// descendants take the default walk branch (children in prefix order): not scrollable, not a
/// navigator, not a virtualised list, no `layout_builder`, not a stack, no overlay, no
/// continuous animation. The count then follows the walk's rect order **exactly**, which is
/// what makes the fingerprint and the bit-for-bit replay correct. `None` = a subtree that
/// cannot be cached (it is repainted in full — the safe fallback).
fn plain_subtree_len<Msg>(widget: &dyn Widget<Msg>) -> Option<usize> {
    if widget.continuous()
        || widget.scroll_content().is_some()
        || widget.interactive().is_some()
        || widget.fitted().is_some()
        || widget.rotated_quarter_turns().is_some()
        || widget.navigator().is_some()
        // Only *whether*, never *what*: these two ask if the widget windows its
        // children at all, and a size it will not read is the honest argument.
        || widget.virtual_list(Size::ZERO).is_some()
        || widget.page_view().is_some()
        || widget.overflow_box().is_some()
        || widget.constraints_transform().is_some()
        || widget.layout_builder().is_some()
        || widget.stack()
        || widget.overlay().is_some()
        // A reorderable (a Kanban card, a draggable header): its bounds feed the reorderables
        // registry, which is not cached — so its subtree is not put in the paint cache.
        || widget.reorder_index().is_some()
    {
        return None;
    }
    let mut n = 1;
    for child in widget.children() {
        n += plain_subtree_len(child.as_ref())?;
    }
    Some(n)
}

/// Quantises a `[0,1]` float for the fingerprint (independent of tiny binary differences: two
/// visually identical progresses ⇒ the same fingerprint).
fn quant(x: f32) -> i32 {
    (x * 4096.0).round() as i32
}

/// Adds to `h` everything the paint reads from a `Status`, **except** the time (excluded: a
/// cacheable boundary holds no `continuous` widget).
fn hash_status<H: Hasher>(s: &Status, h: &mut H) {
    (s.interaction as u8).hash(h);
    s.focused.hash(h);
    s.cursor.hash(h);
    s.selection.hash(h);
    s.composing.hash(h);
    quant(s.hover_progress).hash(h);
    quant(s.focus_progress).hash(h);
    quant(s.press_progress).hash(h);
    quant(s.opacity).hash(h);
    quant(s.value).hash(h);
    // Sub-region hover (milestone 208): a change of position repaints the highlight.
    s.hover_cursor.map(|p| (quant(p.x), quant(p.y))).hash(h);
}

/// The result of building an interface for one frame.
/// A **shortcut / action scope**: a subtree that binds keystrokes, answers intents, or
/// both, together with the range of focus stops it contains.
///
/// The range is how "focus is inside this subtree" is answered without an ancestor test:
/// the walk is depth-first, so a subtree's focus stops are contiguous, and the focused
/// stop's index either falls inside the range or does not.
struct Scope<Msg> {
    strokes: Vec<(KeyStroke, Intent)>,
    callbacks: Vec<(KeyStroke, Msg)>,
    actions: Vec<(Intent, Msg)>,
    listeners: Vec<(Intent, Msg)>,
    /// The focus stops this subtree contains, as indices into `focusables`.
    range: std::ops::Range<usize>,
}

/// A **focus stop**: somewhere the keyboard can land, and what the traversal should make
/// of it.
#[derive(Clone, Copy, Debug)]
pub struct Focusable {
    /// The widget's identity.
    pub id: WidgetId,
    /// Its **visible** box this frame: the box it was given, clipped by whatever
    /// encloses it. Empty when it is scrolled out of sight, which is what a click test
    /// wants — a tap on empty space must not land on something nobody can see.
    pub rect: Rect,
    /// Its box this frame, **unclipped**. What the geometry is really about: where the
    /// widget is, whether or not any of it is on screen. Arrow navigation places
    /// candidates by this, and [`Ui::reveal`] works out what to scroll from it.
    pub bounds: Rect,
    /// The [`crate::AutofillGroup`] this stop sits in — the form it is part of — when
    /// there is one (milestone 512).
    pub form: Option<WidgetId>,
    /// The nearest enclosing scroll region, when there is one. What could bring this
    /// stop into view, and the first link of the chain [`Ui::reveal`] walks.
    pub scroll: Option<WidgetId>,
    /// Focusable by a click, but **passed over by Tab** — the reference's
    /// `ExcludeFocusTraversal`. The two are separate questions.
    pub skip: bool,
    /// An explicit traversal position, smallest first. `None` means tree order, which is
    /// where everything sits until someone says otherwise.
    pub order: Option<f32>,
    /// The traversal group it belongs to, within which its order is resolved.
    pub group: Option<WidgetId>,
}

/// The **interface** of one frame: what the walk over a widget tree produced.
///
/// Besides the [`Scene`] to paint it holds everything the shell asks of a frame afterwards —
/// what a click, a long press or a dismissal answers, what can take the focus, which areas
/// scroll, which widgets can be dragged or dropped on — so that events are routed against
/// the frame the reader saw. It is made by [`build_ui`] and read until the next frame
/// replaces it.
pub struct Ui<Msg = crate::callback::Callback> {
    scene: Scene,
    hits: Vec<Hit<Msg>>,
    /// Long-press targets (id, visible bounds, message).
    long_presses: Vec<Hit<Msg>>,
    /// Overlay dismissal messages, from the bottom to the **top**.
    dismisses: Vec<Msg>,
    focusables: Vec<Focusable>,
    /// **Focus scope**: index of the topmost modal overlay's first focusable —
    /// Tab/arrows/click-to-focus are trapped from there on (`None` = no modal, every
    /// focusable takes part).
    focus_scope_start: Option<usize>,
    /// (id, viewport, offset max x, offset max y)
    scrollables: Vec<Scrollable>,
    scrollbars: Vec<Scrollbar>,
    draggables: Vec<(WidgetId, Rect)>,
    drag_sources: Vec<DragSource>,
    drop_zones: Vec<DropZone>,
    /// **Inked surfaces**: (id, the box the ink is clipped to). Tracked separately from
    /// clicking because the splash needs the surface's **whole** box — where the finger
    /// landed inside it, and how far the circle has to travel to cover it — which a
    /// click target, recorded as its *visible* part, does not give.
    inks: Vec<(WidgetId, Rect)>,
    /// **Reorderables** (column headers, Kanban cards): (id, visible bounds). Tracked
    /// independently of clicking — a card is not clickable but can still be picked up and
    /// dropped onto.
    reorderables: Vec<(WidgetId, Rect)>,
    /// Interactive viewports (`InteractiveViewer`): (id, the screen viewport). The shell
    /// routes panning (dragging) and zooming (wheel / pinch) to them.
    interactives: Vec<(WidgetId, Rect)>,
    /// Pull-to-refresh areas of the frame, with their configuration.
    refreshes: Vec<Refreshable>,
    /// Swipe-to-dismiss items of the frame, with their configuration.
    dismissables: Vec<Dismissable>,
    /// Draggable sheets of the frame, with their configuration and the scroll areas
    /// walked inside each.
    sheets: Vec<crate::sheet::SheetArea>,
    wants_animation: bool,
    /// The accessibility tree: semantic nodes (id, bounds, annotation), in paint order. The
    /// shell maps it onto AccessKit.
    semantics: Vec<(WidgetId, Rect, frus_core::SemanticsProperties)>,
    /// The regions saying what the system bars over them should look like (paint order).
    system_ui: Vec<(Rect, crate::SystemUiOverlayStyle)>,
    /// Boxes whose children ran outside them, with the edge and the amount.
    overflows: Vec<Overflowing>,
    /// Shortcut and action scopes, in the order the walk closed them — innermost first
    /// among any that overlap, which is the order the resolution wants.
    scopes: Vec<Scope<Msg>>,
    /// Keystroke listeners, with the focus stops they cover.
    #[allow(clippy::type_complexity)]
    listeners: Vec<(
        std::ops::Range<usize>,
        std::rc::Rc<dyn Fn(KeyStroke) -> Option<Msg>>,
    )>,
}

impl<Msg: Clone> Ui<Msg> {
    /// The scene to hand to the renderer.
    /// Boxes in this frame whose children did not fit inside them.
    ///
    /// Empty is the normal answer. A non-empty one means content is being drawn outside
    /// its parent — invisible where it is clipped, unhittable where it leaves the window,
    /// and silent either way until something asks. That silence is what let a task row's
    /// delete button sit off-screen through three milestones.
    pub fn overflows(&self) -> &[Overflowing] {
        &self.overflows
    }

    /// The scrollbars this frame drew, and therefore the ones a pointer may drag. Empty
    /// where the platform draws none — see [`crate::Scrollbars`].
    pub fn scrollbars(&self) -> &[Scrollbar] {
        &self.scrollbars
    }

    /// The [`Scene`] this frame painted.
    pub fn scene(&self) -> &Scene {
        &self.scene
    }

    /// The frame's **accessibility tree**: every meaningful node with its bounds on screen and
    /// its annotation ([`frus_core::SemanticsProperties`]). Paint order (= reading order). The shell
    /// pushes it to AccessKit.
    pub fn semantics(&self) -> &[(WidgetId, Rect, frus_core::SemanticsProperties)] {
        &self.semantics
    }

    /// What the system bars should look like over this frame (#46): the regions under
    /// `status_bar` answer for the status bar and those under `navigation_bar` for the
    /// other, the one drawn last first and field by field. What none states is left
    /// `None`, for [`crate::SystemUiOverlayStyle::resolve`] to take from the theme.
    ///
    /// The shell picks the two points: the first row of the screen's content under the
    /// status bar, and the last one above the navigation bar.
    pub fn system_ui_style(
        &self,
        status_bar: Point,
        navigation_bar: Point,
    ) -> crate::SystemUiOverlayStyle {
        crate::system_ui::style_under(&self.system_ui, status_bar, navigation_bar)
    }

    /// `true` when a widget animates continuously (the framework must redraw).
    /// Whether **this tree's widgets** want the next frame: a spinner turning, an ink
    /// ripple spreading, a pull being held.
    ///
    /// It answers for the widgets and nothing else. A fetch still in flight also owes the
    /// screen a frame — see [`frus_core::images_in_flight`] — and that is the *process's*
    /// business, asked by whoever drives the loop. It used to be folded in here, which
    /// made this method's answer depend on what an unrelated part of the program happened
    /// to be doing: in the test suite, where everything shares one process, a refresh area
    /// with nothing pulled asked for frames whenever another test was loading an image
    /// (milestone 411).
    pub fn wants_animation(&self) -> bool {
        self.wants_animation
    }

    /// Identity of the topmost clickable widget containing `point`.
    pub fn hit(&self, point: Point) -> Option<WidgetId> {
        self.hits
            .iter()
            .rev()
            .find(|hit| hit.contains(point))
            .map(|hit| hit.id)
    }

    /// The message tied to a given clickable widget. `None` for a target that swallows
    /// input without emitting anything.
    ///
    /// It is always paired with [`hit`](Self::hit), so the two have to agree on which
    /// target an identity means: every registered target therefore has one of its own,
    /// the dismissal barrier below an overlay included.
    pub fn msg_for(&self, id: WidgetId) -> Option<Msg> {
        self.hits
            .iter()
            .find(|hit| hit.id == id)
            .and_then(|hit| hit.msg.clone())
    }

    /// Dismissal message of the **topmost** overlay (for Escape).
    pub fn top_dismiss(&self) -> Option<Msg> {
        self.dismisses.last().cloned()
    }

    /// **Long-press** message of the topmost target containing `point`.
    pub fn long_press_at(&self, point: Point) -> Option<Msg> {
        self.long_presses
            .iter()
            .rev()
            .find(|hit| hit.contains(point))
            .and_then(|hit| hit.msg.clone())
    }

    /// The frame's **pull-to-refresh areas**, with the configuration each was built
    /// with. The shell steps them and reads their `refreshing` flag from here.
    pub fn refresh_areas(&self) -> &[Refreshable] {
        &self.refreshes
    }

    /// The frame's **dismissible items**, with the configuration each was built with.
    pub fn dismissables(&self) -> &[Dismissable] {
        &self.dismissables
    }

    /// The frame's **sheets**, with the configuration each was built with and the scroll
    /// areas walked inside it.
    pub fn sheets(&self) -> &[crate::sheet::SheetArea] {
        &self.sheets
    }

    /// The sheet whose panel is under `point`, the last one walked winning — which is
    /// the one painted on top.
    pub fn sheet_at(&self, point: Point) -> Option<&crate::sheet::SheetArea> {
        self.sheets.iter().rev().find(|sheet| sheet.contains(point))
    }

    /// The sheet `id`, when it is in the frame.
    pub fn sheet(&self, id: WidgetId) -> Option<&crate::sheet::SheetArea> {
        self.sheets.iter().find(|sheet| sheet.id == id)
    }

    /// The sheet the scroll area `area` was walked inside, when there is one — the
    /// innermost, should sheets nest, since an outer one counts the inner one's areas too.
    pub fn sheet_holding(&self, area: WidgetId) -> Option<&crate::sheet::SheetArea> {
        self.sheets
            .iter()
            .filter(|sheet| sheet.areas.contains(&area))
            .min_by_key(|sheet| sheet.areas.len())
    }

    /// The topmost dismissible item containing `point` — the candidate a press has to
    /// weigh against the scrollable underneath it.
    pub fn dismissable_at(&self, point: Point) -> Option<Dismissable> {
        self.dismissables
            .iter()
            .rev()
            .find(|item| item.rect.contains(point))
            .copied()
    }

    /// Topmost focusable widget containing `point`: (id, its bounds).
    pub fn focus_hit(&self, point: Point) -> Option<(WidgetId, Rect)> {
        self.focus_pool()
            .iter()
            .rev()
            .find(|f| f.rect.contains(point))
            .map(|f| (f.id, f.rect))
    }

    /// The **participating** focusables: those of the topmost modal scope when there is one
    /// (a focus trap), otherwise all of them.
    fn focus_pool(&self) -> &[Focusable] {
        match self.focus_scope_start {
            Some(start) => &self.focusables[start.min(self.focusables.len())..],
            None => &self.focusables,
        }
    }

    /// Nearest focusable in the given **direction** (arrow navigation, a geometric policy):
    /// among the focusables whose centre lies on the right side, it minimises the distance
    /// along the main axis with a penalty on the cross-axis offset. `None` when there is
    /// nothing in that direction.
    pub fn focus_directional(
        &self,
        current: WidgetId,
        direction: FocusDirection,
    ) -> Option<WidgetId> {
        // The starting point may be outside the scope (focus from before it opened); the
        // **candidates**, though, are trapped inside it.
        let from = self
            .focusables
            .iter()
            .find(|f| f.id == current)
            .map(|f| &f.rect)?;
        let center = |r: &Rect| (r.x + r.width * 0.5, r.y + r.height * 0.5);
        let (fx, fy) = center(from);

        let mut best: Option<(WidgetId, f32)> = None;
        for candidate in self.focus_pool() {
            let (id, rect) = (candidate.id, &candidate.rect);
            if id == current {
                continue;
            }
            let (cx, cy) = center(rect);
            // (how far ahead in the direction, the cross-axis offset)
            let (ahead, cross) = match direction {
                FocusDirection::Right => (cx - fx, (cy - fy).abs()),
                FocusDirection::Left => (fx - cx, (cy - fy).abs()),
                FocusDirection::Down => (cy - fy, (cx - fx).abs()),
                FocusDirection::Up => (fy - cy, (cx - fx).abs()),
            };
            // Inside a **cone** around the direction (not a plain half-plane): a candidate
            // almost aligned on the cross axis but barely "ahead" (slightly different widths)
            // is not a directional target.
            if ahead <= 0.5 || cross > ahead * 3.0 {
                continue;
            }
            let score = ahead + cross * 3.0;
            if best.map(|(_, s)| score < s).unwrap_or(true) {
                best = Some((id, score));
            }
        }
        best.map(|(id, _)| id)
    }

    /// Next/previous focus stop for Tab, wrapping. With no current focus, the first (or
    /// the last).
    ///
    /// **Tree order, unless something said otherwise.** Stops carrying an explicit order
    /// are sorted ahead of those that do not, smallest first, and the sort is applied
    /// **within a traversal group** rather than across the whole frame — so a reordered
    /// dialog does not reshuffle the page behind it. Stops marked `skip` are passed over
    /// here while remaining reachable by a click: the keyboard's order and the pointer's
    /// reach are two different questions.
    pub fn focus_next(&self, current: Option<WidgetId>, forward: bool) -> Option<WidgetId> {
        let order = self.traversal_order();
        if order.is_empty() {
            return None;
        }
        let n = order.len();
        // A current focus **outside the scope** (taken before the modal opened) is treated
        // as "none": Tab enters the trap.
        match current.and_then(|c| order.iter().position(|id| *id == c)) {
            Some(i) => {
                let j = if forward {
                    (i + 1) % n
                } else {
                    (i + n - 1) % n
                };
                Some(order[j])
            }
            None => Some(order[if forward { 0 } else { n - 1 }]),
        }
    }

    /// The Tab order: the participating stops, minus those that asked to be skipped,
    /// with each traversal group's members sorted among themselves.
    ///
    /// A **stable** sort on the order key, so everything without one keeps tree order and
    /// ties do too — the property that makes an explicit order a local statement rather
    /// than a rearrangement of the whole frame.
    pub fn traversal_order(&self) -> Vec<WidgetId> {
        let pool: Vec<&Focusable> = self.focus_pool().iter().filter(|f| !f.skip).collect();
        if pool.iter().all(|f| f.order.is_none()) {
            return pool.iter().map(|f| f.id).collect();
        }
        let mut out: Vec<WidgetId> = Vec::with_capacity(pool.len());
        let mut i = 0;
        while i < pool.len() {
            // A group's members are contiguous: the walk is depth-first, so a subtree's
            // stops arrive together.
            let group = pool[i].group;
            let mut j = i;
            while j < pool.len() && pool[j].group == group {
                j += 1;
            }
            let mut run: Vec<&Focusable> = pool[i..j].to_vec();
            run.sort_by(|a, b| {
                let key = |f: &Focusable| f.order.unwrap_or(f32::INFINITY);
                key(a).total_cmp(&key(b))
            });
            out.extend(run.iter().map(|f| f.id));
            i = j;
        }
        out
    }

    /// What a keystroke means here: the messages it sends, in the order they should be
    /// applied.
    ///
    /// The resolution, in one place because it is the whole feature:
    ///
    /// 1. Only scopes **containing the focused stop** are candidates; with nothing
    ///    focused, all of them are. Innermost first — `scopes` is filled on the way *out*
    ///    of the walk, so that order is already the one wanted.
    /// 2. A [`crate::KeyboardListener`] gets the first refusal, and a `None` from it lets
    ///    the stroke carry on.
    /// 3. A direct binding ([`crate::CallbackShortcuts`]) sends its message.
    /// 4. Otherwise a [`crate::Shortcuts`] binding names an **intent**, and the innermost
    ///    [`crate::Actions`] that answers it supplies the message. An intent nobody
    ///    answers does nothing — deliberately: a key bound to a meaning the current screen
    ///    has no answer for should be inert, not an error.
    /// 5. Every [`crate::ActionListener`] watching that intent adds its message too.
    ///
    /// Empty means *nobody wanted it*, and the caller should carry on to whatever it would
    /// have done with the key.
    pub fn keystroke(&self, stroke: KeyStroke, focused: Option<WidgetId>) -> Vec<Msg> {
        let at = focused.and_then(|id| self.focusables.iter().position(|f| f.id == id));
        let covers = |range: &std::ops::Range<usize>| match at {
            Some(i) => range.contains(&i),
            None => true,
        };

        for (range, on_key) in self.listeners.iter().rev() {
            if covers(range) {
                if let Some(msg) = on_key(stroke) {
                    return vec![msg];
                }
            }
        }

        let mut out = Vec::new();
        for scope in self.scopes.iter().filter(|s| covers(&s.range)) {
            if let Some((_, msg)) = scope.callbacks.iter().find(|(s, _)| stroke.matches(s)) {
                out.push(msg.clone());
                return out;
            }
            let Some((_, intent)) = scope.strokes.iter().find(|(s, _)| stroke.matches(s)) else {
                continue;
            };
            let answer = self
                .scopes
                .iter()
                .filter(|s| covers(&s.range))
                .find_map(|s| {
                    s.actions
                        .iter()
                        .find(|(i, _)| i == intent)
                        .map(|(_, m)| m.clone())
                });
            if let Some(msg) = answer {
                out.push(msg);
                for watcher in self.scopes.iter().filter(|s| covers(&s.range)) {
                    for (i, m) in &watcher.listeners {
                        if i == intent {
                            out.push(m.clone());
                        }
                    }
                }
            }
            return out;
        }
        out
    }

    /// Topmost scrollable area containing `point`.
    pub fn scroll_hit(&self, point: Point) -> Option<Scrollable> {
        self.scrollables
            .iter()
            .rev()
            .find(|area| area.viewport.contains(point))
            .copied()
    }

    /// **Every** scrollable area containing `point`, innermost first — the whole stack a
    /// finger has under it.
    ///
    /// [`Self::scroll_hit`] answers *which one is on top*, which is the right question for
    /// a wheel or a scrollbar. A finger asks a different one: a strip that only slides
    /// across, sitting in a page that only scrolls down, cannot take a drag downwards, and
    /// the page behind it can. Deciding that needs the ones behind as well.
    pub fn scroll_chain(&self, point: Point) -> impl Iterator<Item = Scrollable> + '_ {
        self.scrollables
            .iter()
            .rev()
            .filter(move |area| area.viewport.contains(point))
            .copied()
    }

    /// Frame of a **focusable** widget `id`, when it is present this frame — so the shell can
    /// find the focused field's geometry (vertical caret movement).
    pub fn widget_rect(&self, id: WidgetId) -> Option<Rect> {
        self.focusables
            .iter()
            .find(|f| f.id == id)
            .map(|f| f.rect)
            // Falls back to the **reorderables** registry. Kanban cards (and headers that are
            // reorderable but **not** sortable) are not focusable: without this fallback the
            // shell cannot find their bounds, and the whole **vertical** drag preview (ghost,
            // insertion line, reflow) as well as the *insert-after* routing stay dead.
            .or_else(|| {
                self.reorderables
                    .iter()
                    .find(|(rid, _)| *rid == id)
                    .map(|(_, rect)| *rect)
            })
    }

    /// The box of the inked surface `id`, when the frame has one — what the shell needs
    /// to start a splash: where inside it the finger landed, and how big it is.
    ///
    /// The **topmost** match wins, as the hit-test does: two inked surfaces can overlap,
    /// and the one that took the tap is the one drawn last.
    pub fn ink_box(&self, id: WidgetId) -> Option<Rect> {
        self.inks
            .iter()
            .rev()
            .find(|(iid, _)| *iid == id)
            .map(|(_, rect)| *rect)
    }

    /// The identities of **every** focusable widget of the frame (the scope included) — so
    /// the shell can detect the focus **disappearing** (an overlay closed) and restore it.
    pub fn focusable_ids(&self) -> impl Iterator<Item = WidgetId> + '_ {
        self.focusables.iter().map(|f| f.id)
    }

    /// The focus stops of the **form** `id` is part of, in tree order, each with its box
    /// this frame (unclipped: a field scrolled out of sight is still a field of the form).
    /// A stop in no [`crate::AutofillGroup`] is a form of one. Empty when `id` is not a
    /// focus stop this frame.
    ///
    /// Stops, not fields: which of them take part in autofill is a question for the
    /// widgets ([`crate::Widget::autofill_hints`]), which the shell has and this does not.
    pub fn form_of(&self, id: WidgetId) -> Vec<(WidgetId, Rect)> {
        let Some(stop) = self.focusables.iter().find(|f| f.id == id) else {
            return Vec::new();
        };
        match stop.form {
            Some(form) => self.group_stops(form),
            None => vec![(stop.id, stop.bounds)],
        }
    }

    /// The [`crate::AutofillGroup`] focus stop `id` sits in, if it is a stop this frame
    /// and sits in one.
    pub fn form_group(&self, id: WidgetId) -> Option<WidgetId> {
        self.focusables.iter().find(|f| f.id == id)?.form
    }

    /// Every focus stop inside the [`crate::AutofillGroup`] `group`, in tree order, with
    /// its unclipped box. Empty once the group has left the screen — which is the moment
    /// a form is finished with, and the platform may offer to save what was typed in it.
    pub fn group_stops(&self, group: WidgetId) -> Vec<(WidgetId, Rect)> {
        self.focusables
            .iter()
            .filter(|f| f.form == Some(group))
            .map(|f| (f.id, f.bounds))
            .collect()
    }

    /// Frame (viewport) of the scrollable area `id`, when there is one — so the shell can find
    /// a multi-line field's width/height (caret following).
    pub fn scrollable_viewport(&self, id: WidgetId) -> Option<Rect> {
        self.scrollables
            .iter()
            .find(|area| area.id == id)
            .map(|area| area.viewport)
    }

    /// The scroll offsets that would bring `id` **into view**, nearest region first.
    ///
    /// Empty when it is already in view, when the frame does not contain it, or when
    /// nothing around it scrolls. Nobody has to check first: an empty answer is the
    /// answer that nothing needs to move.
    ///
    /// Nested regions are walked from the inside out, and each is told where the target
    /// **ended up** rather than where it started. A sideways strip inside a page that
    /// scrolls down moves the target across, and the page then decides how far down it
    /// still is; asking both about the original box would have them fight over the same
    /// pixels and land somewhere neither wanted.
    pub fn reveal(&self, id: WidgetId, runtime: &crate::Runtime) -> Vec<(WidgetId, (f32, f32))> {
        let Some(stop) = self.focusables.iter().find(|f| f.id == id) else {
            return Vec::new();
        };
        let mut target = stop.bounds;
        let mut host = stop.scroll;
        let mut moves = Vec::new();
        // Regions nest a handful deep at most. The bound is a backstop against a chain
        // that loops, which cannot happen and would hang the frame if it did.
        for _ in 0..16 {
            let Some(hid) = host else { break };
            let Some(area) = self.scrollables.iter().find(|area| area.id == hid) else {
                break;
            };
            let current = runtime.scroll.get(&hid).copied().unwrap_or((0.0, 0.0));
            let (offset, shift) = area.reveal(target, current);
            if shift.0 != 0.0 || shift.1 != 0.0 {
                target = target.translate(shift.0, shift.1);
                moves.push((hid, offset));
            }
            host = area.host;
        }
        moves
    }

    /// Every scrollable area of the frame — geometry, bounds and physics — which is
    /// what the runtime needs to drive momentum and edges.
    pub fn scroll_regions(&self) -> &[Scrollable] {
        &self.scrollables
    }

    /// The area `id`, when it is present this frame.
    pub fn scroll_region(&self, id: WidgetId) -> Option<Scrollable> {
        self.scrollables.iter().find(|area| area.id == id).copied()
    }

    /// SingleChildScrollView bounds `(id, max_x, max_y)` of every scrollable area.
    pub fn scrollable_maxes(&self) -> Vec<(WidgetId, f32, f32)> {
        self.scrollables
            .iter()
            .map(|area| (area.id, area.max_x, area.max_y))
            .collect()
    }

    /// Scrollbar thumb under `point` (to start a drag).
    pub fn scrollbar_at(&self, point: Point) -> Option<Scrollbar> {
        self.scrollbars
            .iter()
            .rev()
            .find(|bar| bar.opacity > 0.0 && bar.thumb.contains(point))
            .copied()
    }

    /// The scrollbar a **pointer is near enough to wake**: inside its track, or within a
    /// tap target's reach of its thumb.
    ///
    /// Wider than [`Ui::scrollbar_at`], and — unlike it — it answers for a bar that has
    /// faded out entirely, which is the whole point. A bar nobody can see is a bar nobody
    /// can grab, so the reference lets a mouse coming near one bring it back first
    /// (`scrollbar.dart:766`); only then is it something to take hold of.
    pub fn scrollbar_near(&self, point: Point) -> Option<Scrollbar> {
        self.scrollbars
            .iter()
            .rev()
            .find(|bar| bar.reach.contains(point))
            .copied()
    }

    /// Topmost draggable widget under `point`: (id, its bounds).
    pub fn draggable_at(&self, point: Point) -> Option<(WidgetId, Rect)> {
        self.draggables
            .iter()
            .rev()
            .find(|(_, rect)| rect.contains(point))
            .map(|(id, rect)| (*id, *rect))
    }

    /// Topmost **drag source** under `point`, with what it carries.
    pub fn drag_source_at(&self, point: Point) -> Option<DragSource> {
        self.drag_sources
            .iter()
            .rev()
            .find(|source| source.rect.contains(point))
            .copied()
    }

    /// Topmost **drop target** under `point`.
    pub fn drop_zone_at(&self, point: Point) -> Option<DropZone> {
        self.drop_zones
            .iter()
            .rev()
            .find(|zone| zone.rect.contains(point))
            .copied()
    }

    /// Topmost **reorderable** widget under `point`: its id. The basis of reordering
    /// drag-and-drop (the source on press, the target on drop) — independent of clickability.
    pub fn reorderable_at(&self, point: Point) -> Option<WidgetId> {
        self.reorderables
            .iter()
            .rev()
            .find(|(_, rect)| rect.contains(point))
            .map(|(id, _)| *id)
    }

    /// **Every** reorderable under `point`, topmost first.
    ///
    /// [`Self::reorderable_at`] answers *which one is on top*, which is the right question
    /// for a press: whatever is nearest the finger is what the finger grabbed. A **drop**
    /// asks a different one, because the thing on top may be a grip that nothing can be
    /// dropped on — see [`Widget::reorder_droppable`] — and the row it belongs to, which
    /// can, is the one behind it.
    pub fn reorderables_at(&self, point: Point) -> impl Iterator<Item = WidgetId> + '_ {
        self.reorderables
            .iter()
            .rev()
            .filter(move |(_, rect)| rect.contains(point))
            .map(|(id, _)| *id)
    }

    /// Every **reorderable** of the frame, with its box, in paint order.
    pub fn reorderables(&self) -> &[(WidgetId, Rect)] {
        &self.reorderables
    }

    /// Topmost **interactive** viewport (`InteractiveViewer`) under `point`: (id, its screen
    /// viewport). The shell routes panning and zooming to it.
    pub fn interactive_at(&self, point: Point) -> Option<(WidgetId, Rect)> {
        self.interactives
            .iter()
            .rev()
            .find(|(_, rect)| rect.contains(point))
            .map(|(id, rect)| (*id, *rect))
    }

    /// Interactive viewports `(id, screen viewport)`, to drive the inertia (fling) and the
    /// clamping of the pan on the framework's side.
    pub fn interactive_bounds(&self) -> Vec<(WidgetId, Rect)> {
        self.interactives.clone()
    }
}

/// Paints a **striped band** along the edge of every box whose children ran past it.
///
/// Milestone 335 taught the layout to notice an overflow and the shell to say so in the
/// console. That is the half a developer reads; this is the half a *screenshot* shows —
/// and a screenshot is what a bug report is made of. Three of this framework's own
/// milestones went looking for defects that a band would have pointed at: a delete button
/// laid out past the card (333, 334), a segmented control 221 px outside its parent (335).
///
/// The look is the reference's, because the point of it is to be recognised on sight:
/// black and yellow diagonal stripes, three quarters opaque, over a tenth of the box along
/// the offending edge, with the edge and the number written across it. Not the mechanism,
/// though — the reference paints one repeating gradient and this paints the stripes,
/// because a repeating diagonal gradient is a shader feature and a parallelogram is four
/// points.
///
/// **Debug builds only.** A band is a message to whoever is building the application, and
/// in a release build there is nobody to read it — the reference draws the same line.
fn paint_overflow_bands(scene: &mut Scene, overflows: &[Overflowing]) {
    if !cfg!(debug_assertions) || overflows.is_empty() {
        return;
    }
    // The reference's two colours and its 10 % band, exactly.
    const BLACK: Color = Color::rgba(0.0, 0.0, 0.0, 0.75);
    const YELLOW: Color = Color::rgba(1.0, 1.0, 0.0, 0.75);
    const FRACTION: f32 = 0.1;
    /// The stripes run at 45°; this is their period measured along the x axis.
    const PERIOD: f32 = 14.0;

    let (outer, outer_bounds) = (scene.current_clip(), scene.current_bounds());
    scene.set_clip(Rect::UNBOUNDED);
    for over in overflows {
        let r = over.rect;
        let band = match over.side {
            Side::Left => Rect::new(r.x, r.y, r.width * FRACTION, r.height),
            Side::Right => Rect::new(
                r.x + r.width * (1.0 - FRACTION),
                r.y,
                r.width * FRACTION,
                r.height,
            ),
            Side::Top => Rect::new(r.x, r.y, r.width, r.height * FRACTION),
            Side::Bottom => Rect::new(
                r.x,
                r.y + r.height * (1.0 - FRACTION),
                r.width,
                r.height * FRACTION,
            ),
        };
        if band.width <= 0.0 || band.height <= 0.0 {
            continue;
        }
        scene.set_clip(band);
        scene.fill_rect(band, BLACK);
        // One parallelogram per stripe, sheared by the band's height so that every one
        // of them crosses it at 45° whatever shape the band is.
        let shear = band.height;
        let mut x = band.x - shear;
        while x < band.x + band.width {
            let stripe = Path::new()
                .move_to(Point::new(x, band.y))
                .line_to(Point::new(x + PERIOD / 2.0, band.y))
                .line_to(Point::new(x + PERIOD / 2.0 + shear, band.y + band.height))
                .line_to(Point::new(x + shear, band.y + band.height))
                .close();
            scene.fill_path(&stripe, YELLOW);
            x += PERIOD;
        }
        // The label is **not** clipped to the band: a vertical one is usually longer than
        // the box is tall, and half a sentence is worse than a sentence written over
        // whatever is beside it. The reference does not clip it either.
        scene.set_clip(Rect::UNBOUNDED);
        scene.set_bounds(Rect::UNBOUNDED);
        paint_overflow_label(scene, band, over);
    }
    scene.set_clip(outer);
    scene.set_bounds(outer_bounds);
}

/// Writes the reference's sentence across a band: which edge overflowed, and by how much.
///
/// The console already says it — but the console is on the developer's machine and the
/// band is on the device, and a photograph of a phone is what half the bug reports in the
/// world are made of. A striped edge says *something* is too big; `RIGHT OVERFLOWED BY 86
/// PIXELS` says which edge, and by enough that you can tell a forgotten padding from a
/// missing wrap without running anything.
///
/// The words are the reference's, exactly, so that searching for them finds the same
/// answers. So are the numbers: 7.5 px, the heaviest weight there is, dark red on an
/// opaque white plate — a label that must stay readable over stripes cannot be subtle —
/// centred on the band's outer edge and turned a quarter turn on the vertical ones.
fn paint_overflow_label(scene: &mut Scene, band: Rect, over: &Overflowing) {
    /// The reference's label metrics.
    const SIZE: f32 = 7.5;
    /// The gap between the label and the outer edge of the band.
    const PAD: f32 = 1.0;
    /// `0xFF900000`.
    const INK: Color = Color::rgb(0.5647059, 0.0, 0.0);

    let side = match over.side {
        Side::Left => "LEFT",
        Side::Right => "RIGHT",
        Side::Top => "TOP",
        Side::Bottom => "BOTTOM",
    };
    let text = format!("{side} OVERFLOWED BY {} PIXELS", format_pixels(over.amount));
    // The reference asks for an 800 weight; the heaviest this framework has is bold.
    let style = TextStyle::new(SIZE).weight(FontWeight::Bold);
    let size = frus_text::measure_styled(&text, SIZE, FontWeight::Bold, false);

    // Where the middle of the label's leading edge goes, before any rotation, and by how
    // much the whole thing then turns about that point.
    let (anchor, angle) = match over.side {
        Side::Left => (
            Point::new(band.x + SIZE + PAD, band.y + band.height / 2.0),
            std::f32::consts::FRAC_PI_2,
        ),
        Side::Right => (
            Point::new(band.x + band.width - SIZE - PAD, band.y + band.height / 2.0),
            -std::f32::consts::FRAC_PI_2,
        ),
        Side::Top => (Point::new(band.x + band.width / 2.0, band.y + PAD), 0.0),
        Side::Bottom => (
            Point::new(band.x + band.width / 2.0, band.y + band.height - SIZE - PAD),
            0.0,
        ),
    };
    if angle == 0.0 {
        let at = Point::new(anchor.x - size.width / 2.0, anchor.y);
        scene.fill_rect(Rect::from_point_size(at, size), Color::WHITE);
        scene.text(at, text, &style.resolved(), INK);
        return;
    }
    // A rotation of a group, not of a glyph: the plate and the sentence turn together and
    // neither has to know it is turning.
    //
    // The group is painted **at the origin** rather than where it lands, because a layer
    // is rendered flat into a window-sized texture before it is composited: a vertical
    // label is written across a box near the right edge, so laid out flat it would run
    // off the texture and lose its last word before the rotation ever brought it back
    // inside. The transform is the one that carries the origin to where the label goes —
    // shift it half its width to the left, turn it, and land it on the anchor.
    let flat = Rect::from_point_size(Point::ZERO, size);
    let matrix = Affine::translation(-size.width / 2.0, 0.0)
        .then(Affine::rotation(angle))
        .then(Affine::translation(anchor.x, anchor.y));
    scene.transformed(LayerTransform::new(matrix), move |scene: &mut Scene| {
        scene.fill_rect(flat, Color::WHITE);
        scene.text(flat.origin(), text, &style.resolved(), INK);
    });
}

/// How the reference writes an overflow: whole pixels past ten, one decimal past one, and
/// three significant figures below that — because the difference between 0.5 px and
/// 0.0001 px is the difference between a layout bug and a rounding error.
fn format_pixels(value: f32) -> String {
    if value > 10.0 {
        format!("{value:.0}")
    } else if value > 1.0 {
        format!("{value:.1}")
    } else {
        // Three significant figures: the first one sits at the first non-zero decimal.
        let leading = if value > 0.0 {
            (-value.abs().log10().floor()) as i32
        } else {
            0
        };
        format!("{value:.*}", (leading + 2).clamp(0, 12) as usize)
    }
}

/// Identity of the `index`-th child: **by key** when the child declares one (stable whatever
/// its position), **positional** otherwise. It must be used everywhere a child identity is
/// derived (render, collection, lookup, animations) so they all stay consistent.
pub(crate) fn child_id<Msg>(parent: WidgetId, index: usize, child: &dyn Widget<Msg>) -> WidgetId {
    match child.key() {
        Some(key) => parent.keyed(key),
        None => parent.child(index),
    }
}

/// A widget's **effective** style for layout: its `style()`, whose size is **replaced by the
/// runtime's interpolated size** when the widget is animated (`Widget::anim_size` +
/// `Container::animated_size`). This is the only place where an animated size enters layout —
/// used **identically** by [`build_layout`] and by the cache fingerprint (`hash_node`), which
/// is what keeps them consistent (the cache stays invalid for as long as the size moves).
pub(crate) fn effective_style<Msg>(
    widget: &dyn Widget<Msg>,
    id: WidgetId,
    runtime: &Runtime,
    theme: &Theme,
) -> frus_layout::Style {
    // The theme's say on size and spacing (milestone 309), before the runtime's
    // animated overrides below — an animation in flight wins over a resting default.
    let mut style = widget.style_themed(theme);
    if widget.anim_size().is_some() {
        if let Some(size) = runtime.anim_size(id) {
            style.width = frus_layout::Dimension::Length(size.width);
            style.height = frus_layout::Dimension::Length(size.height);
        }
    }
    if widget.anim_padding().is_some() {
        if let Some(padding) = runtime.anim_padding(id) {
            style.padding = padding;
        }
    }
    // A share of the parent, growing or shrinking. `Percent` and not `Length`, because
    // the whole point of the quantity is that it does not know what it will come to — and
    // an axis whose factor is unset goes back to following its content rather than to
    // nought, which is what "unset" has always meant here.
    if widget.anim_fractions().is_some() {
        if let Some((width, height)) = runtime.anim_fractions(id) {
            let dim = |factor: Option<f32>| match factor {
                Some(f) => frus_layout::Dimension::Percent(f),
                None => frus_layout::Dimension::Auto,
            };
            style.width = dim(width);
            style.height = dim(height);
        }
    }
    // A dismissed item closing its gap. It collapses along the axis it was **not**
    // swiped along — a row swiped sideways loses its height — which is what makes the
    // neighbours slide up rather than the row narrow to a sliver. Only an explicit
    // length can shrink: an `Auto` box has no number to scale, which is why
    // `Dismissible` asks for a size (see its docs).
    // A sheet's panel, as tall as the retained share of its box. The same `Percent` as a
    // fraction above, for the same reason: the share is the quantity, and the box it is a
    // share of is the layout's to know. Hashed through here as well, so the cache misses
    // on every frame the sheet moves.
    if let Some(spec) = widget.sheet() {
        style.height = frus_layout::Dimension::Percent(runtime.sheet_size(id, spec));
    }
    if let Some(spec) = widget.dismissible() {
        if let Some(factor) = runtime.dismiss_extent_factor(id) {
            let axis = if spec.axis.is_horizontal() {
                &mut style.height
            } else {
                &mut style.width
            };
            if let frus_layout::Dimension::Length(extent) = *axis {
                *axis = frus_layout::Dimension::Length(extent * factor);
            }
        }
    }
    style
}

/// Builds the main layout tree (a scrollable is a **leaf**). `id`/`runtime` are what inject
/// the animated size through [`effective_style`], following the walk's identity scheme
/// (`child_id`) **exactly**.
pub(crate) fn build_layout<'a, Msg>(
    widget: &'a dyn Widget<Msg>,
    id: WidgetId,
    runtime: &'a Runtime,
    theme: &Theme,
    layout: &mut Layout<'a, BaselineData>,
) -> NodeId {
    let (node, fills) = build_layout_scoped(widget, id, runtime, theme, layout, true);
    // A root that wants to fill has no parent to fill: the flex machinery below needs one
    // on each side of the question. A percentage of the room the layout is being computed
    // in is the same answer without a parent, and it degrades to hugging the content when
    // that room is unbounded — a scrollable measuring its content, a natural size.
    if fills.horizontal {
        layout.fill_root(node, true);
    }
    if fills.vertical {
        layout.fill_root(node, false);
    }
    node
}

/// The axes a subtree asks to **fill** rather than shrink-wrap.
///
/// It is not a property of one widget. A column whose row fills the width is itself as
/// wide as the room it was given, because the row inside it took that room — so the
/// request travels up as the layout is built, and each container answers it with the one
/// thing a container can do about it: grow along its own axis, or stretch across it.
#[derive(Clone, Copy, Default)]
pub(crate) struct Fills {
    horizontal: bool,
    vertical: bool,
}

impl Fills {
    /// What a widget asks for on its own account.
    ///
    /// A straight copy since milestone 405: the widget's answer already has a flag per
    /// axis, where it used to be one direction and a container that wanted both had no way
    /// to say so.
    fn own<Msg>(widget: &dyn Widget<Msg>, theme: &Theme) -> Self {
        let asked = widget.fill_axes(theme);
        Fills {
            horizontal: asked.horizontal,
            vertical: asked.vertical,
        }
    }

    fn merge(self, other: Fills) -> Self {
        Fills {
            horizontal: self.horizontal || other.horizontal,
            vertical: self.vertical || other.vertical,
        }
    }

    /// The half of a child's request a container passes on to **its** parent, given
    /// which way the container runs. Along its own axis a container divides the room up
    /// and the request stops there; across it, the container's size *is* the child's, so
    /// the request has to keep going.
    /// Whether one axis is asked for.
    fn wants(self, horizontal: bool) -> bool {
        if horizontal {
            self.horizontal
        } else {
            self.vertical
        }
    }

    /// Drops any axis this box was **given a size on**: it has already been told how big
    /// to be, and a request to fill cannot reach past that answer.
    fn bounded_by(self, style: &frus_layout::Style) -> Self {
        let auto = |d| matches!(d, frus_layout::Dimension::Auto);
        Fills {
            horizontal: self.horizontal && auto(style.width),
            vertical: self.vertical && auto(style.height),
        }
    }

    fn across(self, direction: frus_layout::FlexDirection) -> Self {
        if direction.is_horizontal() {
            Fills {
                horizontal: false,
                vertical: self.vertical,
            }
        } else {
            Fills {
                horizontal: self.horizontal,
                vertical: false,
            }
        }
    }
}

/// A layout leaf's **text baseline**, when it has one: the distance from the top of its
/// box down to the line its letters sit on.
///
/// It rides on the layout tree rather than being asked of the widgets afterwards because
/// only the layout knows where a node ended up, and only the walk that built it knows
/// which branch it took — a scrollable, a stack and a page view are all *leaves* here,
/// with their contents laid out elsewhere, and a second walk guessing at that would be a
/// copy of this one waiting to drift out of step.
pub(crate) type BaselineData = Option<f32>;

/// An owned copy of a theme, **made in a frame of its own**.
///
/// `#[inline(never)]` is the whole point: inlined, the eleven-kilobyte temporary is built
/// in the caller's frame, and the caller here is the recursive walk that pays for its
/// frame once per level of the tree. Behind the call it is built, copied into the
/// allocation, and gone before the walk recurses.
#[inline(never)]
fn owned_theme(theme: &Theme) -> std::rc::Rc<Theme> {
    std::rc::Rc::new(theme.clone())
}

/// The body of [`build_layout`], carrying whether baselines are still being collected.
/// An [`crate::IgnoreBaseline`] turns them off for its subtree — the widgets inside still
/// have baselines, and the point is that nothing above may see them.
fn build_layout_scoped<'a, Msg>(
    widget: &'a dyn Widget<Msg>,
    id: WidgetId,
    runtime: &'a Runtime,
    theme: &Theme,
    layout: &mut Layout<'a, BaselineData>,
    baselines: bool,
) -> (NodeId, Fills) {
    // A component is built into what it stands for before anything is asked of the node,
    // the scope it introduces included — see `Widget::expand`.
    widget.expand(id, runtime, theme);
    // A themed subtree lays out under **its** theme, not the frame's: a theme reaches
    // sizes and spacing (milestone 309), so this has to happen here and not only at paint
    // time. `hash_node`, which fingerprints this same walk for the relayout cache, makes
    // the same swap — the two staying in step is what keeps the cache honest.
    let scoped = scoped_theme(widget, id, runtime, theme);
    let theme = scoped.as_deref().unwrap_or(theme);
    // And a **scoped surface**, the same idea one milestone later: a shell that hands a slot
    // a narrowed description narrows it for everything the slot builds, the deferred build
    // below included. Held for this subtree and put back on the way out.
    let _surface = widget
        .media_override(crate::MediaQuery::of())
        .map(crate::MediaQuery::install);
    // And the **shell**, the third inherited thing (milestone 422): a slot told what shell
    // it stands in composes differently — a bar grows a menu button — so it has to be in
    // force before `build_themed` below, exactly as the surface is.
    let _shell = widget.scaffold_override().map(crate::ScaffoldInfo::install);
    // A subtree that could not be composed until the theme was known (`ThemeBuilder`).
    // It has to happen **before** anything reads `children()`, and under the subtree's
    // own theme, which is why it sits after the swap above rather than at the call site.
    widget.build_in(id, runtime, theme);
    // Everything below an `IgnoreBaseline` keeps its baseline and loses the right to be
    // seen: the flag is narrowed once, here, so no branch below has to remember.
    let baselines = baselines && !widget.ignores_baseline();
    // A leaf's own baseline, or nothing when this subtree is being ignored.
    let own_baseline = if baselines {
        widget.text_baseline(theme)
    } else {
        None
    };
    // `Baseline`: the child is pushed down until **its** baseline lands `target` pixels
    // from the top of this box, and this box grows to contain it. If the child's own
    // baseline is already lower than that, there is nowhere to push it up to and the
    // child is top-aligned instead — the same answer the reference gives.
    if let Some(target) = widget.baseline_target() {
        let mut style = effective_style(widget, id, runtime, theme);
        if let Some(child) = widget.children().first() {
            let child = child.as_ref();
            let cid = child_id(id, 0, child);
            // A child with no baseline of its own is treated as if its baseline were its
            // bottom edge, which is what a box with no text amounts to.
            let child_baseline = natural_baseline(child, cid, runtime, theme)
                .unwrap_or_else(|| natural_size(child, cid, runtime, theme).height);
            style.padding.top += (target - child_baseline).max(0.0);
            let (node, fills) = build_layout_scoped(child, cid, runtime, theme, layout, baselines);
            return (layout.container(style, &[node]), fills);
        }
        return (layout.leaf(style, None), Fills::default());
    }
    // `RotatedBox`: a leaf whose box is the child's **natural** size, with its dimensions
    // **swapped** for an odd quarter turn (the rotation does affect layout). The child itself
    // is laid out separately (at render time).
    if let Some(q) = widget.rotated_quarter_turns() {
        let mut style = effective_style(widget, id, runtime, theme);
        if let Some(child) = widget.children().first() {
            let nat = natural_size(
                child.as_ref(),
                child_id(id, 0, child.as_ref()),
                runtime,
                theme,
            );
            let (w, h) = if q.rem_euclid(4) % 2 != 0 {
                (nat.height, nat.width)
            } else {
                (nat.width, nat.height)
            };
            style.width = frus_layout::Dimension::Length(w);
            style.height = frus_layout::Dimension::Length(h);
        }
        return (layout.leaf(style, own_baseline), Fills::default());
    }
    // `Intrinsic`: one axis is taken from what the content would **like** to be, not from
    // the space on offer. The content is measured once, unconstrained, and the answer is
    // written into this node's style as a length — the same trick `RotatedBox` uses, except
    // that here the child stays inside, laid out normally within the size it asked for.
    if let Some((axis, step)) = widget.intrinsic() {
        let mut style = effective_style(widget, id, runtime, theme);
        if let Some(child) = widget.children().first() {
            let child = child.as_ref();
            let cid = child_id(id, 0, child);
            let nat = natural_size(child, cid, runtime, theme);
            let quantise = |extent: f32| match step {
                Some(step) if step > 0.0 => (extent / step).ceil() * step,
                _ => extent,
            };
            match axis {
                crate::constraints::IntrinsicAxis::Width => {
                    style.width = frus_layout::Dimension::Length(quantise(nat.width));
                }
                crate::constraints::IntrinsicAxis::Height => {
                    style.height = frus_layout::Dimension::Length(quantise(nat.height));
                }
            }
            let (node, fills) = build_layout_scoped(child, cid, runtime, theme, layout, baselines);
            return (layout.container(style, &[node]), fills);
        }
        return (layout.leaf(style, own_baseline), Fills::default());
    }
    // `OverflowBox`: a leaf, because its child is laid out **separately**, to constraints of
    // its own. That separation is the whole feature — a child sharing this node's layout
    // could never be bigger than it.
    if widget.overflow_box().is_some() {
        return (
            layout.leaf(effective_style(widget, id, runtime, theme), own_baseline),
            Fills::default(),
        );
    }
    // A box that **transforms the space on offer**: its child is laid out in a box derived
    // from this one's, in a tree of its own, and this box is then as big as what came back
    // — held to what it was itself offered, which is the reference's
    // `constraints.constrain(child.size)`. `UnconstrainedBox` is this branch with the
    // constraint taken away.
    if let Some(transform) = widget.constraints_transform() {
        let style = effective_style(widget, id, runtime, theme);
        let child = widget.children().first().map(|c| c.as_ref());
        let owned = owned_theme(theme);
        let measure: frus_layout::MeasureFn<'a> = Box::new(move |w, h| {
            let Some(child) = child else {
                return Size::new(0.0, 0.0);
            };
            let (aw, free_x) = transform.width.offered(w);
            let (ah, free_y) = transform.height.offered(h);
            let mut inner: Layout<BaselineData> = Layout::new();
            let node = build_layout(child, child_id(id, 0, child), runtime, &owned, &mut inner);
            // **Handed** every axis that has a number, **asked** about every axis that does
            // not. `compute_scroll` already fills a lone constrained axis, for the reason a
            // scrollable's cross axis needs it; with numbers on both, `compute_filled` is
            // that same rule. Merely constraining them instead would leave a child with no
            // size of its own — a plain container — hugging at nothing, and a box asked how
            // big its child wanted to be would come back empty.
            match (free_x, free_y) {
                (false, false) => inner.compute_filled(node, aw, ah),
                _ => inner.compute_scroll(node, aw, ah, free_x, free_y),
            }
            let size = inner.size_of(node);
            // Held to the offer: a child too big for the room spills, and the box stays the
            // size the room was.
            Size::new(
                size.width.min(w.unwrap_or(f32::INFINITY)),
                size.height.min(h.unwrap_or(f32::INFINITY)),
            )
        });
        return (
            layout.measured_leaf(style, own_baseline, measure),
            Fills::default(),
        );
    }
    // A `LayoutBuilder` **is measured**: it builds its content from the space offered and
    // is then as big as what it built, which is the reference's
    // `size = constraints.constrain(child.size)`. It cannot be a plain leaf, because a
    // leaf answers before it has been asked and there is nothing to answer with until the
    // box is known; and it cannot be a container, because its child does not exist yet.
    //
    // Taffy calls the closure during the computation with the space actually available —
    // the same moment the reference runs its layout callback — and the closure builds the
    // subtree, lays it out in a `Layout` of its own, and hands back the size. An axis the
    // style pins is still the style's: taffy does not ask about a dimension it already
    // knows, so `LayoutBuilder::height(200.0)` behaves exactly as it did.
    if let Some(build) = widget.layout_builder() {
        let style = effective_style(widget, id, runtime, theme);
        // The closure needs an **owned** theme: a themed subtree's theme is a local in
        // this function, so it cannot be borrowed for as long as the closure lives. The
        // runtime and the widget are borrowed, which is the whole reason `Layout` carries
        // a lifetime.
        //
        // This is a clone of eleven kilobytes, and it used to be a silent one — `Theme`
        // was `Copy` until milestone 448, so `*theme` read like a pointer copy and was
        // not. It happens once per `LayoutBuilder`, not once per node.
        //
        // **Behind an `Rc`, and made somewhere else**, because the cost that mattered was
        // not the copy. A `Theme` local here and a closure that captures one are two
        // slots of eleven kilobytes in *this* function's frame, and a frame is charged to
        // every level of the walk whether or not the branch is taken: 24 736 bytes a
        // level, which overflowed a Windows main thread's megabyte at about forty. The
        // `Rc` makes the capture a pointer, and `owned_theme` keeps the copy in a frame
        // that pops before the recursion goes any deeper.
        let owned = owned_theme(theme);
        let cid = id.child(0);
        let measure: frus_layout::MeasureFn<'a> = Box::new(move |w, h| {
            // What taffy offers. `None` is an *intrinsic* question — how big would you
            // be with no limit, or with none at all — and there is no honest answer to
            // it here: finding out means running the application's callback
            // speculatively. The reference refuses these outright (`computeDryLayout`
            // asserts); we build at the offered numbers, substituting zero for what is
            // not offered, and leave the unoffered axis free in the nested computation
            // so the content's own size comes back.
            let offered = Size::new(w.unwrap_or(0.0), h.unwrap_or(0.0));
            let child = build(offered);
            let mut inner: Layout<BaselineData> = Layout::new();
            let node = build_layout(child.as_ref(), cid, runtime, &owned, &mut inner);
            // The content is **handed** the offered box, not asked what it would like:
            // it was built from that box. An axis that was not offered is the one being
            // asked about, and stays free so the content's own size comes back.
            match (w, h) {
                (Some(w), Some(h)) => inner.compute_filled(node, w, h),
                _ => inner.compute_scroll(
                    node,
                    offered.width,
                    offered.height,
                    w.is_none(),
                    h.is_none(),
                ),
            }
            inner.size_of(node)
        });
        return (
            layout.measured_leaf(style, own_baseline, measure),
            Fills::own(widget, theme),
        );
    }
    // **A viewport is sized from its content on the axis it does not scroll.**
    //
    // A scrollable area declares a size on the axis it scrolls — that is what a viewport
    // is, a window shorter than what is behind it. On the *other* axis there is nothing to
    // choose: the content is as tall as it is, and the viewport is that tall. Until
    // milestone 485 a horizontal strip took the 200 px that belongs to a vertical one, so a
    // scrollable tab bar 48 px tall claimed 200 and pushed its panel a hundred and fifty
    // pixels into empty space (#65).
    //
    // It cannot be answered by the widget alone, and that is the whole reason this lives
    // here. A scroll host lays its content out **against** the viewport on the axis that
    // does not scroll — the content of a horizontal strip is given the viewport's height —
    // so a viewport that said `Auto` there would hand the content nothing and come back
    // nothing tall, the circle closing at zero. Breaking it takes a measurement, at the one
    // moment the runtime and the theme are both to hand.
    if let Some(content) = widget.scroll_content() {
        let style = effective_style(widget, id, runtime, theme);
        let axis = widget.scroll_axis();
        // Only an axis that **neither scrolls nor was given a size**. A caller's number is
        // a caller's number, and an axis that scrolls has already answered.
        let hug_x = !axis.free_x() && matches!(style.width, frus_layout::Dimension::Auto);
        let hug_y = !axis.free_y() && matches!(style.height, frus_layout::Dimension::Auto);
        if hug_x || hug_y {
            let owned = owned_theme(theme);
            let cid = child_id(id, 0, content);
            let measure: frus_layout::MeasureFn<'a> = Box::new(move |w, h| {
                let mut inner: Layout<BaselineData> = Layout::new();
                let node = build_layout(content, cid, runtime, &owned, &mut inner);
                // The content is unconstrained on every axis that scrolls — that is what
                // scrolling means — and on the one being measured. What is left is an axis
                // with a real number on it, and the content is held to it.
                inner.compute_scroll(
                    node,
                    w.unwrap_or(0.0),
                    h.unwrap_or(0.0),
                    hug_x || axis.free_x() || w.is_none(),
                    hug_y || axis.free_y() || h.is_none(),
                );
                let content = inner.size_of(node);
                let pad = widget.scroll_padding();
                // **Only the hugged axis is answered.** On the axis that scrolls, a
                // viewport is precisely *not* as big as its content — answering with the
                // content's size there would make a flexible viewport ask for the whole
                // length of what is behind it as its basis, and a column holding one would
                // overflow by however much there was to scroll. Nought is what a leaf
                // answered before this branch existed, and it is still the right answer.
                Size::new(
                    match hug_x {
                        true => content.width + pad.left + pad.right,
                        false => 0.0,
                    },
                    match hug_y {
                        true => content.height + pad.top + pad.bottom,
                        false => 0.0,
                    },
                )
            });
            return (
                layout.measured_leaf(style, own_baseline, measure),
                Fills::own(widget, theme),
            );
        }
    }

    // Scrollables, interactive viewports, fitters (`FittedBox`), navigators, virtualised
    // lists and stacks: their content is laid out separately (independent layers / screens /
    // items, or a child laid out at its natural size).
    if widget.scroll_content().is_some()
        || widget.interactive().is_some()
        || widget.fitted().is_some()
        || widget.navigator().is_some()
        || widget.virtual_list(Size::ZERO).is_some()
        || widget.page_view().is_some()
        || widget.stack()
    {
        // Nothing bubbles out of these: what is inside is laid out somewhere else, to
        // constraints of its own, and cannot have an opinion about this box.
        return (
            layout.leaf(effective_style(widget, id, runtime, theme), own_baseline),
            Fills::own(widget, theme),
        );
    }
    // A portal only lays out its anchor (child 0); the overlay is deferred.
    if widget.overlay().is_some() {
        let anchor_w = widget.children()[0].as_ref();
        let (anchor, fills) = build_layout_scoped(
            anchor_w,
            child_id(id, 0, anchor_w),
            runtime,
            theme,
            layout,
            baselines,
        );
        return (
            layout.container(effective_style(widget, id, runtime, theme), &[anchor]),
            fills,
        );
    }
    let children = widget.children();
    if children.is_empty() {
        // A leaf measured under constraints (a paragraph that wraps…): taffy calls the
        // closure during the computation.
        if let Some(measure) = widget.measure(theme) {
            return (
                layout.measured_leaf(
                    effective_style(widget, id, runtime, theme),
                    own_baseline,
                    measure,
                ),
                Fills::own(widget, theme),
            );
        }
        (
            layout.leaf(effective_style(widget, id, runtime, theme), own_baseline),
            Fills::own(widget, theme),
        )
    } else {
        let style = effective_style(widget, id, runtime, theme);
        let built: Vec<(NodeId, Fills)> = children
            .iter()
            .enumerate()
            .map(|(i, child)| {
                build_layout_scoped(
                    child.as_ref(),
                    child_id(id, i, child.as_ref()),
                    runtime,
                    theme,
                    layout,
                    baselines,
                )
            })
            .collect();
        let child_ids: Vec<NodeId> = built.iter().map(|(node, _)| *node).collect();
        // `MainAxisSize::Max`: a run that fills the room its parent leaves it. Only the
        // parent knows what that means — grow along an axis it shares, stretch across
        // one it does not — which is why the child asks rather than saying.
        //
        // The request is the child's **and its subtree's**: a column whose row fills the
        // width is itself as wide as the room it was given.
        let alone = children.len() == 1;
        for (node, fills) in &built {
            for horizontal in [true, false] {
                if !fills.wants(horizontal) {
                    continue;
                }
                let parallel = horizontal == style.flex_direction.is_horizontal();
                // Along an axis the parent runs too, the reference leaves the main axis
                // **unbounded** and `Max` quietly degrades to `Min`: there is no maximum
                // to take. The exception is a parent with a single child — a padding, an
                // alignment, a decorated box — which passes its own constraints straight
                // down, and there the run does fill.
                if parallel && !alone {
                    continue;
                }
                layout.fill_parent(*node, horizontal, parallel);
            }
        }
        // A **lone** child gives way; several do not.
        //
        // The reference hands an inflexible child of a row or a column an unbounded main
        // axis: it is never squeezed, and a line that does not fit overflows and says so.
        // That is the default here now, because a framework that quietly crushes a button
        // instead of reporting a layout that does not fit is one whose bugs are invisible
        // — milestone 333 spent three milestones on exactly that crushed button.
        //
        // But a box with one child is not dividing a line up: it is handing its own
        // constraints down, and the reference bounds a lone child by them. The same
        // exception the fill request and the floor below both make, for the same reason.
        if alone {
            for node in &child_ids {
                layout.allow_shrink(*node);
            }
        }
        // A grid's tiles are all the same shape. The ratio is the *container's*, since a
        // tile cannot know how wide its column came out, and the reference says the same:
        // a grid's delegate hands every child a tight box derived from the track, square
        // unless the application asked for another ratio.
        if let Some(ratio) = widget.tile_shape() {
            for node in &child_ids {
                layout.set_tile_shape(*node, ratio);
            }
        }
        // A child that refuses to be squeezed along the row. Only a row of **several**
        // children may say so. Across a column the same floor would refuse a width the
        // column was handing it, which is how a paragraph is told how wide to be; and a
        // box with a single child — a padding, an alignment, a decorated box — is handing
        // one down rather than dividing a line up, whichever way it nominally runs.
        if style.flex_direction.is_horizontal() && !alone {
            for (child, node) in children.iter().zip(&child_ids) {
                if let Some(floor) = child.main_axis_floor(theme) {
                    layout.set_min_width(*node, floor);
                }
            }
        }
        // **Baseline** cross-alignment: the children are pushed down until their
        // baselines meet, which is the only alignment that makes two runs of different
        // sizes read as one line rather than as one row.
        //
        // It is resolved here rather than by taffy, which cannot: taffy asks a leaf for
        // a size and a leaf can only answer with one. The measurement a baseline needs
        // is the font's, so the answer has to come from up here, where the widgets are.
        //
        // The **natural** baseline is the right one to measure even though the children
        // will be laid out at some other width: the first line of a piece of text sits
        // in the same place however narrow the box gets, since narrowing it adds lines
        // below rather than moving the first one.
        if style.align == frus_layout::Align::Baseline && style.flex_direction.is_horizontal() {
            let own: Vec<Option<f32>> = children
                .iter()
                .enumerate()
                .map(|(i, child)| {
                    natural_baseline(
                        child.as_ref(),
                        child_id(id, i, child.as_ref()),
                        runtime,
                        theme,
                    )
                })
                .collect();
            if let Some(deepest) = own.iter().flatten().copied().reduce(f32::max) {
                for (node, b) in child_ids.iter().zip(&own) {
                    // A child with no baseline keeps its place: it is a box, and a box
                    // has nothing to line up.
                    if let Some(b) = b {
                        layout.add_margin_top(*node, deepest - b);
                    }
                }
            }
        }
        // What this container passes on to **its** parent. Across its own axis the
        // container's size is its child's, so the request keeps going; along it the
        // container divides the room up and the request stops. A container with a single
        // child divides nothing, and passes the whole request on.
        let mut fills = Fills::own(widget, theme);
        for (_, child) in &built {
            fills = fills.merge(if alone {
                *child
            } else {
                child.across(style.flex_direction)
            });
        }
        (
            layout.container(style, &child_ids),
            fills.bounded_by(&style),
        )
    }
}

/// The distance from the top of `widget`'s **natural** box to the first baseline inside
/// it, or `None` when there is no text in there to have one.
///
/// It lays the subtree out on its own, exactly as [`natural_size`] does, and takes the
/// first baseline the layout collected. First in *layout* order, which is the order a
/// reader would find it in — and it is the leaves that carry them, so an intervening
/// padding or alignment is already counted in the rectangle it comes with.
pub(crate) fn natural_baseline<Msg>(
    widget: &dyn Widget<Msg>,
    id: WidgetId,
    runtime: &Runtime,
    theme: &Theme,
) -> Option<f32> {
    let mut layout = Layout::new();
    let node = build_layout(widget, id, runtime, theme, &mut layout);
    layout.compute_scroll(node, 0.0, 0.0, true, true);
    let rects = layout.absolute_rects(node);
    let top = rects.first()?.0.y;
    rects
        .iter()
        .find_map(|(rect, data)| data.copied().flatten().map(|b| rect.y + b - top))
}

/// **Natural** (intrinsic) size of a subtree: laid out under free axes (`MaxContent`), with
/// no imposed constraint. Used by `RotatedBox` (the dimensions to swap) and — at render time
/// — by `FittedBox` (the fit factor).
pub(crate) fn natural_size<Msg>(
    widget: &dyn Widget<Msg>,
    id: WidgetId,
    runtime: &Runtime,
    theme: &Theme,
) -> Size {
    let mut layout = Layout::new();
    let node = build_layout(widget, id, runtime, theme, &mut layout);
    layout.compute_scroll(node, 0.0, 0.0, true, true);
    layout
        .absolute_rects(node)
        .first()
        .map(|(r, _)| Size::new(r.width, r.height))
        .unwrap_or(Size::new(0.0, 0.0))
}

/// A deferred overlay: `(content, id, the anchor's bounds, placement, dismissal,
/// progress 0..=1, whether it takes the pointer, the scrim's colour, the theme it was
/// declared under)`. The progress animates the appearance — a drawer sliding in, a
/// scrim fading — and is `1.0` for overlays that are not animated.
///
/// The **theme travels with it** because an overlay is painted long after the walk has
/// left the node that declared it: a dialog opened from inside a [`crate::Themed`]
/// subtree would otherwise come out in the root's theme, which is the surprise the
/// reference had to grow a whole mechanism to avoid. The scrim's colour travels for the
/// same reason — by the time it is painted, the widget that asked for it is long
/// behind.
type Overlay<'a, Msg> = (
    &'a dyn Widget<Msg>,
    WidgetId,
    Rect,
    Placement,
    Option<Msg>,
    f32,
    bool,
    Option<frus_core::Color>,
    std::rc::Rc<Theme>,
);

struct Builder<'a, Msg> {
    scene: Scene,
    hits: Vec<Hit<Msg>>,
    long_presses: Vec<Hit<Msg>>,
    dismisses: Vec<Msg>,
    focusables: Vec<Focusable>,
    /// Start of the topmost modal overlay's focus scope.
    focus_scope_start: Option<usize>,
    /// Set while inside an `ExcludeFocus`: nothing in here registers a focus stop.
    focus_excluded: bool,
    /// The identity of the nearest enclosing backdrop group — the key a backdrop
    /// asking to be shared takes. Pushed and popped by the walk, like the focus flags.
    backdrop_group: Option<u64>,
    /// Set while inside an `ExcludeFocusTraversal`: stops register, Tab passes them by.
    focus_skipped: bool,
    /// The traversal order in force, from the nearest enclosing `FocusTraversalOrder`.
    focus_order: Option<f32>,
    /// The nearest enclosing `FocusTraversalGroup`, within which an order is resolved.
    focus_group: Option<WidgetId>,
    /// The nearest enclosing [`crate::AutofillGroup`]: the form a field is part of.
    autofill_group: Option<WidgetId>,
    /// Shortcut and action scopes closed so far this frame.
    scopes: Vec<Scope<Msg>>,
    /// Keystroke listeners, with the focus stops they cover.
    #[allow(clippy::type_complexity)]
    listeners: Vec<(
        std::ops::Range<usize>,
        std::rc::Rc<dyn Fn(KeyStroke) -> Option<Msg>>,
    )>,
    scrollables: Vec<Scrollable>,
    scrollbars: Vec<Scrollbar>,
    draggables: Vec<(WidgetId, Rect)>,
    drag_sources: Vec<DragSource>,
    drop_zones: Vec<DropZone>,
    inks: Vec<(WidgetId, Rect)>,
    reorderables: Vec<(WidgetId, Rect)>,
    interactives: Vec<(WidgetId, Rect)>,
    /// Deferred overlays: (content, id, the anchor's bounds, placement, dismissal, progress
    /// `0..=1`). The progress animates the appearance (a drawer sliding in, a scrim fading);
    /// it is `1.0` for overlays that are not animated.
    overlays: Vec<Overlay<'a, Msg>>,
    /// A widget is asking for a continuous, time-driven animation.
    wants_animation: bool,
    available: Size,
    runtime: &'a Runtime,
    /// The theme **in force at this point of the walk** — the root's, unless a
    /// [`crate::Themed`] ancestor replaced it. Owned rather than borrowed because a
    /// subtree's theme is derived from the one above it and outlives nothing.
    ///
    /// Owned **behind an `Rc`**: a `Theme` is eleven kilobytes, and this field is swapped
    /// on the way into a themed subtree and swapped back on the way out. By value that is
    /// two copies of eleven kilobytes standing in the walk's frame — one being moved in,
    /// one held across the recursion waiting to be put back — on every level of the tree,
    /// taken or not. Behind a pointer the swap is a pointer's width, and the walk's frame
    /// went from 28 144 bytes a level to 5 264.
    theme: std::rc::Rc<Theme>,
    /// The inspector's collection (`Some` only while it is on): one node per painted widget,
    /// in paint order.
    inspector: Option<Vec<crate::inspector::InspectorNode>>,
    /// Current depth of the walk (for the dump's indentation and the palette of the
    /// inspector's outlines).
    depth: usize,
    /// The [`crate::RefreshIndicator`] area currently being walked, if any: every scrollable
    /// registered under it records it, so the shell knows where to send the movement
    /// its physics refuses. Saved and restored around the subtree, so sibling areas do
    /// not inherit one another's.
    refresh_host: Option<WidgetId>,
    /// The scroll region currently being walked, if any: the nearest one enclosing
    /// whatever the walk is looking at. Focus stops record it so the shell can reveal
    /// them, and nested regions record one another. Saved and restored around the
    /// subtree, like [`Builder::refresh_host`].
    scroll_host: Option<WidgetId>,
    /// Which screen of a route transition the walk is inside (`0` = leaving, `1` =
    /// entering); `None` outside one. Recorded on each hero so the two sides of a
    /// flight are told apart rather than guessed from paint order.
    hero_screen: Option<u8>,
    /// The shared elements seen so far, each with the widget that declared it (needed
    /// to lift its subtree's painting) and the transition screen it belongs to.
    heroes: Vec<(HeroSpot, &'a dyn Widget<Msg>)>,
    /// The frame's refresh areas, in paint order.
    refreshes: Vec<Refreshable>,
    /// The frame's dismissible items, in paint order.
    dismissables: Vec<Dismissable>,
    /// The frame's sheets, in the order their subtrees finished walking.
    sheets: Vec<crate::sheet::SheetArea>,
    /// Accessibility nodes collected during the walk (paint order).
    semantics: Vec<(WidgetId, Rect, frus_core::SemanticsProperties)>,
    /// The parts of the screen saying what the system bars over them should look like,
    /// with their boxes, in paint order.
    system_ui: Vec<(Rect, crate::SystemUiOverlayStyle)>,
    /// Boxes whose children did not fit, screen-positioned, from every sub-root walked
    /// this frame.
    overflows: std::cell::RefCell<Vec<Overflowing>>,
    /// The same, still in their sub-root's own coordinates, waiting for the walk to reach
    /// that sub-root and say where on screen it ended up.
    pending_overflows: std::cell::RefCell<std::collections::HashMap<WidgetId, Vec<Overflowing>>>,
}

impl<'a, Msg: Clone + 'static> Builder<'a, Msg> {
    /// A layout root's rects, through the relayout cache retained in the runtime (it only
    /// recomputes through taffy when the style/structure/constraints have changed). A brief
    /// mutable borrow: the `Vec` returned is owned.
    ///
    /// In **RTL**, taffy computes in LTR (canonical, and cached), then each rect is
    /// **mirrored** about the root's width (the 1st rect): the rows reverse, the alignment
    /// and the margins flip — without touching the widgets. The text itself is drawn
    /// normally inside its moved box (the *internal* bidi is handled by cosmic-text).
    fn cached_rects(&self, key: WidgetId, root: &dyn Widget<Msg>, c: Constraints) -> Vec<Rect> {
        let (mut rects, overflows) =
            self.runtime
                .layout_cache
                .borrow_mut()
                .rects(key, root, self.runtime, &self.theme, c);
        self.mirror(&mut rects);
        self.record_overflows(key, &rects, overflows);
        rects
    }

    /// Files this sub-root's overflowing boxes under its identity, mirrored with
    /// everything else in RTL — where an edge changes name as well as position, since the
    /// layout is the mirror image and "ran past the right" becomes "ran past the left".
    ///
    /// They wait here rather than going straight out because a sub-root's rectangles are
    /// in its **own** coordinates: a scrollable's content, a page, a list item and a
    /// stack's layer each get their own taffy pass, and where that pass lands on screen is
    /// only known when the walk reaches it. [`Self::claim_overflows`] is the other half.
    /// Records a child that came out **bigger than the box holding it**, one entry per
    /// edge it ran past — the same yellow and black band a row too full of children gets,
    /// from a box that laid its child out itself and so was never measured against it.
    ///
    /// The rectangle is already on the screen, this being the walk rather than a sub-root's
    /// own pass, so it goes straight out rather than through [`Self::record_overflows`].
    fn report_spill(&self, own: Rect, child: Rect) {
        // Per edge, from where the child actually landed: a centred child that is too wide
        // runs past **both** sides, and a band on one of them would be a half-truth.
        let over = [
            (Side::Left, own.x - child.x),
            (Side::Top, own.y - child.y),
            (Side::Right, (child.x + child.width) - (own.x + own.width)),
            (
                Side::Bottom,
                (child.y + child.height) - (own.y + own.height),
            ),
        ];
        let spills: Vec<Overflowing> = over
            .into_iter()
            .filter(|(_, amount)| *amount > 0.5)
            .map(|(side, amount)| Overflowing {
                rect: own,
                side,
                amount,
            })
            .collect();
        self.overflows.borrow_mut().extend(spills);
    }

    fn record_overflows(&self, key: WidgetId, mirrored: &[Rect], overflows: Vec<Overflowing>) {
        if overflows.is_empty() {
            return;
        }
        let rtl = self.rtl();
        let root = mirrored.first().copied();
        let list: Vec<Overflowing> = overflows
            .into_iter()
            .map(|mut o| {
                if let (true, Some(root)) = (rtl, root) {
                    o.rect.x = root.x + (root.width - (o.rect.x - root.x) - o.rect.width);
                    o.side = match o.side {
                        Side::Left => Side::Right,
                        Side::Right => Side::Left,
                        other => other,
                    };
                }
                o
            })
            .collect();
        self.pending_overflows.borrow_mut().insert(key, list);
    }

    /// The walk has reached sub-root `id` and knows where it sits: its overflowing boxes
    /// become screen rectangles.
    fn claim_overflows(&self, id: WidgetId, translation: (f32, f32)) {
        let taken = self.pending_overflows.borrow_mut().remove(&id);
        if let Some(list) = taken {
            self.overflows
                .borrow_mut()
                .extend(list.into_iter().map(|o| Overflowing {
                    rect: o.rect.translate(translation.0, translation.1),
                    ..o
                }));
        }
    }

    /// The layout direction **in force here** — read from the ambient theme rather than
    /// from a field set once at the root, so a [`crate::Themed`] subtree carries its own.
    ///
    /// What that reaches is everything decided during the walk: which edge a drawer
    /// slides from, which way an anchored overlay opens, the sign of a rotation, the
    /// mirroring of any **layout root** inside the subtree (a scrollable, an overlay).
    /// What it does not reach is ordinary flow inside the subtree: the frame's rects are
    /// computed once at the root and mirrored there as a whole, so a direction set part
    /// way down does not reverse the rows around it. Setting the direction on the theme
    /// handed to `build_ui` is still the way to flip an application.
    fn rtl(&self) -> bool {
        self.theme.direction.is_rtl()
    }

    /// Mirrors a root's rects horizontally (RTL). The first rect is the root itself: its
    /// width is the axis of symmetry.
    fn mirror(&self, rects: &mut [Rect]) {
        if !self.rtl() {
            return;
        }
        let Some(root) = rects.first().copied() else {
            return;
        };
        // The axis: the rects are relative to the root (origin at root.x).
        for r in rects.iter_mut() {
            r.x = root.x + (root.width - (r.x - root.x) - r.width);
        }
    }

    /// 64-bit fingerprint of everything painting a boundary subtree reads **without**
    /// rebuilding the `view`: each descendant's `Status` (in walk order) and the subtree's
    /// absolute rects. An unchanged fingerprint + generation ⇒ a bit-for-bit identical paint.
    /// The time is excluded (a cacheable boundary holds no `continuous` widget).
    fn boundary_fingerprint(
        &self,
        widget: &dyn Widget<Msg>,
        id: WidgetId,
        translation: (f32, f32),
        sub: &[Rect],
    ) -> u64 {
        let mut h = std::collections::hash_map::DefaultHasher::new();
        self.rtl().hash(&mut h);
        translation.0.to_bits().hash(&mut h);
        translation.1.to_bits().hash(&mut h);
        for r in sub {
            r.x.to_bits().hash(&mut h);
            r.y.to_bits().hash(&mut h);
            r.width.to_bits().hash(&mut h);
            r.height.to_bits().hash(&mut h);
        }
        self.hash_statuses(widget, id, &mut h);
        h.finish()
    }

    /// Adds `widget`'s `Status` to `h`, then its children's, recursively — following the
    /// walk's identity scheme (`child_id`) **exactly**, so it lines up with the order in which
    /// `walk_node` paints them.
    fn hash_statuses<H: Hasher>(&self, widget: &dyn Widget<Msg>, id: WidgetId, h: &mut H) {
        hash_status(&self.full_status(widget, id), h);
        // Live ink is part of what the boundary paints, and it moves every frame while a
        // splash is alive. Without it here the cached primitives would be replayed and
        // the ripple would stand still — and once the ink dries the hash goes back to
        // what it was, so the boundary starts hitting again.
        if let Some(ripples) = self.runtime.ink.get(&id) {
            ripples.hash_state(h);
        }
        for (i, child) in widget.children().iter().enumerate() {
            self.hash_statuses(child.as_ref(), child_id(id, i, child.as_ref()), h);
        }
    }

    /// Current lengths of the builder's collections: the lower bound of the slices to capture
    /// for a boundary (see [`capture_since`](Self::capture_since)).
    fn snapshot(&self) -> Snapshot {
        Snapshot {
            scene: self.scene.primitives().len(),
            hits: self.hits.len(),
            long_presses: self.long_presses.len(),
            dismisses: self.dismisses.len(),
            focusables: self.focusables.len(),
            scrollables: self.scrollables.len(),
            draggables: self.draggables.len(),
            drag_sources: self.drag_sources.len(),
            drop_zones: self.drop_zones.len(),
            inks: self.inks.len(),
            semantics: self.semantics.len(),
            system_ui: self.system_ui.len(),
            overlays: self.overlays.len(),
            focus_scope_start: self.focus_scope_start,
        }
    }

    /// Captures the output produced since `snap` (the collections' *tail slices*) into a
    /// [`BoundaryData`]. Returns `None` — hence **not cacheable** — when the subtree pushed an
    /// overlay or touched the modal focus scope (global state that cannot be captured here).
    fn capture_since(&self, snap: &Snapshot) -> Option<BoundaryData<Msg>> {
        if self.overlays.len() != snap.overlays || self.focus_scope_start != snap.focus_scope_start
        {
            return None;
        }
        Some(BoundaryData {
            prims: self.scene.primitives()[snap.scene..].to_vec(),
            hits: self.hits[snap.hits..].to_vec(),
            long_presses: self.long_presses[snap.long_presses..].to_vec(),
            dismisses: self.dismisses[snap.dismisses..].to_vec(),
            focusables: self.focusables[snap.focusables..].to_vec(),
            scrollables: self.scrollables[snap.scrollables..].to_vec(),
            draggables: self.draggables[snap.draggables..].to_vec(),
            drag_sources: self.drag_sources[snap.drag_sources..].to_vec(),
            drop_zones: self.drop_zones[snap.drop_zones..].to_vec(),
            inks: self.inks[snap.inks..].to_vec(),
            semantics: self.semantics[snap.semantics..].to_vec(),
            system_ui: self.system_ui[snap.system_ui..].to_vec(),
        })
    }

    /// Replays a boundary from the cache: primitives already formed (clip/owner baked in) and
    /// interaction maps, appended as is.
    fn splice_boundary(&mut self, data: BoundaryData<Msg>) {
        for p in data.prims {
            self.scene.push_primitive(p);
        }
        self.hits.extend(data.hits);
        self.long_presses.extend(data.long_presses);
        self.dismisses.extend(data.dismisses);
        self.focusables.extend(data.focusables);
        self.scrollables.extend(data.scrollables);
        self.draggables.extend(data.draggables);
        self.drag_sources.extend(data.drag_sources);
        self.drop_zones.extend(data.drop_zones);
        self.inks.extend(data.inks);
        self.semantics.extend(data.semantics);
        self.system_ui.extend(data.system_ui);
    }

    /// Lengths of every registry a [`ModalBarrier`] can withhold from, taken before its subtree
    /// is walked.
    fn barrier_base(&self) -> BarrierBase {
        BarrierBase {
            scene: self.scene.primitives().len(),
            hits: self.hits.len(),
            long_presses: self.long_presses.len(),
            focusables: self.focusables.len(),
            scrollables: self.scrollables.len(),
            scrollbars: self.scrollbars.len(),
            draggables: self.draggables.len(),
            drag_sources: self.drag_sources.len(),
            drop_zones: self.drop_zones.len(),
            inks: self.inks.len(),
            reorderables: self.reorderables.len(),
            interactives: self.interactives.len(),
            semantics: self.semantics.len(),
        }
    }

    /// Drops what the subtree added since `base`, according to `barrier`, and — for an
    /// absorbing barrier — puts a message-less hit target in its place so that input stops
    /// at the barrier instead of reaching whatever is painted behind it.
    /// Resolves the **shared elements** of a route transition: every tag that appears
    /// on both screens flies from where it was to where it is going.
    ///
    /// Called once, after both screens have been drawn, because that is the first
    /// moment both boxes are known. `hero_base` and `scene_base` mark where those two
    /// screens started.
    ///
    /// What flies is the **destination**'s own painting, mapped onto the box it is
    /// travelling through. Both originals are taken out of the frame: a thing that is
    /// flying is not also sitting at either end, and leaving them in is the difference
    /// between a shared element and three copies of one.
    fn fly_heroes(&mut self, hero_base: usize, scene_base: usize, progress: f32) {
        let spots: Vec<(HeroSpot, &'a dyn Widget<Msg>)> = self.heroes.split_off(hero_base);
        if spots.len() < 2 {
            return;
        }
        // The pairs: one tag, one hero on each side. A tag on one side only has nothing
        // to fly to, and a tag used more than once per side is ambiguous — both are
        // left alone rather than guessed at.
        let mut flights: Vec<(Rect, Rect, &'a dyn Widget<Msg>, WidgetId, WidgetId)> = Vec::new();
        for (from, _) in spots.iter().filter(|(s, _)| s.screen == 0) {
            let mut matching = spots
                .iter()
                .filter(|(s, _)| s.screen == 1 && s.tag == from.tag);
            let Some((to, widget)) = matching.next() else {
                continue;
            };
            if matching.next().is_some() {
                continue;
            }
            flights.push((from.rect, to.rect, *widget, from.id, to.id));
        }
        if flights.is_empty() {
            return;
        }

        // Everything the two screens painted, so the originals can be taken out and the
        // travelling copies laid on top.
        let painted = self.scene.split_off(scene_base);
        let mut hidden: std::collections::HashSet<u64> = std::collections::HashSet::new();
        for (_, _, widget, from_id, to_id) in &flights {
            for id in subtree_ids(*widget, *to_id) {
                hidden.insert(id.as_u64());
            }
            // The source's subtree is the *other* screen's widget, whose identity is
            // rooted at `from_id`; the same relative shape, so the ids follow.
            for id in subtree_ids(*widget, *from_id) {
                hidden.insert(id.as_u64());
            }
        }
        for primitive in &painted {
            if !hidden.contains(&primitive.owner()) {
                self.scene.push_primitive(primitive.clone());
            }
        }

        self.scene.set_clip(Rect::UNBOUNDED);
        for (from, to, _, _, to_id) in &flights {
            let travelling = lerp_rect(*from, *to, progress);
            if to.width <= 0.0 || to.height <= 0.0 {
                continue;
            }
            let (sx, sy) = (travelling.width / to.width, travelling.height / to.height);
            let pivot = Point::new(to.x, to.y);
            let owners: std::collections::HashSet<u64> = subtree_ids(
                flights
                    .iter()
                    .find(|(_, _, _, _, id)| id == to_id)
                    .map(|(_, _, w, _, _)| *w)
                    .expect("the flight just matched"),
                *to_id,
            )
            .iter()
            .map(|id| id.as_u64())
            .collect();
            for primitive in painted.iter().filter(|p| owners.contains(&p.owner())) {
                let flown = primitive
                    .scaled_about_xy(pivot, sx, sy)
                    .translated(travelling.x - to.x, travelling.y - to.y)
                    .with_clip(Rect::UNBOUNDED);
                self.scene.push_primitive(flown);
            }
        }
    }

    /// Reconciles what a [`crate::Semantics`] wrapper's subtree announced with what the
    /// wrapper says about it.
    ///
    /// The wrapper's own answers win, and the subtree's show through wherever it said
    /// nothing — a container that knows a child is a *heading* rarely knows what the words
    /// are, and dropping them would replace a spoken title with silence.
    ///
    /// The merged node goes in **where the subtree's first one was**, not at the end. The
    /// accessibility tree is flat and its order is reading order, so a wrapper appended
    /// after its own contents would be read after them.
    fn apply_description(
        &mut self,
        described: crate::semantics::Description,
        base: usize,
        id: WidgetId,
        own: Rect,
    ) {
        let mut props = described.props;
        // Merging swallows every child's own entry, so **something** has to answer for
        // this node when it is activated — the wrapper itself never does (see
        // `Semantics::on_click`'s own reasoning: an annotation that swallowed a click
        // would put a hit target over the widget it describes). Found testing #18 in a
        // real browser and real screen reader: a `Checkbox::new(..).on_toggle(..)`
        // merged with its row's caption read correctly and did **nothing** on
        // activation, on every platform, because the merged entry carried the row's own
        // id, which nothing routes a click through. When exactly one child in the
        // swallowed subtree was clickable, its id is who a click or a keyboard
        // activation has to reach, so the merged entry keys on that id instead — the
        // wrapper's id is kept only when there is no such child, or more than one and
        // "the one that gets clicked" has no single answer.
        let mut operable = None;
        if described.merging {
            let mut clickable_count = 0;
            for (child_id, _, child) in self.semantics.drain(base..).collect::<Vec<_>>() {
                if child.clickable {
                    clickable_count += 1;
                    operable = Some(child_id);
                }
                props = props.over(&child);
            }
            if clickable_count != 1 {
                operable = None;
            }
        }
        let id = operable.unwrap_or(id);
        if props.is_meaningful() && own.width > 0.0 && own.height > 0.0 {
            self.semantics.insert(base, (id, own, props));
        }
    }

    fn apply_barrier(
        &mut self,
        barrier: ModalBarrier,
        base: &BarrierBase,
        id: WidgetId,
        own: Rect,
    ) {
        if barrier.pointer {
            self.hits.truncate(base.hits);
            self.long_presses.truncate(base.long_presses);
            self.focusables.truncate(base.focusables);
            self.scrollables.truncate(base.scrollables);
            self.scrollbars.truncate(base.scrollbars);
            self.draggables.truncate(base.draggables);
            self.drag_sources.truncate(base.drag_sources);
            self.drop_zones.truncate(base.drop_zones);
            self.inks.truncate(base.inks);
            self.reorderables.truncate(base.reorderables);
            self.interactives.truncate(base.interactives);
            // The modal focus scope is an index **into** `focusables`. A barrier that cut
            // away the focusable it pointed at would leave it dangling past the end, and
            // every later slice of the pool would then be empty — no focusable at all,
            // rather than the ones the barrier meant to spare.
            if let Some(start) = self.focus_scope_start {
                self.focus_scope_start = Some(start.min(self.focusables.len()));
            }
        }
        if barrier.absorb && own.width > 0.0 && own.height > 0.0 {
            self.hits.push(Hit {
                id,
                rect: own,
                msg: None,
                xform: None,
            });
        }
        if barrier.paint {
            // The clip is baked into each primitive when it is pushed, so dropping the tail
            // leaves nothing for the next sibling to repair.
            let _hidden = self.scene.split_off(base.scene);
        }
        if barrier.semantics {
            self.semantics.truncate(base.semantics);
        }
    }

    /// Lower bounds of the interaction registries **before** a transformed composited subtree.
    fn xform_base(&self) -> XformBase {
        XformBase {
            hits: self.hits.len(),
            long_presses: self.long_presses.len(),
            focusables: self.focusables.len(),
            scrollables: self.scrollables.len(),
            draggables: self.draggables.len(),
            drag_sources: self.drag_sources.len(),
            drop_zones: self.drop_zones.len(),
            inks: self.inks.len(),
            reorderables: self.reorderables.len(),
            semantics: self.semantics.len(),
        }
    }

    /// Applies the layer transform `matrix` to the registry entries **added since** `base`:
    /// the test point of click / long-press targets goes through `M⁻¹` (without overwriting an
    /// inner transform already set); and when `matrix` preserves axis alignment
    /// (scale/translation, no rotation), the **rects** of focus / scrolling / dragging /
    /// **reordering** / accessibility are mapped exactly by `M` (otherwise they are left as
    /// they are — the click stays correct through `M⁻¹`). The **shared factor** of the two
    /// transformed-composition sites (`walk`'s boundary and `emit_transformed_child`): one
    /// place to keep up to date, which forgets no registry (milestone 250 had forgotten
    /// `reorderables` in exactly one of the two).
    fn transform_interaction_registries(&mut self, base: &XformBase, matrix: Affine) {
        let inverse = matrix.inverse();
        for h in &mut self.hits[base.hits..] {
            h.xform.get_or_insert(inverse);
        }
        for h in &mut self.long_presses[base.long_presses..] {
            h.xform.get_or_insert(inverse);
        }
        if matrix.is_axis_aligned() {
            for f in &mut self.focusables[base.focusables..] {
                f.rect = matrix.apply_rect(f.rect);
                f.bounds = matrix.apply_rect(f.bounds);
            }
            for area in &mut self.scrollables[base.scrollables..] {
                area.viewport = matrix.apply_rect(area.viewport);
            }
            for source in &mut self.drag_sources[base.drag_sources..] {
                source.rect = matrix.apply_rect(source.rect);
            }
            for zone in &mut self.drop_zones[base.drop_zones..] {
                zone.rect = matrix.apply_rect(zone.rect);
            }
            for (_, r) in &mut self.inks[base.inks..] {
                *r = matrix.apply_rect(*r);
            }
            for (_, r) in &mut self.draggables[base.draggables..] {
                *r = matrix.apply_rect(*r);
            }
            for (_, r) in &mut self.reorderables[base.reorderables..] {
                *r = matrix.apply_rect(*r);
            }
            for (_, r, _) in &mut self.semantics[base.semantics..] {
                *r = matrix.apply_rect(*r);
            }
        }
    }

    /// Entry point for walking a node. When the node is a cacheable **repaint boundary**, it
    /// tries to replay its subtree from the paint cache; otherwise (or on a *miss*) it
    /// delegates to the full walk [`walk_node`](Self::walk_node), capturing its output for the
    /// next frame. Every recursion goes through here → nested boundaries get cached too.
    /// The focus flags a subtree carries — exclusion, Tab-skipping, an order, a group —
    /// are **subtree-scoped**, so they are pushed here and popped on the way out rather
    /// than asked of each widget at the moment it registers. The body of the walk has
    /// early returns in a dozen branches; wrapping it is the only way to be sure the
    /// scope is closed on every one of them.
    fn walk(
        &mut self,
        widget: &'a dyn Widget<Msg>,
        id: WidgetId,
        translation: (f32, f32),
        clip: Rect,
        rects: &[Rect],
        index: &mut usize,
    ) {
        let outer = (
            self.focus_excluded,
            self.focus_skipped,
            self.focus_order,
            self.focus_group,
        );
        if !widget.descendants_focusable() {
            self.focus_excluded = true;
        }
        if widget.focus_skip_traversal() {
            self.focus_skipped = true;
        }
        if let Some(order) = widget.focus_order() {
            self.focus_order = Some(order);
        }
        if widget.focus_group() {
            self.focus_group = Some(id);
        }
        // The backdrop group a subtree sits in, scoped the same way and for the same
        // reason. Its own identity is the key: stable across frames, and unique
        // without anything having to hand one out.
        let outer_group = self.backdrop_group;
        if widget.backdrop_group() {
            self.backdrop_group = Some(id.as_u64());
        }
        // The form a field belongs to, scoped the same way (milestone 512).
        let outer_form = self.autofill_group;
        if widget.autofill_group() {
            self.autofill_group = Some(id);
        }
        // The focus stops this subtree contains start here; the walk is depth-first, so
        // they are contiguous and the range closes below.
        let stops_before = self.focusables.len();
        self.walk_scoped(widget, id, translation, clip, rects, index);
        (
            self.focus_excluded,
            self.focus_skipped,
            self.focus_order,
            self.focus_group,
        ) = outer;
        self.backdrop_group = outer_group;
        self.autofill_group = outer_form;
        self.close_scope(widget, stops_before);
    }

    /// Files whatever tables this subtree carried, with the focus stops it turned out to
    /// contain. Recorded **on the way out**, because the range is not known on the way in;
    /// so `scopes` ends up innermost-first among any that overlap, which is the order the
    /// resolution wants and the reason it is not sorted afterwards.
    fn close_scope(&mut self, widget: &'a dyn Widget<Msg>, stops_before: usize) {
        let range = stops_before..self.focusables.len();
        if let Some(on_key) = widget.on_keystroke() {
            self.listeners.push((range.clone(), on_key));
        }
        let (strokes, callbacks) = (widget.shortcut_bindings(), widget.shortcut_callbacks());
        let (actions, listeners) = (widget.action_bindings(), widget.action_listeners());
        if strokes.is_empty() && callbacks.is_empty() && actions.is_empty() && listeners.is_empty()
        {
            return;
        }
        self.scopes.push(Scope {
            strokes: strokes.to_vec(),
            callbacks: callbacks.to_vec(),
            actions: actions.to_vec(),
            listeners: listeners.to_vec(),
            range,
        });
    }

    fn walk_scoped(
        &mut self,
        widget: &'a dyn Widget<Msg>,
        id: WidgetId,
        translation: (f32, f32),
        clip: Rect,
        rects: &[Rect],
        index: &mut usize,
    ) {
        self.claim_overflows(id, translation);
        // A **sheet's panel**: the subtree is walked as usual, and every scroll area it
        // registered is recorded against the sheet, so the shell knows which lists share a
        // finger with it. By range, since a subtree's registrations are contiguous —
        // a replayed boundary splices its own in the same place.
        if let Some(spec) = widget.sheet() {
            let panel = rects[*index].translate(translation.0, translation.1);
            let first = self.scrollables.len();
            self.walk_node(widget, id, translation, clip, rects, index);
            let areas = self.scrollables[first..]
                .iter()
                .map(|area| area.id)
                .collect();
            // What the share is a share of. At nought there is nothing to divide by, so the
            // height last measured stands in: a finger that lowered the panel to nothing
            // may still be holding it.
            let size = self.runtime.sheet_size(id, spec);
            let available = if size > 0.0 {
                panel.height / size
            } else {
                self.runtime
                    .sheets
                    .get(&id)
                    .map_or(0.0, |sheet| sheet.available())
            };
            self.sheets.push(crate::sheet::SheetArea {
                id,
                panel,
                available,
                spec: spec.clone(),
                areas,
            });
            return;
        }

        // A **refresh area**: the subtree is walked with this widget named as the host, so
        // every scrollable inside records where to send the movement its physics refuses at
        // the top edge. The indicator is then painted **over** the subtree — painting it in
        // the widget's own `paint` would put it under the list it belongs to.
        if let Some(spec) = widget.refresh() {
            let viewport = rects[*index]
                .translate(translation.0, translation.1)
                .intersect(clip);
            let outer = self.refresh_host.replace(id);
            self.walk_node(widget, id, translation, clip, rects, index);
            self.refresh_host = outer;

            let area = Refreshable { id, viewport, spec };
            if let Some(pull) = self.runtime.refresh.get(&id) {
                crate::refresh::paint_refresh(&mut self.scene, &area, pull, &self.theme, clip);
                // A pull that is settling, spinning or fading away drives itself, so the
                // frame after this one has to happen.
                self.wants_animation = true;
            }
            self.refreshes.push(area);
            return;
        }

        // A **barrier** (`IgnorePointer`, `AbsorbPointer`, a hidden `Visibility`,
        // `ExcludeSemantics`): the subtree is walked exactly as usual, and then whatever it
        // added to the withheld registries is dropped again.
        //
        // Removing afterwards rather than skipping the walk is what makes it exact. A widget
        // deep inside registers its click target, focus stop, scrollable area or accessibility
        // node without knowing that something above is holding the subtree out of the frame;
        // truncating at the barrier catches every one of them, including those added by
        // widgets written after this code. It also keeps the walk's rect indexing untouched,
        // which a skipped subtree would break.
        // A **description** (`Semantics`): something above states what the subtree *is*,
        // which the subtree cannot state for itself. Same shape as the barrier below and for
        // the same reason — walk first, reconcile after, so a widget deep inside annotates
        // itself without knowing anything is speaking for it.
        if let Some(described) = widget.describes() {
            let base = self.semantics.len();
            let own = rects[*index]
                .translate(translation.0, translation.1)
                .intersect(clip);
            self.walk_node(widget, id, translation, clip, rects, index);
            self.apply_description(described, base, id, own);
            return;
        }

        if let Some(barrier) = widget.barrier().filter(|b| !b.is_none()) {
            let base = self.barrier_base();
            // The barrier's own box, before `walk_node` advances the index past it.
            let own = rects[*index]
                .translate(translation.0, translation.1)
                .intersect(clip);
            self.walk_node(widget, id, translation, clip, rects, index);
            self.apply_barrier(barrier, &base, id, own);
            return;
        }

        // An opacity group: the subtree is painted normally, then its range of primitives is
        // **drained** into a composited layer at the group's opacity — so overlaps do not
        // double-blend. The animated opacity is the value the runtime tweened; otherwise the
        // fixed target. Opaque (≈1): no layer at all (zero cost).
        if let Some(target) = widget.opacity_group() {
            let opacity = self.runtime.value_or(id, target).clamp(0.0, 1.0);
            if opacity < 0.999 {
                let start = self.scene.primitives().len();
                self.walk_node(widget, id, translation, clip, rects, index);
                let group = self.scene.split_off(start);
                self.scene.push_primitive(Primitive::Layer {
                    primitives: group,
                    opacity,
                    clip,
                    clip_shape: ClipShape::Rect,
                    transform: None,
                    filter: LayerFilter::NONE,
                    owner: id.as_u64(),
                });
                return;
            }
            // Fully opaque: an ordinary render (no pointless layer).
        }

        // A **pixel effect** over the subtree (`ColorFiltered`, `ImageFiltered`,
        // `ShaderMask`): painted normally, then drained into a composited layer that
        // carries the effect. The renderer applies it when it composites — the image
        // filter as a pre-pass over the layer texture, the colour filter and the mask
        // in the compositing fragment.
        //
        // The box is passed in because a mask is written in fractions of the box it
        // covers, and this is the first point at which that box is a place on screen.
        if let Some(filter) = widget.layer_filter(crate::widget::FilterContext {
            box_rect: rects[*index].translate(translation.0, translation.1),
            backdrop_group: self.backdrop_group,
        }) {
            // The layer keeps the **ambient** clip rather than its own box: an image
            // filter reaches past the pixels it came from, and cutting it at the box
            // would shave the edge off every blur.
            let start = self.scene.primitives().len();
            self.walk_node(widget, id, translation, clip, rects, index);
            let group = self.scene.split_off(start);
            let (group, filter, clip_box) = fold_filter(group, filter, clip);
            self.scene.push_primitive(Primitive::Layer {
                primitives: group,
                opacity: 1.0,
                clip: clip_box,
                clip_shape: ClipShape::Rect,
                transform: None,
                filter,
                owner: id.as_u64(),
            });
            return;
        }

        // **Shape** clipping: the subtree is painted normally, bounded to the widget's box,
        // then its primitives are **drained** into a composited layer whose shape (rounded
        // corners / ellipse) modulates the alpha — the overflowing corners are erased at
        // compositing time. The shape's box is the layer's clip rect. Two sources: `ClipPath`
        // (an arbitrary path, taking priority) or `ClipRRect`/`ClipOval` (an analytic shape).
        // The local path is **offset to the box's screen position**.
        if widget.clip_path().is_some() || widget.clip_shape().is_some() {
            let box_rect = rects[*index].translate(translation.0, translation.1);
            let shape = widget
                .clip_path()
                .map(|p| ClipShape::Path(p.translated(box_rect.x, box_rect.y)))
                .or_else(|| widget.clip_shape())
                .expect("clip_path or clip_shape is Some");
            let clip_box = clip.intersect(box_rect);
            let start = self.scene.primitives().len();
            self.walk_node(widget, id, translation, clip_box, rects, index);
            let group = self.scene.split_off(start);
            // A clip around a filter is **one** layer, not two. It matters most for a
            // backdrop: the reference's own advice is to wrap one in a clip to give it
            // its shape, and a backdrop pushed a level down would be filtering the
            // clip's contents rather than the frame.
            let (group, filter, clip_box) = fold_filter(group, LayerFilter::NONE, clip_box);
            self.scene.push_primitive(Primitive::Layer {
                primitives: group,
                opacity: 1.0,
                clip: clip_box,
                clip_shape: shape,
                transform: None,
                filter,
                owner: id.as_u64(),
            });
            return;
        }

        // Composable paint transforms (`Transform`: scale and/or rotation; translation goes
        // through the child offset instead). Scale and rotation are melted into **a single
        // affine matrix** `M`, the subtree is painted **flat**, then wrapped in a composited
        // layer transformed by `M`. The hit-test applies `M⁻¹` to the point. The translation,
        // applied upstream through `child_offset`, is the innermost one.
        //
        // A transform that was told to **animate** hands over its numbers, and only its
        // numbers: the pivots stay the widget's, because a pivot is a choice of origin
        // rather than a quantity and interpolating it would slide the subtree across the
        // screen with nothing describing it having changed. Where the runtime has never
        // heard of this widget the static value stands, which is the same rule every
        // other animated property follows on mount.
        let moving = self.runtime.anim_transform(id);
        let scale = widget
            .transform_scale()
            .map(|(sx, sy, pivot)| {
                moving.map_or((sx, sy, pivot), |m| (m.scale_x, m.scale_y, pivot))
            })
            .filter(|(sx, sy, _)| (sx - 1.0).abs() > 1e-4 || (sy - 1.0).abs() > 1e-4);
        let rotate = widget
            .transform_rotate()
            .map(|(angle, pivot)| moving.map_or((angle, pivot), |m| (m.rotation, pivot)))
            .filter(|(a, _)| a.abs() > 1e-4);
        if scale.is_some() || rotate.is_some() {
            // The pivots are taken on the **child's** box (the next node in prefix order): it
            // is the child that gets transformed, and its box hugs the content even when the
            // Transform's own box is stretched by the parent.
            let basis = rects.get(*index + 1).copied().unwrap_or(rects[*index]);
            let box_rect = basis.translate(translation.0, translation.1);
            let pivot_of = |align: frus_core::Alignment| {
                Point::new(
                    box_rect.x + box_rect.width * align.fraction_x(),
                    box_rect.y + box_rect.height * align.fraction_y(),
                )
            };
            // The composition: scale (about its own pivot) **then** rotation (about its own).
            // In RTL the world is mirrored → the rotation direction is inverted.
            let mut matrix = Affine::IDENTITY;
            if let Some((sx, sy, pivot_align)) = scale {
                matrix = matrix.then(Affine::scale(sx, sy).about(pivot_of(pivot_align)));
            }
            if let Some((angle, pivot_align)) = rotate {
                let angle = if self.rtl() { -angle } else { angle };
                matrix = matrix.then(Affine::rotation(angle).about(pivot_of(pivot_align)));
            }

            let p0 = self.scene.primitives().len();
            let base = self.xform_base();
            self.walk_node(widget, id, translation, clip, rects, index);
            // Wraps the range of primitives — painted flat — in a layer transformed by `M`
            // (scale/rotation applied at compositing time).
            let group = self.scene.split_off(p0);
            self.scene.push_primitive(Primitive::Layer {
                primitives: group,
                opacity: 1.0,
                clip,
                clip_shape: ClipShape::Rect,
                transform: Some(LayerTransform::new(matrix)),
                filter: LayerFilter::NONE,
                owner: id.as_u64(),
            });
            // Counter-transforms the hit-test and maps the subtree's interaction rects.
            self.transform_interaction_registries(&base, matrix);
            return;
        }

        // The inspector wants a full walk (it collects every node); caching only happens
        // outside inspection.
        if self.inspector.is_none() && widget.repaint_boundary() {
            if let Some(count) = plain_subtree_len(widget) {
                let start = *index;
                let sub = &rects[start..start + count];
                let fp = self.boundary_fingerprint(widget, id, translation, sub);

                // Hit: the same generation (config) + the same fingerprint (state+geometry)
                // ⇒ the paint would be identical. The output is cloned and replayed.
                let hit = {
                    let mut pc = self.runtime.paint_cache.borrow_mut();
                    pc.get(id, fp).and_then(|(rc, any)| {
                        any.downcast_ref::<BoundaryData<Msg>>()
                            .map(|d| (rc, d.clone()))
                    })
                };
                if let Some((rc, data)) = hit {
                    self.runtime.paint_cache.borrow_mut().note_hit();
                    self.splice_boundary(data);
                    *index += rc;
                    return;
                }

                // Miss: paints normally, capturing the subtree's output (primitives +
                // interaction maps) for the next frame.
                let snap = self.snapshot();
                self.walk_node(widget, id, translation, clip, rects, index);
                self.runtime.paint_cache.borrow_mut().note_miss();
                if let Some(data) = self.capture_since(&snap) {
                    self.runtime
                        .paint_cache
                        .borrow_mut()
                        .put(id, fp, count, Box::new(data));
                }
                return;
            }
        }
        self.walk_node(widget, id, translation, clip, rects, index);
    }

    /// Paints a child **flat** (laid out separately, at `translation`, with its own rects)
    /// then wraps it in a composited layer transformed by `matrix` and clipped to `clip`. The
    /// hit-test counter-transforms the point (`M⁻¹`); when `matrix` stays axis-aligned
    /// (scale/translation), the focus / scroll / drag / accessibility bounds are transformed
    /// too. The shared factor of `InteractiveViewer`, `RotatedBox` and `FittedBox`.
    // The child, its identity, and the four things that place it. Splitting them would
    // only mean passing the same values in two hops.
    #[allow(clippy::too_many_arguments)]
    fn emit_transformed_child(
        &mut self,
        child: &'a dyn Widget<Msg>,
        cid: WidgetId,
        translation: (f32, f32),
        clip: Rect,
        child_rects: &[Rect],
        matrix: Affine,
        owner: WidgetId,
    ) {
        let p0 = self.scene.primitives().len();
        let base = self.xform_base();
        let mut child_index = 0;
        self.walk(child, cid, translation, clip, child_rects, &mut child_index);
        let group = self.scene.split_off(p0);
        self.scene.push_primitive(Primitive::Layer {
            primitives: group,
            opacity: 1.0,
            clip,
            clip_shape: ClipShape::Rect,
            transform: Some(LayerTransform::new(matrix)),
            filter: LayerFilter::NONE,
            owner: owner.as_u64(),
        });
        self.transform_interaction_registries(&base, matrix);
    }

    /// Paints one node, **under the theme it asks for**. A [`crate::Themed`] replaces the
    /// ambient theme for itself and everything below it; it is put back on the way out, so
    /// the sibling that follows is untouched. Everything the subtree reads — its paint,
    /// its ink, its focus ring, its layout through `cached_rects`, and any overlay it
    /// defers — goes through this field, which is what makes one swap enough.
    fn walk_node(
        &mut self,
        widget: &'a dyn Widget<Msg>,
        id: WidgetId,
        translation: (f32, f32),
        clip: Rect,
        rects: &[Rect],
        index: &mut usize,
    ) {
        // The box this node is about to be given, read **before** the walk consumes the
        // index: a decoration painted over the children needs it once they are done, and
        // by then `*index` has moved past the whole subtree.
        let over = rects
            .get(*index)
            .copied()
            .map(|r| r.translate(translation.0, translation.1));
        let outer = scoped_theme(widget, id, self.runtime, &self.theme)
            .map(|theme| std::mem::replace(&mut self.theme, std::rc::Rc::from(theme)));
        // The scoped surface, held for this subtree exactly as the layout walk holds it —
        // a widget that paints from `MediaQuery::of()` must see the same description it
        // was measured against, or the two disagree by whatever the scope removed.
        let _surface = widget
            .media_override(crate::MediaQuery::of())
            .map(crate::MediaQuery::install);
        let _shell = widget.scaffold_override().map(crate::ScaffoldInfo::install);
        self.walk_node_themed(widget, id, translation, clip, rects, index);
        // Over its own children: the reference's `foregroundDecoration`, and the only
        // point in the walk where a widget paints after its subtree. Still under this
        // node's own theme, since it is this node's decoration.
        if let Some(bounds) = over {
            if let Some(decoration) = widget.foreground(&self.theme) {
                let status = self.full_status(widget, id);
                self.scene.set_clip(clip);
                self.scene.set_owner(id.as_u64());
                self.scene.set_bounds(bounds);
                decoration.paint_into(&mut self.scene, bounds, status.opacity);
                self.scene.set_clip(clip);
            }
        }
        if let Some(outer) = outer {
            self.theme = outer;
        }
    }

    /// The walk proper, with the theme already in place — split out so that no early
    /// return inside it can skip putting the outer theme back.
    fn walk_node_themed(
        &mut self,
        widget: &'a dyn Widget<Msg>,
        id: WidgetId,
        translation: (f32, f32),
        clip: Rect,
        rects: &[Rect],
        index: &mut usize,
    ) {
        let rect = rects[*index];
        *index += 1;
        let draw_rect = rect.translate(translation.0, translation.1);
        self.inspect_enter(widget, id, draw_rect);

        let status = self.full_status(widget, id);
        if widget.continuous() {
            self.wants_animation = true;
        }

        self.scene.set_clip(clip);
        self.scene.set_owner(id.as_u64());
        // The box this widget was given. Text primitives record it: a line of text
        // says only where it starts, and the renderer has to know what it covers to
        // order it against anything else (milestone 295).
        self.scene.set_bounds(draw_rect);
        widget.paint(draw_rect, status, &self.theme, &mut self.scene);
        // A widget may have tightened the clip (TextField, for one): it is restored here.
        self.scene.set_clip(clip);
        // A part of the screen saying what the system bars over it should look like, kept
        // with its box: the shell asks which ones lie under each bar (#46).
        if let Some(style) = widget.system_ui_style() {
            self.system_ui.push((draw_rect, style));
        }
        // The ink a tap left on this surface: over the surface's own paint, under its
        // children — where a material surface puts it. The box is recorded too, so the
        // shell can start the next splash at the right place, in the right size.
        if let Some(style) = widget.ink(&self.theme) {
            self.inks.push((id, draw_rect));
            if let Some(ripples) = self.runtime.ink.get(&id) {
                ripples.paint(
                    id.as_u64(),
                    draw_rect,
                    style.radius,
                    style.color,
                    &mut self.scene,
                );
                self.scene.set_clip(clip);
            }
        }
        self.draw_focus_ring(draw_rect, &status, widget);

        // A shared element is recorded **whether or not it is on screen**: half way
        // through a transition the one being left behind has usually slid off the edge,
        // and its box is exactly what the flight starts from. Every other registry here
        // is about what a pointer can reach, which is why they are inside the guard.
        if let Some(screen) = self.hero_screen {
            if let Some(tag) = widget.hero_tag() {
                self.heroes.push((
                    HeroSpot {
                        tag,
                        screen,
                        id,
                        rect: draw_rect,
                    },
                    widget,
                ));
            }
        }

        let visible = draw_rect.intersect(clip);
        // A focus stop clipped entirely away by a **scroll** is still a focus stop.
        // Tab has to reach the field below the fold — the shell brings it into view
        // when it lands there — and registering only what the eye can see is how a long
        // form came to have half its fields unreachable from the keyboard. Clipped away
        // by anything else it is gone: nothing could reveal it, so focus would land
        // where the eye cannot follow.
        //
        // Only the focus registry does this. A click still needs the visible box, or a
        // tap on empty space would land on something scrolled out of sight.
        if widget.focusable()
            && !self.focus_excluded
            && (self.scroll_host.is_some() || (visible.width > 0.0 && visible.height > 0.0))
        {
            self.focusables.push(Focusable {
                id,
                rect: visible,
                bounds: draw_rect,
                form: self.autofill_group,
                scroll: self.scroll_host,
                skip: self.focus_skipped || widget.focus_skip_traversal(),
                order: widget.focus_order().or(self.focus_order),
                group: self.focus_group,
            });
        }
        if visible.width > 0.0 && visible.height > 0.0 {
            // A press that lands on a **surface** and on nothing inside it stops there.
            // Registered before the children, so anything inside still wins on the way
            // back out — see [`Widget::opaque`].
            if widget.opaque() {
                self.hits.push(Hit {
                    id,
                    rect: visible,
                    msg: None,
                    xform: None,
                });
            }
            if let Some(msg) = widget.on_click() {
                self.hits.push(Hit {
                    id,
                    rect: visible,
                    msg: Some(msg),
                    xform: None,
                });
            }
            if let Some(msg) = widget.on_long_press() {
                self.long_presses.push(Hit {
                    id,
                    rect: visible,
                    msg: Some(msg),
                    xform: None,
                });
            }
            if widget.draggable() {
                self.draggables.push((id, visible));
            }
            if let Some(payload) = widget.drag_payload() {
                self.drag_sources.push(DragSource {
                    id,
                    rect: visible,
                    payload,
                });
            }
            if widget.drop_zone() {
                self.drop_zones.push(DropZone { id, rect: visible });
            }
            if widget.reorder_index().is_some() {
                self.reorderables.push((id, visible));
            }
            // The accessibility tree: nodes that carry meaning (a role or a label).
            if let Some(sem) = widget.semantics().filter(|s| s.is_meaningful()) {
                self.semantics.push((id, visible, sem));
            }
            // A **multi-line** field whose content overflows: a scrollable region (wheel and
            // inertia through the generic machinery; the shell follows the caret) plus a
            // draggable scrollbar (mouse and touch).
            if let Some(vp) = widget.text_viewport(draw_rect) {
                if let Some((content_h, visible_h, _, _)) = widget.text_metrics(draw_rect.width, 0)
                {
                    let max_y = (content_h - visible_h).max(0.0);
                    if max_y > 0.0 {
                        self.scrollables.push(Scrollable {
                            id,
                            viewport: vp,
                            max_x: 0.0,
                            max_y,
                            physics: widget.scroll_physics(),
                            refresh: self.refresh_host,
                            page: None,
                            reverse_x: false,
                            reverse_y: false,
                            host: self.scroll_host,
                            keep_visible: None,
                        });
                        let offset_y = self
                            .runtime
                            .scroll
                            .get(&id)
                            .map(|s| s.1)
                            .unwrap_or(0.0)
                            .clamp(0.0, max_y);
                        self.add_scrollbar(
                            id,
                            vp,
                            Bar {
                                vertical: true,
                                offset: offset_y,
                                max: max_y,
                                reverse: false,
                                asked: widget.scrollbars(),
                                visible: widget.thumb_visibility(),
                            },
                        );
                    }
                }
            }
        }

        if let Some((progress, forward)) = widget.navigator() {
            let bounds = draw_rect;
            let children = widget.children();
            let w = bounds.width;
            // **The pages stop at the navigator's edge.** A screen sliding in comes from
            // outside the box, and one sliding out goes outside it; before milestone 398
            // the only thing stopping them was the window, so a navigator that was not the
            // whole window painted its pages over its siblings — and even a full-window
            // one spent the frame drawing a screen nobody could see. The reference clips
            // by default (`Clip.hardEdge`) for the same reason.
            let clip = if widget.navigator_clips() {
                clip.intersect(bounds)
            } else {
                clip
            };
            // The pages under the one on show are kept in the tree and stay out of the picture.
            let hidden = widget.navigator_retained().min(children.len());
            let shown = &children[hidden..];
            if shown.len() >= 2 {
                // A transition: two offset screens. The screen "behind" (a negative offset)
                // moves less (parallax) → the sense of depth.
                let dir = if forward { 1.0 } else { -1.0 };
                let raw = [-progress * w * dir, (1.0 - progress) * w * dir];
                let off = [
                    if raw[0] < 0.0 {
                        raw[0] * NAV_PARALLAX
                    } else {
                        raw[0]
                    },
                    if raw[1] < 0.0 {
                        raw[1] * NAV_PARALLAX
                    } else {
                        raw[1]
                    },
                ];
                // Depth order: the one offset furthest left (the back one) goes first.
                let (back, front) = if off[0] <= off[1] { (0, 1) } else { (1, 0) };
                // Where the shared elements of this transition start, in both the
                // registry and the scene: everything after this point belongs to the
                // two screens, and the flight is resolved from it once both are drawn.
                let hero_base = self.heroes.len();
                let scene_base = self.scene.primitives().len();
                let outer_screen = self.hero_screen.replace(back as u8);
                // A screen being left keeps its floating layers to itself.
                // `process_overlays` draws every overlay above the **whole window**, after
                // both screens, so a menu left open on the departing screen is painted on
                // top of the screen that replaced it — opaque, and anchored to a bar the
                // window no longer shows. A device found it; the parallax is why it is not
                // self-correcting, since the outgoing screen travels only 30 % of the width
                // and its anchor never actually leaves.
                //
                // `Navigator::from` inserts the screen being left at index 0, so
                // `children[1]` is always the destination — on a push, on a pop, and under
                // a back gesture alike. Whatever the other one defers is dropped.
                let overlay_base = self.overlays.len();
                self.render_screen(
                    shown[back].as_ref(),
                    child_id(id, hidden + back, shown[back].as_ref()),
                    bounds,
                    off[back],
                    clip,
                );
                if back != 1 {
                    self.overlays.truncate(overlay_base);
                }
                // Darkens the screen behind in proportion to how far it is covered.
                let coverage = (off[back].abs() / (w * NAV_PARALLAX)).min(1.0);
                if coverage > 0.0 {
                    let scrim =
                        Rect::new(bounds.x + off[back], bounds.y, bounds.width, bounds.height);
                    self.scene.set_owner(0);
                    self.scene.set_clip(clip);
                    self.scene
                        .fill_rect(scrim, self.theme.scheme.scrim.with_alpha(0.22 * coverage));
                }
                self.hero_screen = Some(front as u8);
                let overlay_base = self.overlays.len();
                self.render_screen(
                    shown[front].as_ref(),
                    child_id(id, hidden + front, shown[front].as_ref()),
                    bounds,
                    off[front],
                    clip,
                );
                if front != 1 {
                    self.overlays.truncate(overlay_base);
                }
                self.hero_screen = outer_screen;
                self.fly_heroes(hero_base, scene_base, progress);
            } else if let Some(screen) = shown.first() {
                self.render_screen(
                    screen.as_ref(),
                    child_id(id, hidden, screen.as_ref()),
                    bounds,
                    0.0,
                    clip,
                );
            }
        } else if widget.interactive().is_some() {
            // An **interactive** viewport (`InteractiveViewer`): the child fills the viewport
            // at scale 1, then the retained transform (scale + translation, from the shell's
            // gestures) is applied to it through **a single layer** carrying both the matrix
            // `M` and the clip to the viewport.
            let viewport = draw_rect;
            let content_clip = clip.intersect(viewport);
            self.interactives.push((id, viewport));
            if let Some(content) = widget.children().first() {
                let content = content.as_ref();
                let cid = child_id(id, 0, content);
                let content_rects = self.cached_rects(
                    cid,
                    content,
                    Constraints::definite(Size::new(viewport.width, viewport.height)),
                );
                let matrix = self
                    .runtime
                    .interactive
                    .get(&id)
                    .copied()
                    .unwrap_or_default()
                    .matrix();
                self.emit_transformed_child(
                    content,
                    cid,
                    (viewport.x, viewport.y),
                    content_clip,
                    &content_rects,
                    matrix,
                    id,
                );
            }
        } else if let Some(q) = widget.rotated_quarter_turns() {
            // `RotatedBox`: the child, measured at its **natural** size, is centred in the box
            // (with the dimensions swapped for an odd quarter, see `build_layout`) then rotated
            // about the centre. The rotation, applied at compositing time, does not stay
            // axis-aligned for an odd quarter (the focus bounds are left as they are — the
            // click itself stays correct through `M⁻¹`).
            let box_rect = draw_rect;
            if let Some(child) = widget.children().first() {
                let child = child.as_ref();
                let cid = child_id(id, 0, child);
                let child_rects =
                    self.cached_rects(cid, child, Constraints::scroll(0.0, 0.0, true, true));
                let nat = child_rects
                    .first()
                    .copied()
                    .unwrap_or(Rect::new(0.0, 0.0, 0.0, 0.0));
                let center = Point::new(
                    box_rect.x + box_rect.width / 2.0,
                    box_rect.y + box_rect.height / 2.0,
                );
                let translation = (center.x - nat.width / 2.0, center.y - nat.height / 2.0);
                let angle = q.rem_euclid(4) as f32 * std::f32::consts::FRAC_PI_2;
                let angle = if self.rtl() { -angle } else { angle };
                let matrix = Affine::rotation(angle).about(center);
                self.emit_transformed_child(
                    child,
                    cid,
                    translation,
                    clip,
                    &child_rects,
                    matrix,
                    id,
                );
            }
        } else if let Some(fit) = widget.fitted() {
            // `FittedBox`: the child, measured at its **natural** size, is scaled according to
            // the `BoxFit` (uniformly, except for `Fill`), centred and clipped to the box. The
            // scale stays axis-aligned → the focus bounds follow.
            let box_rect = draw_rect;
            let content_clip = clip.intersect(box_rect);
            if let Some(child) = widget.children().first() {
                let child = child.as_ref();
                let cid = child_id(id, 0, child);
                let child_rects =
                    self.cached_rects(cid, child, Constraints::scroll(0.0, 0.0, true, true));
                let nat = child_rects
                    .first()
                    .copied()
                    .unwrap_or(Rect::new(0.0, 0.0, 0.0, 0.0));
                let (sx, sy) = fit.scale(
                    Size::new(nat.width, nat.height),
                    Size::new(box_rect.width, box_rect.height),
                );
                let center = Point::new(
                    box_rect.x + box_rect.width / 2.0,
                    box_rect.y + box_rect.height / 2.0,
                );
                let translation = (center.x - nat.width / 2.0, center.y - nat.height / 2.0);
                let matrix = Affine::scale(sx, sy).about(center);
                self.emit_transformed_child(
                    child,
                    cid,
                    translation,
                    content_clip,
                    &child_rects,
                    matrix,
                    id,
                );
            }
        } else if let Some(content) = widget.scroll_content() {
            let axis = widget.scroll_axis();
            let viewport = draw_rect;
            let content_clip = clip.intersect(viewport);
            // `reverse` applies to the axis this scrolls along; a two-dimensional scroll
            // takes it on the vertical, which is the one a reversed view is ever about.
            let reverse = if widget.scroll_reverse() {
                (axis.free_x() && !axis.free_y(), axis.free_y())
            } else {
                (false, false)
            };

            // The padding is **inside** the viewport and scrolls with the content:
            // room at the end of a feed is reachable by scrolling to it, room taken out
            // of the window would sit there for ever. The reference's `SliverPadding`.
            let pad = widget.scroll_padding();
            let content_rects = self.cached_rects(
                child_id(id, 0, content),
                content,
                Constraints::scroll(
                    (viewport.width - pad.left - pad.right).max(0.0),
                    (viewport.height - pad.top - pad.bottom).max(0.0),
                    axis.free_x(),
                    axis.free_y(),
                ),
            );

            let content_size = content_rects
                .first()
                .copied()
                .unwrap_or(Rect::new(0.0, 0.0, 0.0, 0.0));
            // What scrolls is the content **and** its room, which is what makes the far
            // inset reachable rather than decorative.
            let scrolled = Size::new(
                content_size.width + pad.left + pad.right,
                content_size.height + pad.top + pad.bottom,
            );
            let max_x = (scrolled.width - viewport.width).max(0.0);
            let max_y = (scrolled.height - viewport.height).max(0.0);

            // The geometry without the identity: enough to ask where the content sits at
            // an offset, and what offset would put a box where it is wanted.
            let frame = Scrollable {
                id,
                viewport,
                max_x,
                max_y,
                physics: None,
                refresh: None,
                page: None,
                reverse_x: reverse.0,
                reverse_y: reverse.1,
                host: None,
                keep_visible: None,
            };
            // What the content asks to be kept in view — a tab bar's selected tab — in
            // the content's own coordinates, which is the only frame it can speak in.
            let asked = content.keep_visible(
                Size::new(content_size.width, content_size.height),
                &self.theme,
            );
            // Where that box would sit if nobody had scrolled: the frame's coordinates,
            // with the offset taken out. See [`KeepVisible::rect`] for why it is stored
            // this way rather than where it is drawn.
            let keep = asked.map(|keep| {
                let rest = frame.content_origin((0.0, 0.0), scrolled);
                KeepVisible {
                    rect: keep.rect.translate(
                        viewport.x + rest.0 + pad.left,
                        viewport.y + rest.1 + pad.top,
                    ),
                    ..keep
                }
            });
            // Inside the extent this frame has just measured, unless something owns the
            // offset: content that shrank is drawn where it rests (milestone 533).
            let (offset_x, offset_y) = match self.runtime.scroll_offset_within(id, (max_x, max_y)) {
                Some(offset) => offset,
                // Never scrolled, and something inside wants to be seen: **open** there
                // rather than sliding across a frame later. A tab bar restored on its
                // eighth tab should show the eighth tab, not show the first and then
                // travel. The same answer a paged view gives its initial page, and the
                // runtime retains the offset on that first frame so it stays.
                None => match keep {
                    Some(keep) => frame.keep_offset(keep).0,
                    None => (0.0, 0.0),
                },
            };

            let origin = frame.content_origin((offset_x, offset_y), scrolled);
            let content_translation = (
                viewport.x + origin.0 + pad.left,
                viewport.y + origin.1 + pad.top,
            );
            self.scrollables.push(Scrollable {
                id,
                viewport,
                max_x,
                max_y,
                physics: widget.scroll_physics(),
                refresh: self.refresh_host,
                page: None,
                reverse_x: reverse.0,
                reverse_y: reverse.1,
                host: self.scroll_host,
                keep_visible: keep,
            });
            let mut content_index = 0;
            let outer = self.scroll_host.replace(id);
            self.walk(
                content,
                child_id(id, 0, content),
                content_translation,
                content_clip,
                &content_rects,
                &mut content_index,
            );
            self.scroll_host = outer;

            // The overscroll glow, then the scrollbars, over the content (not
            // clipped by it).
            self.scene.set_clip(clip);
            self.add_overscroll_glow(id, viewport);
            if max_y > 0.0 {
                self.add_scrollbar(
                    id,
                    viewport,
                    Bar {
                        vertical: true,
                        offset: offset_y,
                        max: max_y,
                        reverse: reverse.1,
                        asked: widget.scrollbars(),
                        visible: widget.thumb_visibility(),
                    },
                );
            }
            if max_x > 0.0 {
                self.add_scrollbar(
                    id,
                    viewport,
                    Bar {
                        vertical: false,
                        offset: offset_x,
                        max: max_x,
                        reverse: reverse.0,
                        asked: widget.scrollbars(),
                        visible: widget.thumb_visibility(),
                    },
                );
            }
        } else if let Some(vlist) =
            widget.virtual_list(Size::new(draw_rect.width, draw_rect.height))
        {
            // A virtualised list: only build/lay out/paint the visible window.
            let viewport = draw_rect;
            let content_clip = clip.intersect(viewport);
            let reverse = widget.scroll_reverse();
            // Down the screen or across it. A list virtualises along **one** axis, which
            // is what lets it place item `n` without building the ones before it, so
            // `Axis::Both` has no meaning here and reads as vertical.
            let across = matches!(vlist.axis, crate::scroll::Axis::Horizontal);
            // Room around the items, inside the viewport and scrolling with them. The
            // **leading** inset is the one at the end the items start from, so a
            // reversed list clears the far end first and both keep their sides.
            let pad = widget.scroll_padding();
            let (lead, trail, cross_near, cross_far) = match (across, reverse) {
                (true, false) => (pad.left, pad.right, pad.top, pad.bottom),
                (true, true) => (pad.right, pad.left, pad.top, pad.bottom),
                (false, false) => (pad.top, pad.bottom, pad.left, pad.right),
                (false, true) => (pad.bottom, pad.top, pad.left, pad.right),
            };
            // From here down it is a main axis and a cross axis, and only the two
            // branches at the end have to know which is which. The alternative was a
            // second copy of the window arithmetic below, which is where a reversed
            // list gets its signs right -- and a fix applied to one copy and not the
            // other is exactly how the two would drift apart.
            let (extent, cross_extent) = match across {
                true => (viewport.width, viewport.height),
                false => (viewport.height, viewport.width),
            };
            let content = lead + trail + vlist.count as f32 * vlist.item_extent;
            let max = (content - extent).max(0.0);
            let bounds = if across { (max, 0.0) } else { (0.0, max) };
            let offset = self
                .runtime
                .scroll_offset_within(id, bounds)
                .map_or(0.0, |(x, y)| if across { x } else { y });
            self.scrollables.push(Scrollable {
                id,
                viewport,
                max_x: if across { max } else { 0.0 },
                max_y: if across { 0.0 } else { max },
                physics: widget.scroll_physics(),
                refresh: self.refresh_host,
                page: None,
                reverse_x: across && reverse,
                reverse_y: !across && reverse,
                host: self.scroll_host,
                keep_visible: None,
            });

            let outer = self.scroll_host.replace(id);
            if vlist.item_extent > 0.0 && vlist.count > 0 {
                // The **window** is the same arithmetic either way, and that is not a
                // coincidence: a reversed list counts its indices from the end, and a
                // reversed offset counts its pixels from the end, so index and offset
                // agree about which way is forward. Only where an item lands differs.
                let first = ((offset - lead) / vlist.item_extent).floor().max(0.0) as usize;
                let last = ((((offset + extent - lead) / vlist.item_extent).ceil()).max(0.0)
                    as usize)
                    .min(vlist.count);
                let origin = if across { viewport.x } else { viewport.y };
                for i in first..last {
                    let item = (vlist.build)(i);
                    let along = if reverse {
                        origin + extent - lead - (i + 1) as f32 * vlist.item_extent + offset
                    } else {
                        origin + lead + i as f32 * vlist.item_extent - offset
                    };
                    let (x, y) = match across {
                        true => (along, viewport.y + cross_near),
                        false => (viewport.x + cross_near, along),
                    };

                    // **Filled**, not merely constrained: a list hands its children a
                    // box rather than asking them how big they would like to be. The
                    // reference gives a list's children a *tight* cross-axis extent, and
                    // for a fixed-extent list a tight main-axis one too — which is
                    // exactly the pair of numbers here.
                    //
                    // Constrained-but-not-filled, a row whose width nobody set hugged
                    // its own text: a list of coloured rows painted a column of chips
                    // down the left instead of rows across the list. Found on a device
                    // in milestone 349.
                    let free_cross = (cross_extent - cross_near - cross_far).max(0.0);
                    let item_rects = self.cached_rects(
                        id.child(i),
                        item.as_ref(),
                        Constraints::filled(match across {
                            true => Size::new(vlist.item_extent, free_cross),
                            false => Size::new(free_cross, vlist.item_extent),
                        }),
                    );

                    let mut item_index = 0;
                    self.render_item(
                        item.as_ref(),
                        id.child(i),
                        (x, y),
                        content_clip,
                        &item_rects,
                        &mut item_index,
                    );
                }
            }

            self.scroll_host = outer;
            self.scene.set_clip(clip);
            self.add_overscroll_glow(id, viewport);
            if max > 0.0 {
                self.add_scrollbar(
                    id,
                    viewport,
                    Bar {
                        vertical: !across,
                        offset,
                        max,
                        reverse,
                        asked: widget.scrollbars(),
                        visible: widget.thumb_visibility(),
                    },
                );
            }
        } else if let Some(pages) = widget.page_view() {
            // A paged view: like a virtualised list turned on its side, and with the
            // page extent — the whole geometry — derived from the viewport rather than
            // given. Only the pages the viewport touches are built.
            let viewport = draw_rect;
            let content_clip = clip.intersect(viewport);
            let snap = pages.snap(viewport);
            let (viewport_along, page_across) = if snap.horizontal {
                (viewport.width, viewport.height)
            } else {
                (viewport.height, viewport.width)
            };
            let reverse = widget.scroll_reverse();
            // Room at both ends, so a page narrower than the viewport comes to rest
            // **centred** in it rather than jammed against the leading edge — and so
            // the last one can be reached at all: unpadded, the travel stops with the
            // last page's trailing edge on the viewport's, which is short of where that
            // page rests. Padded, the total works out to `extent × (count - 1)`,
            // the last page's own offset, exactly.
            let pad = pages.end_padding(viewport);
            let total = pages.count as f32 * snap.extent + 2.0 * pad;
            let max = (total - viewport_along).max(0.0);
            // With no retained offset this is the view's **first** frame, and it opens
            // on the page it was asked for. Reading the initial page here rather than
            // correcting it a frame later is what keeps page 0 from flashing past on
            // the way to page 3.
            let bounds = if snap.horizontal {
                (max, 0.0)
            } else {
                (0.0, max)
            };
            let along = match self.runtime.scroll_offset_within(id, bounds) {
                Some((x, y)) => {
                    if snap.horizontal {
                        x
                    } else {
                        y
                    }
                }
                None => snap
                    .offset_of(snap.requested.min(pages.count.saturating_sub(1)))
                    .clamp(0.0, max),
            };
            self.scrollables.push(Scrollable {
                id,
                viewport,
                max_x: if snap.horizontal { max } else { 0.0 },
                max_y: if snap.horizontal { 0.0 } else { max },
                physics: widget.scroll_physics(),
                refresh: self.refresh_host,
                page: Some(snap),
                reverse_x: snap.horizontal && reverse,
                reverse_y: !snap.horizontal && reverse,
                host: self.scroll_host,
                keep_visible: None,
            });

            let outer = self.scroll_host.replace(id);
            if pages.count > 0 {
                // The window is the same arithmetic whichever end index 0 is at: a
                // reversed view counts its indices from the far end and a reversed
                // offset counts its pixels from the same one, so the two agree about
                // which way forward is. Only where a page **lands** differs.
                let first = ((along - pad) / snap.extent).floor().max(0.0) as usize;
                let last = ((((along + viewport_along - pad) / snap.extent).ceil()).max(0.0)
                    as usize)
                    .min(pages.count)
                    .max(first + 1);
                // A wheel shows **more** rows than a flat strip would: the ones a quarter
                // turn away are compressed into the last few pixels at either end, and
                // their flat positions are a whole quarter-circumference outside the
                // viewport. Widening the window in both directions keeps the reversed
                // arithmetic above untouched, and the rows that turn out to have gone
                // over the horizon are dropped below — before they are built.
                let (first, last) = match pages.wheel {
                    Some(wheel) => {
                        let span = wheel.radius(viewport_along) * std::f32::consts::FRAC_PI_2;
                        let extra = (span / snap.extent).ceil().max(0.0) as usize + 1;
                        (first.saturating_sub(extra), (last + extra).min(pages.count))
                    }
                    None => (first, last),
                };
                for index in first..last.min(pages.count) {
                    let start = match reverse {
                        true => viewport_along - pad - (index + 1) as f32 * snap.extent + along,
                        false => pad + index as f32 * snap.extent - along,
                    };
                    // Where this row's centre would sit on the unrolled strip, measured
                    // from the middle of the viewport — which is the whole of what the
                    // cylinder needs to know about it.
                    let on_wheel = match pages.wheel {
                        Some(wheel) => {
                            let flat = start + snap.extent / 2.0 - viewport_along / 2.0;
                            match wheel.row(viewport_along, flat) {
                                // Past the horizon: not drawn, and not built either.
                                None => continue,
                                Some(row) => Some((row, flat)),
                            }
                        }
                        None => None,
                    };
                    let page = (pages.build)(index);
                    let (size, origin) = if snap.horizontal {
                        (
                            Size::new(snap.extent, page_across),
                            (viewport.x + start, viewport.y),
                        )
                    } else {
                        (
                            Size::new(page_across, snap.extent),
                            (viewport.x, viewport.y + start),
                        )
                    };

                    // A page is **given** its box, not asked for one: it fills the
                    // panel even when its content is a single centred line.
                    let page_rects = self.cached_rects(
                        id.child(index),
                        page.as_ref(),
                        Constraints::filled(size),
                    );

                    let mut page_index = 0;
                    // The row is drawn **flat**, then the whole of it is composited on
                    // the cylinder — one layer per row, the way `Transform` does it, so
                    // the text, the rules and the backgrounds all turn together instead
                    // of each primitive having to know it is on a wheel.
                    let before = self.scene.primitives().len();
                    let base = self.xform_base();
                    self.render_item(
                        page.as_ref(),
                        id.child(index),
                        origin,
                        content_clip,
                        &page_rects,
                        &mut page_index,
                    );
                    if let Some((row, flat)) = on_wheel {
                        // The row's own centre on screen: the scale is about it, so a row
                        // shrinks in place rather than creeping towards a corner.
                        let centre = Point::new(
                            viewport.x + viewport.width / 2.0,
                            viewport.y + viewport_along / 2.0 + flat,
                        );
                        let matrix = Affine::scale(row.scale_x, row.scale_y)
                            .about(centre)
                            // And then up or down to where the cylinder actually put it.
                            .then(Affine::translation(0.0, row.offset - flat));
                        let group = self.scene.split_off(before);
                        self.scene.push_primitive(Primitive::Layer {
                            primitives: group,
                            opacity: row.opacity.clamp(0.0, 1.0),
                            clip: content_clip,
                            clip_shape: ClipShape::Rect,
                            transform: Some(LayerTransform::new(matrix)),
                            filter: LayerFilter::NONE,
                            owner: id.child(index).as_u64(),
                        });
                        self.transform_interaction_registries(&base, matrix);
                    }
                }
            }

            self.scroll_host = outer;
            self.scene.set_clip(clip);
            self.add_overscroll_glow(id, viewport);
        } else if let Some(overflow) = widget.overflow_box() {
            // The child is laid out to constraints of its own — which is why it can
            // come out bigger than the box holding it — then anchored inside it and
            // rendered **without** the box's clip. A spill that got clipped here would
            // be no spill at all; a `ClipRect` above is how a caller asks for one.
            let own = draw_rect;
            if let Some(child) = widget.children().first() {
                let child = child.as_ref();
                let cid = child_id(id, 0, child);
                let asked = overflow.child_size(Size::new(own.width, own.height));
                let child_rects = if overflow.unconstrained {
                    // Unconstrained: the child is asked how big it wants to be, and
                    // gets exactly that.
                    self.cached_rects(cid, child, Constraints::scroll(0.0, 0.0, true, true))
                } else {
                    self.cached_rects(cid, child, Constraints::filled(asked))
                };
                let size = child_rects
                    .first()
                    .map(|r| Size::new(r.width, r.height))
                    .unwrap_or(asked);
                let origin = overflow.origin(own, size);

                let mut child_index = 0;
                self.render_item(child, cid, origin, clip, &child_rects, &mut child_index);
            }
        } else if let Some(transform) = widget.constraints_transform() {
            // The child is laid out at **the same box the measurement gave it**, worked out
            // again from what is left of that measurement — the box it produced. Each of
            // the three things an axis can say survives the round trip; see
            // `AxisConstraint::at`.
            let own = draw_rect;
            if let Some(child) = widget.children().first() {
                let child = child.as_ref();
                let cid = child_id(id, 0, child);
                let (aw, free_x) = transform.width.at(own.width);
                let (ah, free_y) = transform.height.at(own.height);
                let constraints = match (free_x, free_y) {
                    (false, false) => Constraints::filled(Size::new(aw, ah)),
                    _ => Constraints::scroll(aw, ah, free_x, free_y),
                };
                let child_rects = self.cached_rects(cid, child, constraints);
                let size = child_rects
                    .first()
                    .map(|r| Size::new(r.width, r.height))
                    .unwrap_or(Size::new(0.0, 0.0));
                let align = transform.alignment;
                let origin = (
                    own.x + (own.width - size.width) * align.fraction_x(),
                    own.y + (own.height - size.height) * align.fraction_y(),
                );
                if transform.report {
                    self.report_spill(own, Rect::new(origin.0, origin.1, size.width, size.height));
                }
                let mut child_index = 0;
                self.render_item(child, cid, origin, clip, &child_rects, &mut child_index);
            }
        } else if let Some(build) = widget.layout_builder() {
            // Builds the content from the actual box, then lays it out and renders it inside
            // (like a list item: with no retained state).
            let bounds = draw_rect;
            let content_clip = clip.intersect(bounds);
            let child = build(Size::new(bounds.width, bounds.height));

            // **Filled**, not merely constrained: the content is handed this box, and it
            // was built from this box in the first place. Constraining it instead let a
            // root with no width of its own hug its content — a grid built here laid its
            // columns out at nothing, which is what `GridView::extent`'s first tests found
            // (milestone 356). The same distinction a list's items and a paged view's
            // pages already draw.
            let child_rects = self.cached_rects(
                id.child(0),
                child.as_ref(),
                Constraints::filled(Size::new(bounds.width, bounds.height)),
            );

            let mut child_index = 0;
            self.render_item(
                child.as_ref(),
                id.child(0),
                (bounds.x, bounds.y),
                content_clip,
                &child_rects,
                &mut child_index,
            );
        } else if let Some(build) = widget.scroll_overlay() {
            // The **body first**, exactly as an ordinary single child: it keeps its own
            // identity, registers itself as a scroll region in its own right, and consumes
            // its rects from this array the way the generic walk would. Nothing about it
            // changes for being watched.
            let children = widget.children();
            for (child_index, child) in children.iter().enumerate() {
                self.walk(
                    child.as_ref(),
                    child_id(id, child_index, child.as_ref()),
                    translation,
                    clip,
                    rects,
                    index,
                );
            }
            // Then the overlay, built from **where the body has got to this frame**. Read
            // from the retained offset rather than from the registry the walk is still
            // filling: the offset is written before the frame is drawn, so it is current,
            // where the extents beside it are not yet known — which is why the builder is
            // handed the one and not the other.
            let offset = children
                .first()
                .map(|body| child_id(id, 0, body.as_ref()))
                .and_then(|body| self.runtime.scroll.get(&body).copied())
                .unwrap_or((0.0, 0.0));
            let bounds = draw_rect;
            let over = build(offset, Size::new(bounds.width, bounds.height));
            // `child(1)`, beside the body's `child(0)` — or beside its key, which cannot
            // collide with a positional identity. The overlay is laid out in a tree of its
            // own, so it needs an identity of its own for hover, ink and the paint cache.
            let over_id = id.child(1);
            let over_rects = self.cached_rects(
                over_id,
                over.as_ref(),
                // **Filled**, not constrained: an overlay covers the region it is over, and
                // where inside that box its content sits is the caller's business — a
                // column pins it to the top, an `Align` puts it anywhere else. The same
                // rule a `layout_builder`'s content is given.
                Constraints::filled(Size::new(bounds.width, bounds.height)),
            );
            let mut over_index = 0;
            self.render_item(
                over.as_ref(),
                over_id,
                (bounds.x, bounds.y),
                clip.intersect(bounds),
                &over_rects,
                &mut over_index,
            );
        } else if let Some(spec) = widget.dismissible() {
            // A dismissible item is a stack whose **last** layer — the item itself — is
            // offset by however far it has been swiped, and whose earlier layers, the
            // backgrounds, show only through the strip the item has uncovered. Clipping
            // them is what makes a background read as something the item is sliding
            // *off*, rather than a block that was always there.
            let bounds = draw_rect;
            let state = self.runtime.dismiss.get(&id).copied();
            let progress = state.map(|s| s.progress()).unwrap_or(0.0);
            let layers = widget.children();
            let last = layers.len().saturating_sub(1);
            // Which background: the first covers a swipe towards the end, the second —
            // when there is one — the other way. With only one, it serves both.
            let shown_background = if progress < 0.0 && last >= 2 { 1 } else { 0 };
            let strip = crate::dismiss::revealed_strip(bounds, progress);

            for (i, layer) in layers.iter().enumerate() {
                let is_item = i == last;
                if !is_item && (i != shown_background || progress == 0.0) {
                    // Not the background this direction shows: skip it, and skip the
                    // rects it would have consumed — it is laid out separately, so
                    // there is no index to keep in step.
                    continue;
                }
                let offset = if is_item {
                    if spec.axis.is_horizontal() {
                        (bounds.width * progress, 0.0)
                    } else {
                        (0.0, bounds.height * progress)
                    }
                } else {
                    (0.0, 0.0)
                };
                let layer_clip = if is_item {
                    clip.intersect(bounds)
                } else {
                    clip.intersect(strip)
                };
                if layer_clip.width <= 0.0 || layer_clip.height <= 0.0 {
                    continue;
                }
                let cid = child_id(id, i, layer.as_ref());
                let layer_rects = self.cached_rects(
                    cid,
                    layer.as_ref(),
                    Constraints::filled(Size::new(bounds.width, bounds.height)),
                );
                let mut layer_index = 0;
                self.walk(
                    layer.as_ref(),
                    cid,
                    (bounds.x + offset.0, bounds.y + offset.1),
                    layer_clip,
                    &layer_rects,
                    &mut layer_index,
                );
            }

            self.dismissables.push(Dismissable {
                id,
                rect: bounds,
                spec,
            });
            // A swipe that is settling, flying or collapsing drives itself.
            if state.is_some_and(|s| s.phase() != DismissPhase::Drag) {
                self.wants_animation = true;
            }
        } else if widget.stack() {
            // A stack: the layers are rendered in order, bottom first.
            let bounds = draw_rect;
            let layer_clip = clip.intersect(bounds);
            let loose = widget.stack_loose();
            // An **indexed** stack shows one layer and lays out the rest. Which is a
            // question for here rather than for the widget: a layer that wrapped itself in
            // something to keep quiet would no longer be laid out the way a bare layer is,
            // and the layout is the whole promise.
            let shown = widget.stack_visible();
            // Where a layer smaller than the stack sits. Resolved once, against the
            // reading direction, so a start-anchored badge follows the script.
            let align = widget
                .alignment_geometry()
                .unwrap_or(frus_core::AlignmentGeometry::Physical(
                    frus_core::Alignment::TOP_LEFT,
                ))
                .resolve(if self.rtl() {
                    frus_core::TextDirection::Rtl
                } else {
                    frus_core::TextDirection::Ltr
                });
            for (i, layer) in widget.children().iter().enumerate() {
                let cid = child_id(id, i, layer.as_ref());
                // What this layer asks for on each axis: a pinned pair gives a number, a
                // lone pin plus an explicit extent gives one, and neither leaves the axis
                // to the layer itself — or, under `Expand`, to the stack.
                // A layer moving between two sets of pins is read from the runtime rather
                // than from the widget: the widget carries where it is **going**, and a
                // layer that jumped there would be the whole bug this animates away.
                // Both the size and the place come from the one value, so a box cannot be
                // measured against one frame's pins and placed against another's.
                let pins = match layer.positioned() {
                    Some(spec) if layer.anim_pins().is_some() => {
                        Some(self.runtime.anim_pins(cid).unwrap_or(spec))
                    }
                    other => other,
                };
                let (want_w, want_h) = match pins {
                    Some(p) => (
                        p.resolved_width(bounds.width),
                        p.resolved_height(bounds.height),
                    ),
                    None if loose => (None, None),
                    // The historical behaviour, and still the default: a layer is
                    // **given** the box rather than asked what size it would like. An
                    // unsized layer that hugged its content would collapse to nothing —
                    // invisibly, since a stack draws no box of its own.
                    None => (Some(bounds.width), Some(bounds.height)),
                };
                // A pinned layer is **forced** into what its edges say: two opposite
                // pins are not a suggestion, and a width of its own is a contradiction
                // rather than a second opinion. An unpinned layer under `Expand` is
                // merely handed the box, which leaves a layer that chose a size alone —
                // that is what a badge sitting in a filled stack has always relied on.
                // An axis nobody pinned is left free, so the layer's own size comes back.
                let layer_rects = if pins.is_some() {
                    self.cached_rects(
                        cid,
                        layer.as_ref(),
                        Constraints::pinned(want_w, want_h, Size::new(bounds.width, bounds.height)),
                    )
                } else {
                    match (want_w, want_h) {
                        (Some(w), Some(h)) => self.cached_rects(
                            cid,
                            layer.as_ref(),
                            Constraints::filled(Size::new(w, h)),
                        ),
                        _ => self.cached_rects(
                            cid,
                            layer.as_ref(),
                            Constraints::scroll(bounds.width, bounds.height, true, true),
                        ),
                    }
                };
                let own = layer_rects
                    .first()
                    .copied()
                    .unwrap_or(Rect::new(0.0, 0.0, 0.0, 0.0));
                let (dx, dy) = match pins {
                    Some(p) => (
                        Positioning::place(
                            p.left,
                            p.right,
                            bounds.width,
                            own.width,
                            align.fraction_x(),
                        ),
                        Positioning::place(
                            p.top,
                            p.bottom,
                            bounds.height,
                            own.height,
                            align.fraction_y(),
                        ),
                    ),
                    None => (
                        (bounds.width - own.width).max(0.0) * align.fraction_x(),
                        (bounds.height - own.height).max(0.0) * align.fraction_y(),
                    ),
                };
                let mut layer_index = 0;
                // A layer that is not the shown one is walked in full — so it is measured,
                // and so the runtime keeps its scroll offset, its caret and its focus — and
                // then everything it added is dropped again. The same withdrawal a
                // `Visibility` that maintains its size performs, applied from outside.
                let hidden = shown.is_some_and(|which| which != i);
                let base = hidden.then(|| self.barrier_base());
                self.walk(
                    layer.as_ref(),
                    cid,
                    (bounds.x + dx, bounds.y + dy),
                    layer_clip,
                    &layer_rects,
                    &mut layer_index,
                );
                if let Some(base) = base {
                    self.apply_barrier(HIDDEN_LAYER, &base, cid, Rect::new(0.0, 0.0, 0.0, 0.0));
                }
            }
        } else if let Some((content, placement)) = widget.overlay() {
            // The anchor (child 0) is rendered inline; the overlay (child 1) is deferred.
            self.walk(
                widget.children()[0].as_ref(),
                child_id(id, 0, widget.children()[0].as_ref()),
                translation,
                clip,
                rects,
                index,
            );
            // The appearance progress: for an animated overlay (a drawer), the value the
            // runtime interpolated; otherwise `1.0` (shown at once). With no value recorded
            // (an isolated render), the target is adopted immediately.
            let target = widget.anim_target().unwrap_or(1.0);
            let progress = self.runtime.value_or(id, target);
            // A tooltip only shows while the anchor is hovered; an animated overlay disappears
            // once its progress has fallen back to zero.
            let visible = match placement {
                Placement::Tooltip => self.runtime.input.hovered == Some(id.child(0)),
                _ => true,
            };
            if visible && progress > 0.001 {
                self.overlays.push((
                    content,
                    child_id(id, 1, content),
                    draw_rect,
                    placement,
                    widget.overlay_dismiss(),
                    progress,
                    widget.overlay_traps_focus(),
                    widget.overlay_scrim(&self.theme),
                    self.theme.clone(),
                ));
            }
        } else {
            let children = widget.children();
            // Fractional alignment (`Container::alignment`) + paint offset
            // (`Transform::translate`): both offset the subtree. `(0, 0)` otherwise → the
            // ordinary flex walk.
            let extra = self.child_offset(widget, id, rect, rects, *index, children);
            for (child_index, child) in children.iter().enumerate() {
                self.walk(
                    child.as_ref(),
                    child_id(id, child_index, child.as_ref()),
                    (translation.0 + extra.0, translation.1 + extra.1),
                    clip,
                    rects,
                    index,
                );
            }
        }
        self.depth -= 1;
    }

    /// Offset to apply to a child's subtree: the sum of the **fractional alignment**
    /// (`Widget::alignment`, a single child slid through the free space) and the **paint
    /// offset** (`Transform::translate`, the whole subtree offset without touching layout).
    /// `(0, 0)` by default. Since it is added to the walk's translation, this offset follows
    /// both the primitives **and** the hit-test.
    fn child_offset(
        &self,
        widget: &dyn Widget<Msg>,
        id: WidgetId,
        container: Rect,
        rects: &[Rect],
        child_index: usize,
        children: &[Box<dyn Widget<Msg>>],
    ) -> (f32, f32) {
        let mut off = (0.0, 0.0);

        // Fractional alignment: it targets a single child. taffy laid the child out at the
        // top left (Start/Start) at its natural size; it is then slid by `free × fraction`.
        // A **stack** answers this question too, and means something else by it: where a
        // layer smaller than the box sits, which the stack branch applies per layer. It
        // must not also be applied to the stack itself, or a stack with exactly one layer
        // would shift twice.
        if let (Some(geo), 1, false) = (widget.alignment_geometry(), children.len(), widget.stack())
        {
            // An **animated** anchor moves through the runtime's pair rather than the
            // widget's own numbers, in the anchor's own coordinates — so the reading
            // direction is applied to the interpolated anchor below, and not to the two
            // it came from.
            let geo = match self.runtime.anim_offset(id) {
                Some((x, y)) => geo.with_fractions(x, y),
                None => geo,
            };
            // Resolves the alignment (physical or directional) against the reading direction;
            // `resolve` produces a physical `Alignment` that the rest (with its RTL correction)
            // handles uniformly.
            let direction = if self.rtl() {
                frus_core::TextDirection::Rtl
            } else {
                frus_core::TextDirection::Ltr
            };
            let align = geo.resolve(direction);
            let child = rects[child_index];
            let pad = effective_style(widget, id, self.runtime, &self.theme).padding;
            let free_w = (container.width - pad.left - pad.right - child.width).max(0.0);
            let free_h = (container.height - pad.top - pad.bottom - child.height).max(0.0);
            // In RTL, taffy lays the child out on the left and `mirror` has sent it back to
            // the right: the baseline is therefore already right-aligned. 1 is subtracted so
            // the fraction stays **physical** (x = +1 ⇒ the right in both directions).
            let fx = align.fraction_x() - if self.rtl() { 1.0 } else { 0.0 };
            off.0 += free_w * fx;
            off.1 += free_h * align.fraction_y();
        }

        // Paint offset (`Transform::translate`): in RTL the world's x axis is mirrored, so a
        // logical +x offset ("towards the end") points left — the sign is inverted to stay
        // consistent with the reading direction.
        if let Some((tx, ty)) = widget.transform_translate() {
            off.0 += if self.rtl() { -tx } else { tx };
            off.1 += ty;
        }

        // The same offset, given as a **fraction of the child's own box**
        // (`FractionalTranslation`). The child's rectangle is the one thing this function
        // has that the widget did not: a widget cannot multiply by a width it was never
        // told.
        if let Some((fx, fy)) = widget.translate_fraction() {
            // The same tween, on the other offset rule: a slide that animates reads the
            // runtime's pair, and one that does not reads its own.
            let (fx, fy) = self.runtime.anim_offset(id).unwrap_or((fx, fy));
            let child = rects.get(child_index).copied().unwrap_or(container);
            let tx = child.width * fx;
            off.0 += if self.rtl() { -tx } else { tx };
            off.1 += child.height * fy;
        }

        off
    }

    /// Records the widget in the inspector's collection (when it is on) and opens a depth
    /// level — every render path closes it again at the end of the function
    /// (`self.depth -= 1`).
    fn inspect_enter(&mut self, widget: &dyn Widget<Msg>, id: WidgetId, draw_rect: Rect) {
        if let Some(nodes) = &mut self.inspector {
            nodes.push(crate::inspector::InspectorNode {
                id,
                rect: draw_rect,
                name: widget.debug_name(),
                depth: self.depth,
            });
        }
        self.depth += 1;
    }

    /// A widget's full status: pointer interaction + focus + animation progresses + the
    /// cursor/selection when there is one.
    fn full_status(&self, widget: &dyn Widget<Msg>, id: WidgetId) -> crate::interaction::Status {
        let mut status = self.runtime.input.status_for(id);
        status.hover_progress = self.runtime.hover_progress(id);
        status.focus_progress = self.runtime.focus_progress(id);
        // A press is a progression now, and where the runtime has never heard of this
        // widget the flag is adopted whole — the rule `value` follows just below. Without
        // it a frame built outside the loop would draw a held widget as untouched.
        status.press_progress = self.runtime.press_progress_or(
            id,
            if status.interaction == crate::interaction::Interaction::Pressed {
                1.0
            } else {
                0.0
            },
        );
        status.opacity = self.runtime.opacity(id);
        // A widget's own animated value, or **its target** where the runtime has never
        // heard of it: the same rule the runtime applies on mount (adopt, do not animate
        // in from zero). Without the fallback an isolated render — a test, a frame built
        // before the loop has advanced anything — draws every such widget at zero: a
        // switch that is on drawn off, an indicator under the wrong tab.
        status.value = match widget.anim_target() {
            Some(target) => self.runtime.value_or(id, target),
            None => self.runtime.value(id),
        };
        status.anim_color = self.runtime.anim_color(id);
        status.anim_radius = self.runtime.anim_radius(id);
        status.time = self.runtime.time;
        status.drag_over = self.runtime.drag_over == Some(id);
        status.scroll_y = self.runtime.scroll.get(&id).map(|s| s.1).unwrap_or(0.0);
        if status.focused {
            if let Some(edit) = self.runtime.edits.get(&id) {
                status.cursor = Some(edit.cursor);
                status.selection = edit.selection_range();
                status.composing = edit.composing;
            }
            status.handles = self.runtime.selection_handles == Some(id);
            status.caret_hidden = self.runtime.caret_hidden;
        }
        status
    }

    /// The generic focus ring (for widgets that do not draw their own).
    fn draw_focus_ring(
        &mut self,
        draw_rect: Rect,
        status: &crate::interaction::Status,
        widget: &dyn Widget<Msg>,
    ) {
        // The generic ring only appears when the last interaction was a **keyboard** one
        // (`focus_visible`) — a click must not flash a ring.
        if status.focused
            && self.runtime.focus_visible
            && widget.focusable()
            && !widget.draws_own_focus()
        {
            let ring = Rect::new(
                draw_rect.x - 2.0,
                draw_rect.y - 2.0,
                draw_rect.width + 4.0,
                draw_rect.height + 4.0,
            );
            let alpha = 0.4 + 0.6 * status.focus_progress.clamp(0.0, 1.0);
            self.scene.draw_rect(
                ring,
                Color::TRANSPARENT,
                self.theme.radius + 2.0,
                2.0,
                self.theme.focus.fade(alpha),
            );
        }
    }

    /// Renders a **virtualised list item**: built on the fly, it cannot defer an overlay
    /// (hence a render of its own, without the special branches).
    fn render_item(
        &mut self,
        widget: &dyn Widget<Msg>,
        id: WidgetId,
        translation: (f32, f32),
        clip: Rect,
        rects: &[Rect],
        index: &mut usize,
    ) {
        let rect = rects[*index];
        *index += 1;
        let draw_rect = rect.translate(translation.0, translation.1);
        self.inspect_enter(widget, id, draw_rect);

        let status = self.full_status(widget, id);
        if widget.continuous() {
            self.wants_animation = true;
        }
        self.scene.set_clip(clip);
        self.scene.set_owner(id.as_u64());
        // The box this widget was given. Text primitives record it: a line of text
        // says only where it starts, and the renderer has to know what it covers to
        // order it against anything else (milestone 295).
        self.scene.set_bounds(draw_rect);
        widget.paint(draw_rect, status, &self.theme, &mut self.scene);
        self.scene.set_clip(clip);
        self.draw_focus_ring(draw_rect, &status, widget);

        let visible = draw_rect.intersect(clip);
        // A focus stop clipped entirely away by a **scroll** is still a focus stop.
        // Tab has to reach the field below the fold — the shell brings it into view
        // when it lands there — and registering only what the eye can see is how a long
        // form came to have half its fields unreachable from the keyboard. Clipped away
        // by anything else it is gone: nothing could reveal it, so focus would land
        // where the eye cannot follow.
        //
        // Only the focus registry does this. A click still needs the visible box, or a
        // tap on empty space would land on something scrolled out of sight.
        if widget.focusable()
            && !self.focus_excluded
            && (self.scroll_host.is_some() || (visible.width > 0.0 && visible.height > 0.0))
        {
            self.focusables.push(Focusable {
                id,
                rect: visible,
                bounds: draw_rect,
                form: self.autofill_group,
                scroll: self.scroll_host,
                skip: self.focus_skipped || widget.focus_skip_traversal(),
                order: widget.focus_order().or(self.focus_order),
                group: self.focus_group,
            });
        }
        if visible.width > 0.0 && visible.height > 0.0 {
            // A press that lands on a **surface** and on nothing inside it stops there.
            // Registered before the children, so anything inside still wins on the way
            // back out — see [`Widget::opaque`].
            if widget.opaque() {
                self.hits.push(Hit {
                    id,
                    rect: visible,
                    msg: None,
                    xform: None,
                });
            }
            if let Some(msg) = widget.on_click() {
                self.hits.push(Hit {
                    id,
                    rect: visible,
                    msg: Some(msg),
                    xform: None,
                });
            }
            if let Some(msg) = widget.on_long_press() {
                self.long_presses.push(Hit {
                    id,
                    rect: visible,
                    msg: Some(msg),
                    xform: None,
                });
            }
            if widget.draggable() {
                self.draggables.push((id, visible));
            }
            if widget.reorder_index().is_some() {
                self.reorderables.push((id, visible));
            }
            // The accessibility tree: nodes that carry meaning (a role or a label).
            if let Some(sem) = widget.semantics().filter(|s| s.is_meaningful()) {
                self.semantics.push((id, visible, sem));
            }
        }

        let children = widget.children();
        // Fractional alignment + paint offset, as in the main walk (a virtualised-list /
        // `layout_builder` child may itself be an aligned or transformed container).
        let extra = self.child_offset(widget, id, rect, rects, *index, children);
        for (child_index, child) in children.iter().enumerate() {
            self.render_item(
                child.as_ref(),
                child_id(id, child_index, child.as_ref()),
                (translation.0 + extra.0, translation.1 + extra.1),
                clip,
                rects,
                index,
            );
        }
        self.depth -= 1;
    }

    /// Lays out a full-window screen and renders it offset by `off_x`.
    fn render_screen(
        &mut self,
        screen: &'a dyn Widget<Msg>,
        id: WidgetId,
        bounds: Rect,
        off_x: f32,
        clip: Rect,
    ) {
        let rects = self.cached_rects(
            id,
            screen,
            Constraints::definite(Size::new(bounds.width, bounds.height)),
        );
        let screen_clip = clip.intersect(bounds);
        let mut index = 0;
        self.walk(
            screen,
            id,
            (bounds.x + off_x, bounds.y),
            screen_clip,
            &rects,
            &mut index,
        );
    }

    /// Processes the deferred overlays: sub-layout, positioning and rendering **above**
    /// everything (their clickable areas win). May spawn further overlays (nested portals).
    fn process_overlays(&mut self) {
        let window = Rect::new(0.0, 0.0, self.available.width, self.available.height);
        while let Some((content, oid, anchor, placement, dismiss, progress, traps, scrim, theme)) =
            self.overlays.pop()
        {
            // The theme this overlay was declared under, for the whole of its layout and
            // painting; whatever was in force when the walk ended is put back after it,
            // so two overlays declared under two themes do not bleed into each other.
            let outer = std::mem::replace(&mut self.theme, theme);
            // Drawers slide along a **spring curve** (a gentle arrival), not linearly; the
            // other overlays keep their raw progress.
            let progress = if matches!(
                placement,
                Placement::Left | Placement::Right | Placement::Bottom
            ) {
                crate::runtime::spring_ease(progress)
            } else {
                progress
            };
            // The content's natural size. A drawer (`Left`) is constrained in height to the
            // window (so its `Percent(1.0)` panel unfolds) with a free width; the other
            // overlays take their natural size.
            let (free_x, free_y) = match placement {
                Placement::Left | Placement::Right => (true, false),
                // The sheet is full-width (constrained to the window) with its natural height:
                // its `Percent(1.0)` panel unfolds across the width.
                Placement::Bottom => (false, true),
                _ => (true, true),
            };
            let mut rects = self.cached_rects(
                oid,
                content,
                Constraints::scroll(self.available.width, self.available.height, free_x, free_y),
            );
            let mut size = rects
                .first()
                .copied()
                .unwrap_or(Rect::new(0.0, 0.0, 0.0, 0.0));
            // **Nothing wider than the window.** A free axis asks the content how big it
            // would like to be, and a dialog answers with the width of its widest line —
            // which, at a reader's font size, is wider than the screen. Centred, that
            // spills off *both* edges, and a button drawn at a negative x is a button
            // nobody can press. So the answer is taken as a wish rather than a size: past
            // the room there is, the content is laid out again at that room, and whatever
            // can fold — a paragraph, a bar of actions — folds.
            //
            // The room is the window less the content's **own margin**, which is how an
            // overlay says how far off the edges it wants to be held: a dialog's inset
            // padding is exactly that, and a clamp that ignored it would push the surface
            // flat against both sides of the screen.
            //
            // The height is deliberately left alone. A dialog too tall for the screen
            // wants its content to scroll, which is a question of its own; squashing it
            // here would only move the spill inside the surface.
            let inset = content.style_themed(&self.theme).margin;
            let room = (self.available.width - inset.left - inset.right).max(0.0);
            if free_x && size.width > room {
                rects = self.cached_rects(
                    oid,
                    content,
                    Constraints::scroll(room, self.available.height, false, free_y),
                );
                size = rects
                    .first()
                    .copied()
                    .unwrap_or(Rect::new(0.0, 0.0, 0.0, 0.0));
            }

            // A drawer's slide-in from the left / right edge.
            let from_left = -(1.0 - progress) * size.width;
            let from_right = self.available.width - progress * size.width;
            // An anchored menu/tooltip: aligned to the anchor's **start** edge — in RTL that
            // edge is the right one (the menu opens leftwards).
            let anchor_x = if self.rtl() {
                anchor.x + anchor.width - size.width
            } else {
                anchor.x
            };
            let mut pos = match placement {
                Placement::Below => (anchor_x, anchor.y + anchor.height + 4.0),
                Placement::Center => (
                    (self.available.width - size.width) * 0.5,
                    (self.available.height - size.height) * 0.5,
                ),
                Placement::Tooltip => (anchor_x, anchor.y - size.height - 6.0),
                // `Left` = a drawer on the **start** side; in RTL, start = the right.
                Placement::Left if self.rtl() => (from_right, 0.0),
                Placement::Left => (from_left, 0.0),
                // `Right` = the **end** side; in RTL, end = the left.
                Placement::Right if self.rtl() => (from_left, 0.0),
                Placement::Right => (from_right, 0.0),
                // The sheet slides up from the bottom: its bottom edge stays flush with the
                // window, offset downwards by `(1-progress)·height`.
                Placement::Bottom => (0.0, self.available.height - progress * size.height),
            };

            // An **anchored** overlay follows a widget; the others (a modal, a drawer, a
            // sheet) are positioned against the window and have no anchor worth the name.
            // Only the first kind can find its anchor gone from the window: a screen
            // sliding out under a `Navigator`, a row scrolled sideways past the edge.
            let anchored = matches!(placement, Placement::Below | Placement::Tooltip);
            let anchor_on_screen = !anchored
                || (anchor.x < self.available.width
                    && anchor.x + anchor.width > 0.0
                    && anchor.y < self.available.height
                    && anchor.y + anchor.height > 0.0);

            // Auto-flip: when an anchored overlay overflows an edge, it is flipped / nudged
            // back inside the window.
            //
            // This is for a menu opened near the right margin, and it assumes the anchor is
            // something the window is showing. When the anchor has **left** the window the
            // nudge does the opposite of its job: it drags a departing screen's menu back
            // into view, fully opaque, over the screen that replaced it. An overlay whose
            // anchor is off screen goes off screen with it.
            if anchored && anchor_on_screen {
                // A vertical overflow → flip to the other side of the anchor.
                if placement == Placement::Below
                    && pos.1 + size.height > self.available.height
                    && anchor.y - size.height - 4.0 >= 0.0
                {
                    pos.1 = anchor.y - size.height - 4.0;
                } else if placement == Placement::Tooltip
                    && pos.1 < 0.0
                    && anchor.y + anchor.height + size.height + 6.0 <= self.available.height
                {
                    pos.1 = anchor.y + anchor.height + 6.0;
                }
                // A horizontal overflow → nudge back inside the window.
                if pos.0 + size.width > self.available.width {
                    pos.0 = (self.available.width - size.width).max(0.0);
                }
                if pos.0 < 0.0 {
                    pos.0 = 0.0;
                }
            }

            if matches!(
                placement,
                Placement::Center | Placement::Left | Placement::Right | Placement::Bottom
            ) {
                // The scrim behind the modal / the drawer, modulated by the progress (a fade
                // synchronised with the slide). The colour is the overlay's own when it asked
                // for one — alpha included, since a scrim's transparency *is* the colour —
                // and the `scrim` role at half opacity otherwise.
                let base = scrim.unwrap_or_else(|| self.theme.scheme.scrim.with_alpha(0.5));
                self.scene.set_owner(0);
                self.scene.set_clip(window);
                self.scene
                    .fill_rect(window, base.with_alpha(base.a * progress));
            }

            // Dismissal on a click **outside** the content (a modal, a menu…): a full-screen
            // hit added **before** the content, so the content beats it where they overlap.
            // The dismissal is also remembered for Escape (the last one rendered = the
            // topmost).
            //
            // Gated on the same condition as the nudge, and for the same reason: a
            // window-wide barrier belonging to an overlay nobody can see would swallow the
            // next press anywhere on the screen that replaced it.
            if let Some(msg) = dismiss.filter(|_| anchor_on_screen) {
                self.dismisses.push(msg.clone());
                self.hits.push(Hit {
                    id: oid.barrier(),
                    rect: window,
                    msg: Some(msg),
                    xform: None,
                });
            }

            // A **modal** (scrimmed) or **trapping anchored** (menu) overlay: its focusables
            // form a **scope** that traps Tab/arrows/click-to-focus. The last one rendered (the
            // topmost) wins; anchored overlays that do not trap (a tooltip, an autocomplete
            // list) leave the focus alone.
            let modal = matches!(
                placement,
                Placement::Center | Placement::Left | Placement::Right | Placement::Bottom
            );
            if modal || traps {
                self.focus_scope_start = Some(self.focusables.len());
            }

            let mut index = 0;
            self.walk(content, oid, pos, window, &rects, &mut index);
            self.theme = outer;
        }
    }
}

impl<Msg: Clone> Builder<'_, Msg> {
    /// Draws a scrollbar (track + thumb) and registers it for hit-testing a drag.
    /// Paints the region's overscroll glows over its viewport.
    ///
    /// The colour is the scheme's **secondary**: the edge feedback is an
    /// acknowledgement, not a call to action, so it must read as part of the surface
    /// rather than compete with whatever primary-coloured control sits nearby.
    fn add_overscroll_glow(&mut self, id: WidgetId, viewport: Rect) {
        if let Some(glows) = self.runtime.scroll_glow.get(&id) {
            glows.paint(viewport, self.theme.scheme.secondary, &mut self.scene);
        }
    }

    fn add_scrollbar(&mut self, id: WidgetId, viewport: Rect, axis: Bar) {
        let Bar {
            vertical,
            offset,
            max,
            reverse,
            asked,
            visible,
        } = axis;
        // **Along the horizontal axis, never** (`app.dart:861`) — on any platform, under
        // any setting. A sideways strip is scrolled by the thing that made it sideways,
        // and a bar under it takes room from content that is short of it already.
        if !vertical {
            return;
        }
        // And down the vertical one, only where the platform's own scroll views have a
        // bar (`app.dart:865` against `:870`). A finger already knows where it is on the
        // page; a permanent bar over the content is an affordance for a pointer that
        // cannot feel the edges. This drew one everywhere, on both axes, always.
        if asked.unwrap_or(self.runtime.scrollbars) == crate::physics::Scrollbars::Never {
            return;
        }
        let (track_start, track_len, content_len) = if vertical {
            (viewport.y, viewport.height, viewport.height + max)
        } else {
            (viewport.x, viewport.width, viewport.width + max)
        };
        // Every metric below is `theme ?? framework`. There is no per-call override for a
        // scrollbar — it is drawn by the walk, not by a widget a caller configured — so
        // the chain is two terms here rather than three.
        let bar = &self.theme.widgets.scrollbar;
        let bar_size = bar.thickness.unwrap_or(BAR_SIZE);
        let bar_margin = bar.margin.unwrap_or(BAR_MARGIN);
        let thumb_len = (track_len * track_len / content_len)
            .max(bar.min_thumb_length.unwrap_or(MIN_THUMB))
            .min(track_len);
        let travel = track_len - thumb_len;
        // Along a reversed axis the numbers run the other way, so the thumb does too:
        // offset 0 is the far end, and that is where it rests.
        let fraction = if max > 0.0 { offset / max } else { 0.0 };
        let fraction = if reverse { 1.0 - fraction } else { fraction };
        let thumb_pos = track_start + fraction * travel;

        // The track's rectangle is still worked out — it is the room a pointer has to be
        // in, and the geometry the thumb sits in — but nothing is painted for it.
        //
        // `BAR_SIZE` is the **thumb's** thickness, not a slot's: the reference keeps the
        // thumb clear of the edge with `crossAxisMargin` (`scrollbar.dart:357`) rather
        // than shrinking it to fit. This drew a 6-pixel thumb inside an 8-pixel slot,
        // which is the same arithmetic with the wrong number left over.
        let (track, thumb) = if vertical {
            let x = viewport.x + viewport.width - bar_margin - bar_size;
            (
                Rect::new(
                    x - bar_margin,
                    viewport.y,
                    bar_size + bar_margin * 2.0,
                    viewport.height,
                ),
                Rect::new(x, thumb_pos, bar_size, thumb_len),
            )
        } else {
            let y = viewport.y + viewport.height - bar_margin - bar_size;
            (
                Rect::new(
                    viewport.x,
                    y - bar_margin,
                    viewport.width,
                    bar_size + bar_margin * 2.0,
                ),
                Rect::new(thumb_pos, y, thumb_len, bar_size),
            )
        };
        // What a mouse has to be inside for the bar to notice it: the track, widened to
        // take in a tap target's worth of room around the thumb (`scrollbar.dart:762`).
        let reach = {
            let (cx, cy) = (thumb.x + thumb.width * 0.5, thumb.y + thumb.height * 0.5);
            let r = crate::theme::MIN_TAP_TARGET * 0.5;
            let x0 = track.x.min(cx - r);
            let y0 = track.y.min(cy - r);
            let x1 = (track.x + track.width).max(cx + r);
            let y1 = (track.y + track.height).max(cy + r);
            Rect::new(x0, y0, x1 - x0, y1 - y0)
        };

        // **How present the bar is**, this frame. It arrives when the area moves and goes
        // again once the area has been still long enough; an area nobody has scrolled has
        // none at all. Unless it was asked to stay (`scrollbar.dart:214`).
        let fade = self.runtime.scrollbar_fade_of(id);
        let opacity = if visible.unwrap_or(false) {
            1.0
        } else {
            fade.opacity.clamp(0.0, 1.0)
        };

        // **No track.** The reference's is transparent unless a caller asks for one
        // (`scrollbar.dart:281`), and even then it is 3 to 5 %.
        //
        // The thumb takes the reference's opacity for the surface's brightness: at rest
        // (`scrollbar.dart:242`, `:248`), warmed towards its hovered value while a
        // pointer is near it (`:239`, `:245`), and at its dragged value the moment the
        // thumb is held (`:238`, `:244`) — that one does not fade in, because the hand is
        // already on it and a fade would only lag behind the grab.
        // The scheme's own answer, which is what the reference reads here
        // (`scrollbar.dart:232`). This used to be `surface.compute_luminance() < 0.5`:
        // right on both built-in schemes and a guess on any other.
        let dark = self.theme.brightness().is_dark();
        let (rest, warm, grabbed) = if dark {
            (THUMB_ON_DARK, THUMB_HOVER_ON_DARK, THUMB_DRAG_ON_DARK)
        } else {
            (THUMB_ON_LIGHT, THUMB_HOVER_ON_LIGHT, THUMB_DRAG_ON_LIGHT)
        };
        // A theme's levels replace the scheme's, one at a time: naming the resting
        // opacity says nothing about the held one.
        let rest = bar.opacity.unwrap_or(rest);
        let warm = bar.hover_opacity.unwrap_or(warm);
        let grabbed = bar.drag_opacity.unwrap_or(grabbed);
        let level = if self.runtime.scrollbar_dragged == Some(id) {
            grabbed
        } else {
            rest + (warm - rest) * fade.hover.clamp(0.0, 1.0)
        };
        if opacity > 0.0 {
            let base = bar.thumb_color.unwrap_or(self.theme.scheme.on_surface);
            self.scene.draw_rect(
                thumb,
                base.fade(level * opacity),
                bar.radius.unwrap_or(bar_size * 0.5),
                0.0,
                Color::TRANSPARENT,
            );
        }
        // Registered even when nothing was painted for it — unlike a bar the platform
        // does not draw at all, which is not registered because it is not there. A mouse
        // coming near a faded bar is what brings it back (`scrollbar.dart:2132`), so
        // something has to be here for the mouse to find. What a bar at zero cannot be is
        // **grabbed**; see `Ui::scrollbar_at`.
        self.scrollbars.push(Scrollbar {
            id,
            vertical,
            thumb,
            track_start,
            track_len,
            thumb_len,
            reverse,
            max,
            opacity,
            reach,
        });
    }
}

/// Turns a widget tree into a [`Ui`] for a given size, runtime state and theme.
pub fn build_ui<'a, Msg: Clone + 'static>(
    root: &'a dyn Widget<Msg>,
    available: Size,
    runtime: &'a Runtime,
    theme: &'a Theme,
) -> Ui<Msg> {
    build_ui_impl(root, available, runtime, theme, false).0
}

/// Like [`build_ui`], but it also collects the **inspection nodes** (one per painted widget:
/// name, box, depth) — the raw material of the runtime inspector and of the diagnostic dump.
/// Reserve it for the frames where the inspector is on.
pub fn build_ui_inspected<'a, Msg: Clone + 'static>(
    root: &'a dyn Widget<Msg>,
    available: Size,
    runtime: &'a Runtime,
    theme: &'a Theme,
) -> (Ui<Msg>, Vec<crate::inspector::InspectorNode>) {
    let (ui, nodes) = build_ui_impl(root, available, runtime, theme, true);
    (ui, nodes.unwrap_or_default())
}

/// Panics, **in debug builds only**, when the reader's font size is installed and the
/// surface it belongs to is not.
///
/// The two travel together — [`MediaQuery::install`] sets both — so a scale away from 1
/// with no description means somebody installed half a surface, and the half they left out
/// is about to be missing for the layout that follows. That is not a theory: for four
/// milestones the shell scoped only the build, the scale was 1 while text was measured and
/// painted, and the reader's setting reached a device without moving a pixel. Nothing said
/// a word — not the 91 goldens, not clippy, not the strict rustdoc.
///
/// Debug only, because it is a wiring mistake rather than a state a running application can
/// reach: it should stop a test, not a user's frame. A scale of exactly 1 is the neutral
/// value and says nothing either way, so it is never a failure.
#[cfg(debug_assertions)]
fn assert_surface_is_whole() {
    let scale = frus_core::text_scale();
    if (scale - 1.0).abs() > f32::EPSILON && !crate::MediaQuery::of().is_described() {
        panic!(
            "a text scale of {scale} is installed with no surface described: something \
             installed half a surface. Use `MediaQuery::install` (or `scope`), which sets \
             the description and the reader's font size together \u{2014} see milestone 408."
        );
    }
}

fn build_ui_impl<'a, Msg: Clone + 'static>(
    root: &'a dyn Widget<Msg>,
    available: Size,
    runtime: &'a Runtime,
    theme: &'a Theme,
    inspect: bool,
) -> (Ui<Msg>, Option<Vec<crate::inspector::InspectorNode>>) {
    #[cfg(debug_assertions)]
    assert_surface_is_whole();

    let (mut rects, overflows) = runtime.layout_cache.borrow_mut().rects(
        WidgetId::ROOT,
        root,
        runtime,
        theme,
        Constraints::definite(available),
    );

    let mut builder = Builder {
        scene: Scene::new(),
        hits: Vec::new(),
        long_presses: Vec::new(),
        dismisses: Vec::new(),
        focusables: Vec::new(),
        focus_scope_start: None,
        scrollables: Vec::new(),
        scrollbars: Vec::new(),
        draggables: Vec::new(),
        drag_sources: Vec::new(),
        drop_zones: Vec::new(),
        inks: Vec::new(),
        reorderables: Vec::new(),
        interactives: Vec::new(),
        overlays: Vec::new(),
        wants_animation: false,
        available,
        runtime,
        theme: std::rc::Rc::new(theme.clone()),
        inspector: inspect.then(Vec::new),
        depth: 0,
        refresh_host: None,
        scroll_host: None,
        hero_screen: None,
        heroes: Vec::new(),
        refreshes: Vec::new(),
        dismissables: Vec::new(),
        sheets: Vec::new(),
        semantics: Vec::new(),
        system_ui: Vec::new(),
        focus_excluded: false,
        backdrop_group: None,
        focus_skipped: false,
        focus_order: None,
        focus_group: None,
        autofill_group: None,
        scopes: Vec::new(),
        listeners: Vec::new(),
        overflows: std::cell::RefCell::new(Vec::new()),
        pending_overflows: std::cell::RefCell::new(std::collections::HashMap::new()),
    };
    // The root is mirrored in RTL (like every layout root).
    builder.mirror(&mut rects);
    builder.record_overflows(WidgetId::ROOT, &rects, overflows);
    let mut index = 0;
    builder.walk(
        root,
        WidgetId::ROOT,
        (0.0, 0.0),
        Rect::UNBOUNDED,
        &rects,
        &mut index,
    );

    // Overlays (floating menus, modals, tooltips) above everything else. (Their walk restarts
    // from depth 0: roots as far as the inspector is concerned.)
    builder.process_overlays();

    // End of frame: forget the layout roots and repaint boundaries of widgets that have gone,
    // and freeze the caches' diagnostic counters.
    runtime.layout_cache.borrow_mut().end_frame();
    runtime.paint_cache.borrow_mut().end_frame();

    // Replays the outgoing subtrees, fading out, over the current scene.
    builder.scene.set_clip(Rect::UNBOUNDED);
    for (primitives, opacity) in runtime.leaving.values() {
        for primitive in primitives {
            builder.scene.push_faded(primitive, *opacity);
        }
    }

    // A box whose children ran past it now **says so on the screen**, not only in the
    // console — see `paint_overflow_bands`. Last, so nothing paints over it.
    paint_overflow_bands(&mut builder.scene, &builder.overflows.borrow());

    let ui = Ui {
        scene: builder.scene,
        hits: builder.hits,
        long_presses: builder.long_presses,
        dismisses: builder.dismisses,
        focusables: builder.focusables,
        focus_scope_start: builder.focus_scope_start,
        scrollables: builder.scrollables,
        scrollbars: builder.scrollbars,
        draggables: builder.draggables,
        drag_sources: builder.drag_sources,
        drop_zones: builder.drop_zones,
        inks: builder.inks,
        reorderables: builder.reorderables,
        interactives: builder.interactives,
        refreshes: builder.refreshes,
        dismissables: builder.dismissables,
        sheets: builder.sheets,
        wants_animation: builder.wants_animation,
        semantics: builder.semantics,
        system_ui: builder.system_ui,
        overflows: builder.overflows.into_inner(),
        scopes: builder.scopes,
        listeners: builder.listeners,
    };
    (ui, builder.inspector)
}

/// Collects the identities of every widget in the tree (prefix order), following the same
/// positional scheme as [`build_ui`]. Used to detect mounts/unmounts between two frames.
pub fn collect_ids<Msg>(root: &dyn Widget<Msg>) -> Vec<WidgetId> {
    fn walk<Msg>(widget: &dyn Widget<Msg>, id: WidgetId, out: &mut Vec<WidgetId>) {
        out.push(id);
        for (index, child) in widget.children().iter().enumerate() {
            walk(child.as_ref(), child_id(id, index, child.as_ref()), out);
        }
    }
    let mut out = Vec::new();
    walk(root, WidgetId::ROOT, &mut out);
    out
}

/// Identities of the **subtree** rooted at `root_id` — `widget` being the widget with that
/// identity — that is `[root_id, …descendants]`, derived by the same positional scheme as
/// [`collect_ids`].
///
/// Used by the **drag ghost**: a **rich** card's primitives are painted by its children (owners
/// other than the card itself). To capture all of its visuals, the shell gathers the primitives
/// of the **whole** subtree, not only the card's own.
pub fn subtree_ids<Msg>(widget: &dyn Widget<Msg>, root_id: WidgetId) -> Vec<WidgetId> {
    fn walk<Msg>(widget: &dyn Widget<Msg>, id: WidgetId, out: &mut Vec<WidgetId>) {
        out.push(id);
        for (index, child) in widget.children().iter().enumerate() {
            walk(child.as_ref(), child_id(id, index, child.as_ref()), out);
        }
    }
    let mut out = Vec::new();
    walk(widget, root_id, &mut out);
    out
}

/// The owners of everything a carried row, card or item may be **moved past** this frame:
/// every reorderable that can be dropped on, and all it paints.
///
/// What a reorder preview slides out of the way is decided by geometry — the band the
/// source sits in — and geometry alone moves whatever shares that band: a button floating
/// over a list, the navigation bar under it. This is the other half of the question, *is
/// it part of something that can be reordered*, asked of the tree. A grip is inside its
/// row, so it moves with it without being a target itself.
pub fn reorderable_owners<Msg>(
    ui: &Ui<Msg>,
    root: &dyn Widget<Msg>,
) -> std::collections::HashSet<u64> {
    ui.reorderables
        .iter()
        .filter_map(|(id, _)| {
            find_widget(root, *id)
                .filter(|widget| widget.reorder_droppable())
                .map(|widget| subtree_ids(widget, *id))
        })
        .flatten()
        .map(|id| id.as_u64())
        .collect()
}

/// The slots a reorderable `id` can be dropped among **in its own list**: its siblings — the
/// children of its parent — that can be dropped on, with their boxes this frame, in order.
///
/// A list's rows are one widget's children, and so are a board column's cards and the drop
/// zone that ends it. Nothing else on the page is, which is what lets a drop that landed on
/// no row at all still mean *somewhere in this list* rather than anywhere reorderable.
/// Siblings the frame registered no box for are left out.
pub fn reorder_siblings<Msg>(
    ui: &Ui<Msg>,
    root: &dyn Widget<Msg>,
    id: WidgetId,
) -> Vec<(WidgetId, Rect)> {
    fn parent_of<Msg>(
        widget: &dyn Widget<Msg>,
        own: WidgetId,
        target: WidgetId,
    ) -> Option<(&dyn Widget<Msg>, WidgetId)> {
        for (index, child) in widget.children().iter().enumerate() {
            let id = child_id(own, index, child.as_ref());
            if id == target {
                return Some((widget, own));
            }
            if let Some(found) = parent_of(child.as_ref(), id, target) {
                return Some(found);
            }
        }
        None
    }
    let Some((parent, parent_id)) = parent_of(root, WidgetId::ROOT, id) else {
        return Vec::new();
    };
    parent
        .children()
        .iter()
        .enumerate()
        .filter(|(_, child)| child.reorder_index().is_some() && child.reorder_droppable())
        .filter_map(|(index, child)| {
            let id = child_id(parent_id, index, child.as_ref());
            ui.reorderables
                .iter()
                .find(|(registered, _)| *registered == id)
                .map(|(_, rect)| (id, *rect))
        })
        .collect()
}

/// Identity of the **first** widget declaring the key `key` (a hash), or `None`. It is how the
/// shell resolves a focus-by-key request (`Command::focus`): the application wraps a field in
/// `keyed(k, …)`, then focuses by `k`.
pub fn find_by_key<Msg>(root: &dyn Widget<Msg>, key: u64) -> Option<WidgetId> {
    fn walk<Msg>(widget: &dyn Widget<Msg>, id: WidgetId, key: u64) -> Option<WidgetId> {
        if widget.key() == Some(key) {
            return Some(id);
        }
        for (index, child) in widget.children().iter().enumerate() {
            if let Some(found) = walk(child.as_ref(), child_id(id, index, child.as_ref()), key) {
                return Some(found);
            }
        }
        None
    }
    walk(root, WidgetId::ROOT, key)
}

/// Identity of the **sheet** the key `key` names: the first sheet's panel at or under the
/// widget declaring it, which is the identity the sheet's state is kept under and the one the
/// frame's sheets are reported by. `None` when nothing declares the key, or nothing under it
/// is a sheet.
///
/// A sheet's state belongs to its panel, which the application never builds itself, so a
/// request by key (`Command::sheet`) needs this one step more than a focus request does.
pub fn find_sheet_by_key<Msg>(root: &dyn Widget<Msg>, key: u64) -> Option<WidgetId> {
    fn first_sheet<Msg>(widget: &dyn Widget<Msg>, id: WidgetId) -> Option<WidgetId> {
        if widget.sheet().is_some() {
            return Some(id);
        }
        widget
            .children()
            .iter()
            .enumerate()
            .find_map(|(index, child)| {
                first_sheet(child.as_ref(), child_id(id, index, child.as_ref()))
            })
    }
    fn walk<Msg>(widget: &dyn Widget<Msg>, id: WidgetId, key: u64) -> Option<WidgetId> {
        if widget.key() == Some(key) {
            return first_sheet(widget, id);
        }
        widget
            .children()
            .iter()
            .enumerate()
            .find_map(|(index, child)| {
                walk(child.as_ref(), child_id(id, index, child.as_ref()), key)
            })
    }
    walk(root, WidgetId::ROOT, key)
}

/// Path from the **root down to the widget** with identity `target` (`[root, …, target]`), for
/// the leaf→root bubbling of keys. Empty when it cannot be found.
pub fn find_path<Msg>(root: &dyn Widget<Msg>, target: WidgetId) -> Vec<&dyn Widget<Msg>> {
    fn walk<'a, Msg>(
        widget: &'a dyn Widget<Msg>,
        id: WidgetId,
        target: WidgetId,
        path: &mut Vec<&'a dyn Widget<Msg>>,
    ) -> bool {
        path.push(widget);
        if id == target {
            return true;
        }
        for (index, child) in widget.children().iter().enumerate() {
            if walk(
                child.as_ref(),
                child_id(id, index, child.as_ref()),
                target,
                path,
            ) {
                return true;
            }
        }
        path.pop();
        false
    }
    let mut path = Vec::new();
    if !walk(root, WidgetId::ROOT, target, &mut path) {
        path.clear();
    }
    path
}

/// The theme a subtree inherits at this node — the widget's own override, with any
/// **animated text style** the runtime is holding for it laid on top.
///
/// The one place the theme swap happens, and it is one place on purpose. The swap is made
/// four times over a frame — by the layout pass, by the relayout fingerprint that has to
/// agree with it or the cache lies, by the paint walk, and by [`build_deferred`] before
/// any of them — and every animated value in this framework is read from the runtime by
/// whoever consumes it. This one's consumer is the swap itself, so a copy of the rule at
/// each of the four sites is four chances to drift. `Responsive` cost three silent bugs
/// that way (milestone 495); this is the same lesson written down as a function.
///
/// Cheap where nothing is animated: no `anim_text_style`, no clone, and the widget's own
/// `theme_override` is returned untouched — which is every node but the rare one.
pub(crate) fn scoped_theme<Msg>(
    widget: &dyn Widget<Msg>,
    id: WidgetId,
    runtime: &Runtime,
    inherited: &Theme,
) -> Option<Box<Theme>> {
    let own = widget.theme_override(inherited);
    let Some(target) = widget.anim_text_style() else {
        return own;
    };
    // Mid-flight if the runtime has a value for this node, and the target otherwise —
    // which is the first frame, before the family has been advanced over this tree.
    let style = runtime.anim_text_style(id).unwrap_or(target);
    let mut theme = own.map_or_else(|| inherited.clone(), |boxed| *boxed);
    // **Merged over**, not assigned: the node's own `theme_override` has already put the
    // target style and the four unanimated answers (alignment, wrapping, overflow, line
    // count) in place, and this replaces field by field exactly what is moving.
    theme.widgets.text.style = theme.widgets.text.style.merge(style);
    Some(Box::new(theme))
}

/// Runs the **deferred builds** over a tree, the way the layout pass does on its way down.
///
/// A [`ThemeBuilder`](crate::ThemeBuilder) — and everything built on one, an
/// [`AppBar`](crate::AppBar) included — has no children at all until something calls
/// [`Widget::build_themed`] on it. The layout pass does that first thing, so within a frame
/// nothing ever meets an unbuilt subtree.
///
/// **A tree built outside a frame does.** The shell rebuilds from `view` alone on a burst of
/// keystrokes, faster than a frame, so the next key sees the current value rather than the
/// retained tree's — and then reads that tree straight away. Every traversal that arrives
/// there ([`find_widget`], focus resolution, a caret being revealed) walks a tree whose
/// deferred subtrees are empty, and silently finds nothing.
///
/// This is that half of the walk and nothing else: the theme swap
/// ([`Widget::theme_override`]) then the build, top-down. The swap is not optional — a
/// builder inside a [`Themed`](crate::Themed) has to see its own subtree's theme, and a
/// preparation that is *nearly* the walk is worse than none, because what it builds is wrong
/// rather than absent.
///
/// **Which is why it takes a runtime.** A subtree under an animated text style
/// (`AnimatedDefaultTextStyle`) inherits a theme that is moving, and a builder inside one
/// composes against whatever theme reaches it *first* — this walk. Preparing it against
/// the target instead of the value in flight is the same failure as skipping the swap: what
/// it builds is wrong rather than absent, and only for as long as the movement lasts, which
/// is the hardest kind to see. The runtime is one frame behind here, because this runs
/// before the frame advances its animations, and one frame behind is the whole tree agreeing
/// with itself rather than a builder disagreeing with the layout around it.
pub fn build_deferred<Msg>(root: &dyn Widget<Msg>, theme: &Theme, runtime: &Runtime) {
    fn walk<Msg>(widget: &dyn Widget<Msg>, id: WidgetId, runtime: &Runtime, theme: &Theme) {
        widget.expand(id, runtime, theme);
        let scoped = scoped_theme(widget, id, runtime, theme);
        let theme = scoped.as_deref().unwrap_or(theme);
        let _surface = widget
            .media_override(crate::MediaQuery::of())
            .map(crate::MediaQuery::install);
        let _shell = widget.scaffold_override().map(crate::ScaffoldInfo::install);
        widget.build_in(id, runtime, theme);
        for (index, child) in widget.children().iter().enumerate() {
            walk(
                child.as_ref(),
                child_id(id, index, child.as_ref()),
                runtime,
                theme,
            );
        }
    }
    walk(root, WidgetId::ROOT, runtime, theme);
}

/// The widget of the tree under `root` that has the identity `target`, or `None` if none
/// does. Identities are the ones the walk that built the frame gave, so an id read from a
/// [`Ui`] finds its widget here.
pub fn find_widget<Msg>(root: &dyn Widget<Msg>, target: WidgetId) -> Option<&dyn Widget<Msg>> {
    fn walk<Msg>(
        widget: &dyn Widget<Msg>,
        id: WidgetId,
        target: WidgetId,
    ) -> Option<&dyn Widget<Msg>> {
        if id == target {
            return Some(widget);
        }
        for (index, child) in widget.children().iter().enumerate() {
            if let Some(found) = walk(child.as_ref(), child_id(id, index, child.as_ref()), target) {
                return Some(found);
            }
        }
        None
    }
    walk(root, WidgetId::ROOT, target)
}

/// Folds a filter into the single filtered layer its subtree turned out to be, so two
/// filter widgets wrapped one inside the other cost one layer rather than two.
///
/// It is not only a saving. Compositing renders a layer into a texture and composites
/// that texture; a layer *inside* that texture is not composited again, so a nested
/// filter would simply not be applied. Folding is what makes `ColorFiltered` around
/// `ImageFiltered` mean what it reads as.
///
/// Everything about the inner layer must be neutral — full opacity, a plain
/// rectangular clip, no transform — because those are applied at compositing time and
/// there is only one composite to apply them at. And the two filters must not want
/// the same slot: greyscale of an inverted picture is not the inversion of a
/// greyscale one, so there is no single layer that means both, and the two nest.
fn fold_filter(
    group: Vec<Primitive>,
    filter: LayerFilter,
    clip: Rect,
) -> (Vec<Primitive>, LayerFilter, Rect) {
    if group.len() != 1 {
        return (group, filter, clip);
    }
    let Primitive::Layer {
        opacity,
        clip: inner_clip,
        clip_shape,
        transform,
        filter: inner,
        ..
    } = &group[0]
    else {
        return (group, filter, clip);
    };
    if *opacity < 0.999 || !matches!(clip_shape, ClipShape::Rect) || transform.is_some() {
        return (group, filter, clip);
    }
    let (inner, inner_clip) = (*inner, *inner_clip);
    let Some(merged) = filter.merge(inner) else {
        return (group, filter, clip);
    };
    let Some(Primitive::Layer { primitives, .. }) = group.into_iter().next() else {
        unreachable!("checked just above")
    };
    (primitives, merged, clip.intersect(inner_clip))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::physics::Scrollbars;
    use crate::runtime::Edit;
    use crate::{
        Button, Container, Flex, Key, Keyed, OverlayPortal, Placement, SingleChildScrollView,
        TextField,
    };
    use frus_core::{Color, Point, Primitive, Rect, Size};

    /// **A deep tree on the smallest stack any platform gives a frame.**
    ///
    /// Building a tree recurses twice over it — the layout walk and the scene walk — and
    /// what each level costs is a property of those two functions, not of the widgets.
    /// Two `Theme` copies in each frame made that cost 53 kilobytes a level, so a tree
    /// forty deep exhausted the megabyte a Windows main thread gets and the process died
    /// with no panic and no message. A real screen nests further than forty.
    ///
    /// One megabyte and 64 levels is what this holds to: the platform's smallest stack,
    /// against a tree deeper than a screen builds and half again the depth that used to
    /// die. It is deliberately not the deepest that fits — around 128 now, at about seven
    /// kilobytes a level — because a tripwire wants margin over the number it guards. An
    /// overflow aborts rather than fails, so this one kills the run outright, which is the
    /// right noise for what it watches.
    #[test]
    fn a_deep_tree_builds_on_a_platform_s_smallest_stack() {
        let built = std::thread::Builder::new()
            .stack_size(1024 * 1024)
            .spawn(|| {
                let mut node: Box<dyn Widget<Msg>> = Box::new(crate::Text::new("the bottom"));
                for _ in 0..64 {
                    node = Box::new(Container::new().padding(1.0).child(node));
                }
                let ui = build_ui(
                    node.as_ref(),
                    Size::new(800.0, 600.0),
                    &Runtime::default(),
                    &Theme::default(),
                );
                ui.scene().primitives().len()
            })
            .expect("spawning the deep-tree thread")
            .join()
            .expect("the deep tree was built");
        assert!(built > 0, "and it painted something");
    }

    #[derive(Clone, Debug, PartialEq)]
    enum Msg {
        A,
        B,
        C,
        D,
        Edited(String),
    }

    #[test]
    fn semantics_tree_carries_roles_and_labels() {
        use crate::{Button, Checkbox, Role, Text};
        let rt = Runtime::default();
        let tree = crate::Flex::column()
            .child(Text::new("Titre"))
            .child(Button::new("Submit").on_press(Msg::A))
            .child(Checkbox::new(true).on_toggle(|_| Msg::B));
        let ui = build_ui(&tree, Size::new(300.0, 200.0), &rt, &Theme::default());
        let sem = ui.semantics();
        // One node per meaningful widget (the containing Flex is skipped).
        let roles: Vec<Role> = sem.iter().map(|(_, _, s)| s.role).collect();
        assert!(roles.contains(&Role::Label));
        assert!(roles.contains(&Role::Button));
        assert!(roles.contains(&Role::CheckBox));
        // The button carries its label and is actionable.
        let button = sem.iter().find(|(_, _, s)| s.role == Role::Button).unwrap();
        assert_eq!(button.2.label.as_deref(), Some("Submit"));
        assert!(button.2.clickable);
        // The checked box mirrors its state.
        let check = sem
            .iter()
            .find(|(_, _, s)| s.role == Role::CheckBox)
            .unwrap();
        assert_eq!(check.2.toggled, crate::Toggled::True);
    }

    fn clickable_sample() -> Flex<Msg> {
        Flex::row()
            .width(400.0)
            .height(100.0)
            .padding(10.0)
            .gap(8.0)
            .child(
                Container::new()
                    .width(120.0)
                    .color(Color::rgb(1.0, 0.0, 0.0))
                    .hover_color(Color::rgb(0.0, 1.0, 0.0))
                    .on_click(Msg::A),
            )
            .child(
                Container::new()
                    .flex(1.0)
                    .color(Color::rgb(0.0, 0.0, 1.0))
                    .on_click(Msg::B),
            )
    }

    /// A box whose children ran past it is **marked on the screen**, over a tenth of it,
    /// on the edge they ran past — and a box whose children fit is left alone.
    #[test]
    fn an_overflow_paints_a_band_on_the_edge_it_ran_past() {
        use crate::{Container, Flex};
        // Two children, because a row with one is not dividing a line up — it hands its
        // constraints down, and a lone child is bounded by them rather than overflowing.
        let row = |child_width: f32| {
            let root: Flex<()> = Flex::row()
                .width(100.0)
                .height(40.0)
                .child(
                    Container::new()
                        .width(child_width)
                        .height(20.0)
                        .color(Color::WHITE),
                )
                .child(Container::new().width(20.0).height(20.0));
            let rt = crate::runtime::Runtime::default();
            build_ui(
                &root,
                Size::new(200.0, 100.0),
                &rt,
                &crate::theme::Theme::dark(),
            )
        };
        // The stripes are paths; nothing else in this tree draws one.
        let stripes = |ui: &Ui<()>| {
            ui.scene()
                .primitives()
                .iter()
                .filter(|p| matches!(p, Primitive::Path { .. }))
                .count()
        };
        let over = row(300.0);
        assert!(!over.overflows().is_empty(), "the fixture has to overflow");
        assert!(stripes(&over) > 2, "striped: {}", stripes(&over));
        // The band is on the right-hand tenth: 90..100 of a 100-wide row.
        let band = over
            .scene()
            .primitives()
            .iter()
            .rev()
            .find_map(|p| match p {
                Primitive::Rect { rect, color, .. } if color.a > 0.7 && color.r == 0.0 => {
                    Some(*rect)
                }
                _ => None,
            })
            .expect("the band under the stripes");
        assert!((band.x - 90.0).abs() < 0.5, "at the right edge: {band:?}");
        assert!((band.width - 10.0).abs() < 0.5, "a tenth of it: {band:?}");

        let fits = row(40.0);
        assert!(fits.overflows().is_empty(), "the fixture has to fit");
        assert!(fits.overflows().is_empty());
        assert_eq!(stripes(&fits), 0, "nothing to mark");
    }

    /// The band says **which edge and by how much**, in the reference's words. A striped
    /// edge tells you something is too big; the sentence tells you what to look for, and
    /// it is the only half of the report that survives being photographed off a device.
    #[test]
    fn a_band_writes_which_edge_overflowed_and_by_how_much() {
        use crate::{Container, Flex};
        let root: Flex<()> = Flex::row()
            .width(100.0)
            .height(40.0)
            .child(
                Container::new()
                    .width(300.0)
                    .height(20.0)
                    .color(Color::WHITE),
            )
            .child(Container::new().width(20.0).height(20.0));
        let ui = build_ui(
            &root,
            Size::new(200.0, 100.0),
            &Runtime::default(),
            &Theme::dark(),
        );
        // The label is inside the rotated layer, which is why the search is recursive.
        fn labels(primitives: &[Primitive], out: &mut Vec<String>) {
            for p in primitives {
                match p {
                    Primitive::Text { text, .. } => out.push(text.clone()),
                    Primitive::Layer { primitives, .. } => labels(primitives, out),
                    _ => {}
                }
            }
        }
        let mut found = Vec::new();
        labels(ui.scene().primitives(), &mut found);
        assert!(
            found.iter().any(|t| t == "RIGHT OVERFLOWED BY 220 PIXELS"),
            "the sentence, in the reference's words: {found:?}"
        );
    }

    /// The reference's precision rule: whole pixels when there are many, a decimal when
    /// there are few, three significant figures when there is almost nothing — which is
    /// the difference between a layout bug and a rounding error.
    #[test]
    fn an_overflow_is_written_to_the_precision_it_deserves() {
        assert_eq!(format_pixels(86.0), "86");
        // Past ten pixels the decimal is noise; at ten exactly it is not yet.
        assert_eq!(format_pixels(10.4), "10");
        assert_eq!(format_pixels(10.0), "10.0");
        assert_eq!(format_pixels(4.5), "4.5");
        assert_eq!(format_pixels(1.0), "1.00");
        assert_eq!(format_pixels(0.5), "0.500");
        assert_eq!(format_pixels(0.0123), "0.0123");
    }

    #[test]
    fn rtl_mirrors_row_horizontally() {
        let size = Size::new(400.0, 100.0);
        // A = a fixed 120 px button (on the left in LTR), B = the flexible remainder.
        let ltr = build_ui(
            &clickable_sample(),
            size,
            &Runtime::default(),
            &Theme::default(),
        );
        let rtl = build_ui(
            &clickable_sample(),
            size,
            &Runtime::default(),
            &Theme::default().rtl(),
        );
        let hit = |ui: &Ui<Msg>, x: f32| ui.hit(Point::new(x, 50.0)).and_then(|id| ui.msg_for(id));

        // LTR: button A takes the left edge.
        assert_eq!(hit(&ltr, 40.0), Some(Msg::A));
        assert_eq!(hit(&ltr, 360.0), Some(Msg::B));
        // RTL: everything is mirrored — A moves to the right, B takes the left.
        assert_eq!(hit(&rtl, 360.0), Some(Msg::A), "A on the right in RTL");
        assert_eq!(hit(&rtl, 40.0), Some(Msg::B), "B on the left in RTL");
    }

    #[test]
    fn wrapped_text_wraps_in_layout_and_invalidates_the_cache() {
        let tree = |text: &str| {
            crate::Flex::column()
                .width(120.0)
                .child(crate::Text::new(text).wrap())
                .child(Container::new().height(10.0).on_click(Msg::A))
        };
        // Position of the clickable follower: the first y hit while sweeping.
        let follower_y = |ui: &Ui<Msg>| {
            (0..600)
                .map(|y| y as f32)
                .find(|&y| ui.hit(Point::new(60.0, y)).is_some())
                .expect("suiveur cliquable")
        };

        let rt = Runtime::default();
        let long = "a rather long paragraph that will wrap onto several lines";
        let ui = build_ui(&tree(long), Size::new(120.0, 600.0), &rt, &Theme::default());

        // The paragraph's render carries its wrap width (≤ the column).
        let max_w = ui
            .scene()
            .primitives()
            .iter()
            .find_map(|p| match p {
                Primitive::Text { max_width, .. } => *max_width,
                _ => None,
            })
            .expect("a wrapped paragraph");
        assert!(max_w <= 120.5, "wrapped to the column width: {max_w}");

        // The wrapped text takes several lines: the follower is pushed down.
        let y_long = follower_y(&ui);
        assert!(
            y_long > 30.0,
            "the follower is pushed down by the wrap: {y_long}"
        );

        // The SAME structure/styles, different content, the SAME runtime (a warm cache): the
        // measure key must invalidate the cache — otherwise the rects would be stale.
        let ui2 = build_ui(
            &tree("short"),
            Size::new(120.0, 600.0),
            &rt,
            &Theme::default(),
        );
        let y_short = follower_y(&ui2);
        assert!(
            y_short < y_long,
            "shorter content → a higher follower (the cache was invalidated): {y_short} vs {y_long}"
        );
    }

    #[test]
    fn relayout_cache_reuses_the_root_layout_across_frames() {
        let rt = Runtime::default();
        let size = Size::new(400.0, 100.0);
        // Frame 1: nothing cached → a recomputation (at least the root).
        let _ = build_ui(&clickable_sample(), size, &rt, &Theme::default());
        let (hits1, misses1) = rt.layout_cache.borrow().last_frame_stats();
        assert_eq!(hits1, 0, "1st frame: nothing reused");
        assert!(misses1 >= 1, "1st frame: at least one computation");

        // Frame 2: the same tree, the same constraints → the root is reused.
        let _ = build_ui(&clickable_sample(), size, &rt, &Theme::default());
        let (hits2, misses2) = rt.layout_cache.borrow().last_frame_stats();
        assert_eq!(hits2, 1, "2nd frame: the root is reused");
        assert_eq!(misses2, 0, "2nd frame: nothing recomputed");

        // Frame 3: the window is resized → the constraints change → a recomputation.
        let _ = build_ui(
            &clickable_sample(),
            Size::new(500.0, 100.0),
            &rt,
            &Theme::default(),
        );
        let (hits3, misses3) = rt.layout_cache.borrow().last_frame_stats();
        assert_eq!((hits3, misses3), (0, 1), "redimensionnement → recalcul");
    }

    #[test]
    fn modal_traps_tab_arrows_and_pointer_focus() {
        use crate::portal::{OverlayPortal, Placement};
        // The background: two focusable buttons; the open modal: two buttons as well.
        let dialog = Flex::<Msg>::row()
            .child(Button::new("ok").on_press(Msg::C))
            .child(Button::new("no").on_press(Msg::D));
        let tree: Flex<Msg> = Flex::column()
            .child(Button::new("bg1").on_press(Msg::A))
            .child(Button::new("bg2").on_press(Msg::B))
            .child(
                OverlayPortal::new(Container::new())
                    .overlay(dialog, Placement::Center)
                    .dismiss(Msg::A),
            );
        let ui = build_ui(
            &tree,
            Size::new(400.0, 300.0),
            &Runtime::default(),
            &Theme::default(),
        );

        // Tab enters the trap (the modal's first focusable) and cycles inside it.
        let first = ui.focus_next(None, true).expect("the scope's first");
        assert_eq!(ui.msg_for(first), Some(Msg::C));
        let second = ui.focus_next(Some(first), true).expect("suivant");
        assert_eq!(ui.msg_for(second), Some(Msg::D));
        let wrapped = ui.focus_next(Some(second), true).expect("boucle");
        assert_eq!(
            ui.msg_for(wrapped),
            Some(Msg::C),
            "Tab cycles inside the modal"
        );

        // The arrows stay inside the scope: there is nothing above the dialog.
        assert_eq!(ui.focus_directional(first, FocusDirection::Up), None);
        let right = ui
            .focus_directional(first, FocusDirection::Right)
            .expect("to the right");
        assert_eq!(ui.msg_for(right), Some(Msg::D));

        // Click-to-focus ignores the background (the bg1 button is at the top left).
        assert_eq!(
            ui.focus_hit(Point::new(10.0, 10.0)),
            None,
            "fond hors scope"
        );

        // Without a modal: no trap, Tab starts at the background.
        let open_less: Flex<Msg> = Flex::column()
            .child(Button::new("bg1").on_press(Msg::A))
            .child(Button::new("bg2").on_press(Msg::B));
        let ui2 = build_ui(
            &open_less,
            Size::new(400.0, 300.0),
            &Runtime::default(),
            &Theme::default(),
        );
        let f = ui2.focus_next(None, true).expect("premier");
        assert_eq!(ui2.msg_for(f), Some(Msg::A));
    }

    #[test]
    fn open_menu_traps_focus_in_its_items() {
        use crate::PopupMenuButton;
        // A focusable background plus an **open** menu (anchor + two items).
        let menu = PopupMenuButton::new(Button::new("open").on_press(Msg::A), true, Msg::D)
            .item("one", Msg::B)
            .item("two", Msg::C);
        let tree: Flex<Msg> = Flex::column()
            .child(Button::new("bg").on_press(Msg::A))
            .child(menu);
        let ui = build_ui(
            &tree,
            Size::new(400.0, 300.0),
            &Runtime::default(),
            &Theme::default(),
        );

        // Tab enters the menu's items and **cycles** inside (background and anchor are out of scope).
        let first = ui.focus_next(None, true).expect("the scope's first");
        assert_eq!(ui.msg_for(first), Some(Msg::B));
        let second = ui.focus_next(Some(first), true).expect("suivant");
        assert_eq!(ui.msg_for(second), Some(Msg::C));
        let wrapped = ui.focus_next(Some(second), true).expect("boucle");
        assert_eq!(
            ui.msg_for(wrapped),
            Some(Msg::B),
            "Tab cycles inside the open menu"
        );
        // The background (top left) is out of scope while the menu is open.
        assert_eq!(
            ui.focus_hit(Point::new(10.0, 10.0)),
            None,
            "fond hors scope"
        );

        // The menu **closed**: no trap, Tab starts at the background.
        let closed: Flex<Msg> = Flex::column()
            .child(Button::new("bg").on_press(Msg::A))
            .child(PopupMenuButton::new(
                Button::new("open").on_press(Msg::B),
                false,
                Msg::D,
            ));
        let ui2 = build_ui(
            &closed,
            Size::new(400.0, 300.0),
            &Runtime::default(),
            &Theme::default(),
        );
        let f = ui2.focus_next(None, true).expect("premier");
        assert_eq!(ui2.msg_for(f), Some(Msg::A), "with no open menu, no trap");
    }

    #[test]
    fn escape_infrastructure_finds_path_and_topmost_dismiss() {
        use crate::portal::{OverlayPortal, Placement};
        // An open portal (a modal with a dismissal) around a clickable anchor.
        let anchor = Container::<Msg>::new()
            .width(50.0)
            .height(30.0)
            .on_click(Msg::A);
        let content = Container::<Msg>::new()
            .width(80.0)
            .height(40.0)
            .on_click(Msg::B);
        let portal = OverlayPortal::new(anchor)
            .overlay(content, Placement::Center)
            .dismiss(Msg::C);
        let tree: Flex<Msg> = Flex::column().child(portal);

        let ui = build_ui(
            &tree,
            Size::new(300.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );
        // The topmost dismissal is the portal's.
        assert_eq!(ui.top_dismiss(), Some(Msg::C));

        // Focus "inside the dialog": the root→content path goes through the portal, which
        // consumes Escape while bubbling. (The Center content, 80×40, is centred in 300×200 →
        // its centre is at (150, 100).)
        let inner = ui
            .hit(Point::new(150.0, 100.0))
            .expect("contenu de la modale");
        let path = find_path(&tree, inner);
        assert!(path.len() >= 3, "root, portal, content: {}", path.len());
        assert_eq!(
            path.last().unwrap().on_click(),
            Some(Msg::B),
            "the target closes the path"
        );
        let consumed = path
            .iter()
            .rev()
            .find_map(|w| match w.on_key(&crate::Key::Escape) {
                crate::KeyResponse::Handled(msg) => Some(msg),
                _ => None,
            });
        assert_eq!(
            consumed,
            Some(Some(Msg::C)),
            "the portal consumes Escape while bubbling"
        );

        // Chemin introuvable → vide ; pas d'overlay → pas de fermeture.
        assert!(find_path(&tree, WidgetId::ROOT.child(99)).is_empty());
        let closed: Flex<Msg> = Flex::column().child(Container::new().on_click(Msg::A));
        let ui2 = build_ui(
            &closed,
            Size::new(300.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );
        assert_eq!(ui2.top_dismiss(), None);
    }

    #[test]
    fn long_press_targets_are_collected_topmost_first() {
        // A long-press container holding a long-press child: a point inside the child returns
        // the child's message (the topmost one).
        let tree: Container<Msg> = Container::new()
            .width(200.0)
            .height(100.0)
            .on_long_press(Msg::A)
            .child(
                Container::new()
                    .width(50.0)
                    .height(50.0)
                    .on_long_press(Msg::B),
            );
        let ui = build_ui(
            &tree,
            Size::new(200.0, 100.0),
            &Runtime::default(),
            &Theme::default(),
        );
        assert_eq!(ui.long_press_at(Point::new(25.0, 25.0)), Some(Msg::B));
        assert_eq!(ui.long_press_at(Point::new(150.0, 80.0)), Some(Msg::A));
        assert_eq!(ui.long_press_at(Point::new(500.0, 500.0)), None);
    }

    #[test]
    fn hit_and_msg_for_route_correctly() {
        let rt = Runtime::default();
        let ui = build_ui(
            &clickable_sample(),
            Size::new(400.0, 100.0),
            &rt,
            &Theme::default(),
        );
        let id_a = ui.hit(Point::new(50.0, 50.0)).expect("A");
        let id_b = ui.hit(Point::new(300.0, 50.0)).expect("B");
        assert_ne!(id_a, id_b);
        assert_eq!(ui.msg_for(id_a), Some(Msg::A));
        assert_eq!(ui.msg_for(id_b), Some(Msg::B));
        assert_eq!(ui.hit(Point::new(3.0, 3.0)), None);
    }

    /// Every rectangle a frame paints down the right-hand edge of a 200-wide viewport.
    /// The bar is drawn last, over the content, and it is the only thing over there.
    fn painted(ui: &Ui<()>) -> Vec<(Rect, Color)> {
        ui.scene()
            .primitives()
            .iter()
            .filter_map(|p| match p {
                Primitive::Rect { rect, color, .. }
                    if rect.x >= 200.0 - BAR_SIZE - BAR_MARGIN * 2.0 =>
                {
                    Some((*rect, *color))
                }
                _ => None,
            })
            .collect()
    }

    /// A tall page in a short window, its bar **pinned**: whether a bar fades is the
    /// business of the tests below, and these are about whether there is one to fade.
    fn bars(area: SingleChildScrollView<()>, how: Scrollbars) -> Vec<(Rect, Color)> {
        let runtime = Runtime::with_scrollbars(how);
        let ui = build_ui(
            &area.thumb_visibility(true),
            Size::new(200.0, 100.0),
            &runtime,
            &Theme::dark(),
        );
        painted(&ui)
    }

    /// A tall column in a short viewport: something to scroll.
    fn tall() -> SingleChildScrollView<()> {
        SingleChildScrollView::new()
            .width(200.0)
            .height(100.0)
            .child(Container::<()>::new().width(200.0).height(1000.0))
    }

    /// **A touch screen gets no scrollbar** (`app.dart:870`).
    ///
    /// This drew one on every platform, on both axes, always — a permanent bar over the
    /// content of every scrolling page on a phone, where the reference draws nothing at
    /// all. A finger already knows where it is on the page.
    #[test]
    fn a_touch_screen_gets_no_scrollbar() {
        assert_eq!(bars(tall(), Scrollbars::Never), vec![]);
        assert_eq!(
            bars(tall(), Scrollbars::Always).len(),
            1,
            "and a desktop gets one"
        );

        // Nothing to drag, either: a bar that is not drawn is not a target.
        let runtime = Runtime::with_scrollbars(Scrollbars::Never);
        let ui = build_ui(&tall(), Size::new(200.0, 100.0), &runtime, &Theme::dark());
        assert!(ui.scrollbars().is_empty());
    }

    /// **A bar takes the scheme's word for the brightness, not the surface's luminance.**
    ///
    /// The opacities either side of this are three times apart at rest (`scrollbar.dart:242`,
    /// `:248`), so getting the question wrong is not a shade — it is a bar that reads as
    /// a smudge, or one that reads as a stripe.
    ///
    /// A **dimmed light** scheme is where the two answers part. The measurement it used
    /// to make says dark; the scheme says light, and the scheme is the one that knows.
    #[test]
    fn a_bar_reads_the_scheme_s_brightness_and_not_its_luminance() {
        use crate::media::Brightness;
        let dimmed = |brightness| {
            let mut theme = Theme::light();
            theme.scheme.surface = Color::rgb8(110, 110, 110);
            theme.scheme.brightness = brightness;
            theme
        };
        let thumb = |theme: &Theme| {
            let runtime = Runtime::with_scrollbars(Scrollbars::Always);
            let ui = build_ui(
                &tall().thumb_visibility(true),
                Size::new(200.0, 100.0),
                &runtime,
                theme,
            );
            painted(&ui)[0].1
        };

        let light = dimmed(Brightness::Light);
        assert!(
            light.scheme.surface.compute_luminance() < 0.5,
            "the luminance the old line measured says dark"
        );
        assert_eq!(
            thumb(&light),
            light.scheme.on_surface.fade(THUMB_ON_LIGHT),
            "and the bar takes the scheme's word instead"
        );

        let dark = dimmed(Brightness::Dark);
        assert_eq!(thumb(&dark), dark.scheme.on_surface.fade(THUMB_ON_DARK));
    }

    /// **A theme reaches every number the bar is made of**, not only its colour. A
    /// scrollbar themed in its colour and sized from a constant is themed in the half
    /// that shows and unthemed in the half a pointer has to hit.
    ///
    /// There is no per-call override to outrank here — nobody configures a scrollbar at a
    /// call site, the walk draws it — so the chain is `theme ?? framework`, and the second
    /// half of this test is that the framework still answers where the theme says nothing.
    #[test]
    fn a_theme_reaches_every_number_the_scrollbar_is_made_of() {
        const THUMB: Color = Color::rgb(0.2, 0.7, 0.9);
        let mut theme = Theme::dark();
        theme.widgets.scrollbar.thickness = Some(14.0);
        theme.widgets.scrollbar.margin = Some(5.0);
        theme.widgets.scrollbar.min_thumb_length = Some(90.0);
        theme.widgets.scrollbar.radius = Some(2.0);
        theme.widgets.scrollbar.thumb_color = Some(THUMB);
        theme.widgets.scrollbar.opacity = Some(0.8);

        let runtime = Runtime::with_scrollbars(Scrollbars::Always);
        let ui = build_ui(
            &tall().thumb_visibility(true),
            Size::new(200.0, 100.0),
            &runtime,
            &theme,
        );
        // `painted` filters on the strip a bar of the **default** thickness occupies, so
        // it cannot see a themed one — which is the point of the theme. This asks for the
        // strip the themed bar is in.
        let over_there: Vec<(Rect, Color)> = ui
            .scene()
            .primitives()
            .iter()
            .filter_map(|p| match p {
                Primitive::Rect { rect, color, .. } if rect.x >= 200.0 - 14.0 - 5.0 * 2.0 => {
                    Some((*rect, *color))
                }
                _ => None,
            })
            .collect();
        assert_eq!(over_there.len(), 1, "still one rectangle: the thumb");
        let (thumb, color) = over_there[0];
        assert!(
            (thumb.width - 14.0).abs() < 0.01,
            "the theme's thickness: {thumb:?}"
        );
        assert!(
            ((thumb.x + thumb.width) - (200.0 - 5.0)).abs() < 0.01,
            "held clear by the theme's margin, not shrunk to fit: {thumb:?}"
        );
        assert!(
            thumb.height >= 90.0,
            "and never shorter than the theme's floor: {thumb:?}"
        );
        assert_eq!(
            color,
            THUMB.fade(0.8),
            "the theme's colour, faded to the theme's resting level"
        );

        // The radius is not in `painted`, which reads the rectangles' colours; take it
        // from the primitive itself. A pill is what an unthemed bar is, and this one is
        // not a pill.
        let radius = ui.scene().primitives().iter().find_map(|p| match p {
            Primitive::Rect { radius, .. } if radius.top_left > 0.0 => Some(radius.top_left),
            _ => None,
        });
        assert_eq!(radius, Some(2.0), "the theme's corner radius");

        // And with a theme that says nothing, the framework still answers.
        let plain = bars(tall(), Scrollbars::Always);
        let (thumb, color) = plain[0];
        assert!((thumb.width - BAR_SIZE).abs() < 0.01);
        assert_eq!(color, Theme::dark().scheme.on_surface.fade(THUMB_ON_DARK));
    }

    /// **And it is a thumb and nothing else** (`scrollbar.dart:281`): the reference's
    /// track is transparent unless a caller asks for one, and even then it is 3 to 5 %.
    /// This painted an 18 % stripe down every scrolling page, under a 55 % thumb.
    #[test]
    fn a_bar_is_a_thumb_and_no_track() {
        let painted = bars(tall(), Scrollbars::Always);
        assert_eq!(painted.len(), 1, "one rectangle: the thumb");
        let (thumb, color) = painted[0];
        assert!(
            (thumb.width - BAR_SIZE).abs() < 0.01,
            "at the reference's thickness: {thumb:?}"
        );
        assert!(
            ((thumb.x + thumb.width) - (200.0 - BAR_MARGIN)).abs() < 0.01,
            "and clear of the edge by `crossAxisMargin`, not shrunk to fit: {thumb:?}"
        );
        assert!(
            thumb.height >= MIN_THUMB,
            "and never shorter than a pointer can catch: {thumb:?}"
        );
        let theme = Theme::dark();
        assert_eq!(color, theme.scheme.on_surface.fade(THUMB_ON_DARK));
    }

    /// **Along the horizontal axis, never** (`app.dart:861`) — on any platform, under any
    /// setting. A sideways strip is scrolled by whatever made it sideways, and a bar
    /// under it takes room from content that is short of it already.
    #[test]
    fn a_sideways_strip_never_gets_one() {
        let strip = SingleChildScrollView::new()
            .axis(crate::scroll::Axis::Horizontal)
            .width(200.0)
            .height(100.0)
            .child(Container::<()>::new().width(1000.0).height(100.0));
        let runtime = Runtime::with_scrollbars(Scrollbars::Always);
        let ui = build_ui(&strip, Size::new(200.0, 100.0), &runtime, &Theme::dark());
        assert!(
            ui.scrollbars().is_empty(),
            "a desktop draws none across, either"
        );
    }

    /// And **one area may answer for itself**, over the application's answer — the
    /// per-area say the physics beside it already had.
    #[test]
    fn an_area_may_ask_for_its_own_answer() {
        assert_eq!(
            bars(tall().scrollbars(Scrollbars::Always), Scrollbars::Never).len(),
            1,
            "asked for one where the platform gives none"
        );
        assert_eq!(
            bars(tall().scrollbars(Scrollbars::Never), Scrollbars::Always),
            vec![],
            "and refused one where it does"
        );
    }

    /// **A bar nobody has scrolled is not there at all.** The reference's fade starts
    /// closed and is opened only by movement (`scrollbar.dart:1960`); a list that has
    /// just appeared shows its content, not its furniture.
    ///
    /// It is **registered** even so, which a bar the platform does not draw is not. The
    /// difference is real: that one is not there, and this one is here and invisible —
    /// and a mouse coming near it is the only thing that can bring it back.
    #[test]
    fn an_untouched_area_shows_no_bar_but_can_still_be_reached_for() {
        let runtime = Runtime::with_scrollbars(Scrollbars::Always);
        let ui = build_ui(&tall(), Size::new(200.0, 100.0), &runtime, &Theme::dark());
        assert_eq!(painted(&ui), vec![], "nothing is painted for it");

        let bar = *ui.scrollbars().first().expect("registered all the same");
        assert_eq!(bar.opacity, 0.0);
        let on_it = Point::new(194.0, 20.0);
        assert!(
            ui.scrollbar_at(on_it).is_none(),
            "and a bar at zero cannot be grabbed"
        );
        assert!(
            ui.scrollbar_near(on_it).is_some(),
            "but it can be reached for, which is what brings it back"
        );
        // The reach is wider than the bar: 8 pixels at a tenth of an opacity is not
        // something a hand aims at precisely.
        assert!(
            ui.scrollbar_near(Point::new(178.0, 20.0)).is_some(),
            "the reach takes in a tap target's room around the thumb: {:?}",
            bar.reach
        );
    }

    /// **A pinned bar does not fade** (`scrollbar.dart:214`) — for an area whose content
    /// does not look scrollable, or one a reader should be able to aim at without
    /// scrolling first to make the bar appear.
    #[test]
    fn a_pinned_bar_does_not_fade() {
        let runtime = Runtime::with_scrollbars(Scrollbars::Always);
        let ui = build_ui(
            &tall().thumb_visibility(true),
            Size::new(200.0, 100.0),
            &runtime,
            &Theme::dark(),
        );
        assert_eq!(painted(&ui).len(), 1, "there without being scrolled to");
        assert_eq!(ui.scrollbars()[0].opacity, 1.0);
    }

    /// **A thumb under a pointer, and a thumb in a hand**, are two different colours
    /// (`scrollbar.dart:245`, `:244`) — and neither is the resting one. The dragged
    /// value arrives at once: the hand is already on it.
    #[test]
    fn a_thumb_answers_the_pointer() {
        use crate::runtime::ScrollbarFade;
        let build = |prime: &dyn Fn(&mut Runtime)| {
            let mut runtime = Runtime::with_scrollbars(Scrollbars::Always);
            prime(&mut runtime);
            let ui = build_ui(
                &tall().thumb_visibility(true),
                Size::new(200.0, 100.0),
                &runtime,
                &Theme::dark(),
            );
            let id = ui.scrollbars()[0].id;
            (id, painted(&ui)[0].1)
        };

        let theme = Theme::dark();
        let (id, resting) = build(&|_| {});
        assert_eq!(resting, theme.scheme.on_surface.fade(THUMB_ON_DARK));

        let (_, warmed) = build(&|rt| {
            rt.scrollbar_fade.insert(
                id,
                ScrollbarFade {
                    opacity: 1.0,
                    hover: 1.0,
                    ..ScrollbarFade::default()
                },
            );
        });
        assert_eq!(warmed, theme.scheme.on_surface.fade(THUMB_HOVER_ON_DARK));

        let (_, grabbed) = build(&|rt| rt.scrollbar_dragged = Some(id));
        assert_eq!(grabbed, theme.scheme.on_surface.fade(THUMB_DRAG_ON_DARK));
    }

    #[test]
    fn hover_progress_interpolates_color() {
        let rt = Runtime::default();
        let base = build_ui(
            &clickable_sample(),
            Size::new(400.0, 100.0),
            &rt,
            &Theme::default(),
        );
        let id_a = base.hit(Point::new(50.0, 50.0)).unwrap();

        // Without any progress: the base colour (red).
        if let Primitive::Rect { color, .. } = base.scene().primitives()[0] {
            assert_eq!(color, Color::rgb(1.0, 0.0, 0.0));
        } else {
            panic!("expected a rect");
        }

        // Full progress: the hover colour (green).
        let mut rt = Runtime::default();
        rt.input.hovered = Some(id_a);
        rt.anims.insert(
            id_a,
            crate::Anim {
                hover: 1.0,
                ..Default::default()
            },
        );
        let ui = build_ui(
            &clickable_sample(),
            Size::new(400.0, 100.0),
            &rt,
            &Theme::default(),
        );
        if let Primitive::Rect { color, .. } = ui.scene().primitives()[0] {
            assert_eq!(color, Color::rgb(0.0, 1.0, 0.0));
        } else {
            panic!("expected a rect");
        }
    }

    #[test]
    fn multiline_field_registers_as_scrollable_when_overflowing() {
        // A multi-line field whose content exceeds `rows` registers itself as a scrollable
        // area (with `max_y > 0`) — which is what the wheel and the scrollbar target. A short
        // field does not register.
        let tall = TextField::<Msg>::new("a\nb\nc\nd\ne\nf")
            .on_input(Msg::Edited)
            .rows(2)
            .width(200.0);
        let tree: Flex<Msg> = Flex::column().child(tall);
        let rt = Runtime::default();
        let ui = build_ui(&tree, Size::new(220.0, 240.0), &rt, &Theme::default());
        let maxes = ui.scrollable_maxes();
        assert_eq!(maxes.len(), 1, "the overflowing field registers");
        assert!(maxes[0].2 > 0.0, "max_y > 0 (overflowing content)");

        let short = TextField::<Msg>::new("a\nb")
            .on_input(Msg::Edited)
            .rows(4)
            .width(200.0);
        let tree: Flex<Msg> = Flex::column().child(short);
        let ui = build_ui(&tree, Size::new(220.0, 240.0), &rt, &Theme::default());
        assert!(
            ui.scrollable_maxes().is_empty(),
            "a short field does not scroll"
        );
    }

    #[test]
    fn only_text_inputs_place_a_cursor() {
        // The invariant of the click fix (milestone 39): a focusable button returns NO cursor
        // (`cursor_at` = None), so the shell does not start a text selection on it and does not
        // capture the click. Only text fields place one.
        let button = Button::<Msg>::new("x").on_press(Msg::A);
        assert_eq!(Widget::<Msg>::cursor_at(&button, 10.0, 5.0, 200.0, 0), None);
        let input = TextField::<Msg>::new("hi").on_input(Msg::Edited);
        assert!(Widget::<Msg>::cursor_at(&input, 10.0, 5.0, 200.0, 0).is_some());
    }

    /// A form taller than its window: six buttons of 60 px in a 150 px scroll.
    fn long_form() -> SingleChildScrollView<Msg> {
        let mut column = Flex::<Msg>::column();
        for i in 0..6 {
            column = column.child(
                Button::new(format!("field {i}"))
                    .on_press(Msg::A)
                    .height(60.0),
            );
        }
        SingleChildScrollView::new()
            .width(200.0)
            .height(150.0)
            .child(column)
    }

    fn form_ui(runtime: &Runtime) -> Ui<Msg> {
        build_ui(
            &long_form(),
            Size::new(200.0, 150.0),
            runtime,
            &Theme::default(),
        )
    }

    /// **Every** field is a focus stop, not only the two and a half on screen.
    ///
    /// Registering what the eye can see is how a long form came to have most of its
    /// fields unreachable from the keyboard: Tab walked the visible ones and wrapped.
    #[test]
    fn tab_reaches_the_fields_below_the_fold() {
        let ui = form_ui(&Runtime::default());
        assert_eq!(ui.focusables.len(), 6, "all six, not the visible ones");
        // And the traversal is in tree order, so Tab walks down the form.
        let ids: Vec<_> = ui.focusables.iter().map(|f| f.id).collect();
        assert_eq!(ui.focus_next(Some(ids[2]), true), Some(ids[3]));
    }

    /// A stop clipped away by a scroll keeps its **real** box, and an empty visible one.
    /// The two are different questions and the registry answers both.
    #[test]
    fn a_stop_out_of_sight_keeps_its_geometry() {
        let ui = form_ui(&Runtime::default());
        let fifth = ui.focusables[5];
        assert!((fifth.bounds.y - 300.0).abs() < 0.5, "{:?}", fifth.bounds);
        assert_eq!(fifth.rect.height, 0.0, "none of it is on screen");
        assert!(fifth.scroll.is_some(), "something around it scrolls");
    }

    /// A click still lands only on what can be seen. The unclipped box of a field
    /// scrolled out of sight overlaps the window, and a tap there must not focus it.
    #[test]
    fn a_click_still_only_reaches_what_is_visible() {
        let ui = form_ui(&Runtime::default());
        // The second field, in the middle of its own visible box.
        let second = ui.focusables[1];
        let inside = Point::new(
            second.rect.x + second.rect.width / 2.0,
            second.rect.y + second.rect.height / 2.0,
        );
        assert_eq!(ui.focus_hit(inside).map(|(id, _)| id), Some(second.id));
        // The sixth field's **real** box overlaps nothing on screen, and a tap where it
        // would be if the form were not scrolled hits nothing at all.
        let sixth = ui.focusables[5];
        let past = Point::new(
            sixth.bounds.x + sixth.bounds.width / 2.0,
            sixth.bounds.y + sixth.bounds.height / 2.0,
        );
        assert!(past.y > 150.0, "past the fold: {past:?}");
        assert_eq!(ui.focus_hit(past), None);
    }

    /// Focus lands below the fold and the view follows: the least movement that brings
    /// the field's foot to the window's.
    #[test]
    fn revealing_a_stop_below_the_fold_scrolls_to_it() {
        let runtime = Runtime::default();
        let ui = form_ui(&runtime);
        let area = ui.scroll_regions()[0];
        let fifth = ui.focusables[5].id;
        let moves = ui.reveal(fifth, &runtime);
        // Field 5 sits at 300..360 and the window is 150 tall: its foot reaches the
        // window's foot at 360 - 150 = 210.
        assert_eq!(moves, vec![(area.id, (0.0, 210.0))]);
    }

    /// Already in view, nothing moves — the answer is the empty list rather than a
    /// zero, so no caller has to ask twice.
    #[test]
    fn revealing_something_already_in_view_moves_nothing() {
        let runtime = Runtime::default();
        let ui = form_ui(&runtime);
        assert!(ui.reveal(ui.focusables[0].id, &runtime).is_empty());
        assert!(ui.reveal(ui.focusables[1].id, &runtime).is_empty());
        // And a stop the frame does not contain at all is not an error.
        assert!(ui.reveal(WidgetId::from_u64(7), &runtime).is_empty());
    }

    /// Coming back **up** the form scrolls the other way, and only as far as it must.
    #[test]
    fn revealing_a_stop_above_the_fold_scrolls_back() {
        let mut runtime = Runtime::default();
        let area_id = form_ui(&runtime).scroll_regions()[0].id;
        runtime.scroll.insert(area_id, (0.0, 210.0));
        let ui = form_ui(&runtime);
        let first = ui.focusables[0].id;
        // Field 0 sits at 0..60: its head reaches the window's head at offset 0.
        assert_eq!(ui.reveal(first, &runtime), vec![(area_id, (0.0, 0.0))]);
        // At offset 210 the window shows 210..360, so field 4 (240..300) is wholly in
        // it and does not move. Field 3 (180..240) hangs over the top edge and would.
        assert!(ui.reveal(ui.focusables[4].id, &runtime).is_empty());
        assert!(!ui.reveal(ui.focusables[3].id, &runtime).is_empty());
    }

    /// The arithmetic on its own: the least movement, the leading edge for anything too
    /// big to fit, and the clamp at the ends of the travel.
    #[test]
    fn the_reveal_moves_as_little_as_it_can() {
        let area = Scrollable {
            id: WidgetId::ROOT,
            viewport: Rect::new(0.0, 0.0, 100.0, 100.0),
            max_x: 0.0,
            max_y: 400.0,
            physics: None,
            refresh: None,
            page: None,
            reverse_x: false,
            reverse_y: false,
            host: None,
            keep_visible: None,
        };
        // Inside: nothing.
        assert_eq!(
            area.reveal(Rect::new(0.0, 10.0, 50.0, 20.0), (0.0, 0.0)).1,
            (0.0, 0.0)
        );
        // Below: its foot comes to the window's foot, and no further.
        assert_eq!(
            area.reveal(Rect::new(0.0, 140.0, 50.0, 20.0), (0.0, 0.0)).0,
            (0.0, 60.0)
        );
        // Above: its head comes to the window's head.
        assert_eq!(
            area.reveal(Rect::new(0.0, -30.0, 50.0, 20.0), (0.0, 50.0))
                .0,
            (0.0, 20.0)
        );
        // Taller than the window: the **start** edge wins, because that is what is read.
        assert_eq!(
            area.reveal(Rect::new(0.0, -10.0, 50.0, 300.0), (0.0, 40.0))
                .0,
            (0.0, 30.0)
        );
        // And the travel is a wall: an offset past the end is not asked for.
        assert_eq!(
            area.reveal(Rect::new(0.0, 900.0, 50.0, 20.0), (0.0, 0.0)).0,
            (0.0, 400.0)
        );
    }

    /// A reversed axis numbers its offsets from the far end, so the same movement of the
    /// content is the opposite movement of the offset. One function knows that, and the
    /// reveal asks it rather than keeping a second opinion.
    #[test]
    fn the_reveal_follows_a_reversed_axis() {
        let area = Scrollable {
            id: WidgetId::ROOT,
            viewport: Rect::new(0.0, 0.0, 100.0, 100.0),
            max_x: 0.0,
            max_y: 400.0,
            physics: None,
            refresh: None,
            page: None,
            reverse_x: false,
            reverse_y: true,
            host: None,
            keep_visible: None,
        };
        // A box below the window: the content must move **up** by 60 either way. On a
        // reversed axis a rising offset pushes the content down (`content_origin` is
        // `viewport - content + offset` there), so the offset comes **down** by 60 to do
        // what a plain axis would need it to go up by.
        let (offset, shift) = area.reveal(Rect::new(0.0, 140.0, 50.0, 20.0), (0.0, 100.0));
        assert_eq!(shift, (0.0, -60.0));
        assert_eq!(offset, (0.0, 40.0));
    }

    /// Centring puts the box in the middle of the window, and the clamp is what keeps
    /// the first and last items of a row where they belong rather than half off it.
    #[test]
    fn centring_is_clamped_to_the_travel() {
        let area = Scrollable {
            id: WidgetId::ROOT,
            viewport: Rect::new(0.0, 0.0, 300.0, 50.0),
            max_x: 700.0,
            max_y: 0.0,
            physics: None,
            refresh: None,
            page: None,
            reverse_x: false,
            reverse_y: false,
            host: None,
            keep_visible: None,
        };
        // A box at 400..500 has its middle at 450; the window's is at 150.
        assert_eq!(
            area.centre(Rect::new(400.0, 0.0, 100.0, 50.0), (0.0, 0.0))
                .0,
            (300.0, 0.0)
        );
        // The first item cannot be centred without scrolling backwards, so it stays.
        assert_eq!(
            area.centre(Rect::new(0.0, 0.0, 100.0, 50.0), (0.0, 0.0)).0,
            (0.0, 0.0)
        );
        // Nor the last past the end of the travel.
        assert_eq!(
            area.centre(Rect::new(900.0, 0.0, 100.0, 50.0), (0.0, 0.0))
                .0,
            (700.0, 0.0)
        );
    }

    /// **A lone child could widen the box it was given, and take the screen with it.**
    ///
    /// A flex item's automatic minimum is its **min-content** size, so agreeing to shrink
    /// buys nothing on its own: the item shrinks willingly and then refuses to go below
    /// the widest thing inside it. A column holding one over-wide row came out at that
    /// row's width; the padded box around it came out at the same; and every sibling,
    /// stretched across the column, came out at the same again — a whole screen laid out
    /// to the width of its widest line and then clipped by the window.
    ///
    /// Reported from a real application: a shop whose banner, search field, filter row
    /// and product grid were all cut off at the same edge, because one segmented control
    /// four segments wide had decided how wide the screen was.
    ///
    /// The over-wide child still overflows — that is the reference's behaviour and the
    /// honest one — but it no longer drags its parent and its siblings out with it.
    #[test]
    fn a_lone_child_cannot_widen_the_box_it_was_given() {
        let ordinary = Color::rgb(0.1, 0.2, 0.3);
        let overwide = Color::rgb(0.9, 0.8, 0.7);
        let screen: SingleChildScrollView<Msg> = SingleChildScrollView::new().width(300.0).child(
            Container::new().padding(24.0).child(
                Flex::column()
                    .align(frus_layout::Align::Stretch)
                    .child(Container::new().height(20.0).color(ordinary))
                    .child(Container::new().width(600.0).height(20.0).color(overwide)),
            ),
        );
        let ui = build_ui(
            &screen,
            Size::new(300.0, 800.0),
            &Runtime::default(),
            &Theme::default(),
        );
        let width_of = |wanted: Color| {
            ui.scene()
                .primitives()
                .iter()
                .find_map(|p| match p {
                    Primitive::Rect { color, rect, .. } if *color == wanted => Some(rect.width),
                    _ => None,
                })
                .expect("the box is drawn")
        };
        // 300 less the padding either side, and not 600.
        assert_eq!(width_of(ordinary), 252.0);
        // The one that asked to be too wide still is: it overflows rather than being
        // squeezed, and rather than resizing everything around it.
        assert_eq!(width_of(overwide), 600.0);
    }

    #[test]
    fn tab_cycles_focusables_in_order() {
        let tree = Flex::<Msg>::column()
            .child(Button::new("un").on_press(Msg::A))
            .child(Button::new("deux").on_press(Msg::B));
        let ui = build_ui(
            &tree,
            Size::new(200.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );
        assert_eq!(ui.focusables.len(), 2, "both buttons are focusable");
        let first = ui.focusables[0].id;
        let second = ui.focusables[1].id;

        // With no focus: Tab -> first, Shift+Tab -> last.
        assert_eq!(ui.focus_next(None, true), Some(first));
        assert_eq!(ui.focus_next(None, false), Some(second));
        // Wrap-around.
        assert_eq!(ui.focus_next(Some(first), true), Some(second));
        assert_eq!(ui.focus_next(Some(second), true), Some(first));
        assert_eq!(ui.focus_next(Some(first), false), Some(second));
    }

    #[test]
    fn focus_ring_for_button_not_for_textinput() {
        let theme = Theme::default();
        let ring = theme.focus.fade(0.4); // focus_progress = 0 → alpha 0.4
        let count_ring = |tree: &dyn Widget<Msg>, keyboard: bool| -> usize {
            let mut rt = Runtime::default();
            let probe = build_ui(tree, Size::new(200.0, 200.0), &rt, &theme);
            rt.input.focused = probe.focusables.first().map(|f| f.id);
            rt.focus_visible = keyboard;
            let ui = build_ui(tree, Size::new(200.0, 200.0), &rt, &theme);
            ui.scene()
                .primitives()
                .iter()
                .filter(
                    |p| matches!(p, Primitive::Rect { border_color, .. } if *border_color == ring),
                )
                .count()
        };
        let with_button = Flex::<Msg>::column().child(Button::new("x").on_press(Msg::A));
        assert!(
            count_ring(&with_button, true) >= 1,
            "a button focused with the keyboard has a generic ring"
        );
        // Focus taken with the pointer: no ring (FocusHighlightMode).
        assert_eq!(
            count_ring(&with_button, false),
            0,
            "a click does not flash a ring"
        );

        let with_input = Flex::<Msg>::column().child(TextField::new("hi").on_input(Msg::Edited));
        assert_eq!(
            count_ring(&with_input, true),
            0,
            "the field draws its own focus"
        );
    }

    #[test]
    fn arrow_focus_navigates_geometrically() {
        // A 2×2 grid of buttons; each target is identified by its message.
        let grid: Flex<Msg> = Flex::column()
            .child(
                Flex::row()
                    .child(Button::new("a").on_press(Msg::A))
                    .child(Button::new("b").on_press(Msg::B)),
            )
            .child(
                Flex::row()
                    .child(Button::new("c").on_press(Msg::C))
                    .child(Button::new("d").on_press(Msg::D)),
            );
        let ui = build_ui(
            &grid,
            Size::new(300.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );
        let top_left = ui.focus_next(None, true).expect("premier focusable");
        assert_eq!(ui.msg_for(top_left), Some(Msg::A));

        // Right: a → b; down: a → c; and nothing to the left of a.
        let right = ui
            .focus_directional(top_left, FocusDirection::Right)
            .expect("to the right");
        assert_eq!(ui.msg_for(right), Some(Msg::B));
        let down = ui
            .focus_directional(top_left, FocusDirection::Down)
            .expect("downwards");
        assert_eq!(ui.msg_for(down), Some(Msg::C));
        assert_eq!(ui.focus_directional(top_left, FocusDirection::Left), None);
        // The diagonal is kept in check: from b, down → d (aligned), not c.
        let down_right = ui
            .focus_directional(right, FocusDirection::Down)
            .expect("down from b");
        assert_eq!(ui.msg_for(down_right), Some(Msg::D));
    }

    #[test]
    fn keyed_identity_survives_middle_removal() {
        let colored = |c: Color| Container::<Msg>::new().width(50.0).height(20.0).color(c);
        let red = Color::rgb(1.0, 0.0, 0.0);
        let green = Color::rgb(0.0, 1.0, 0.0);
        let blue = Color::rgb(0.0, 0.0, 1.0);

        let owner_of = |ui: &Ui<Msg>, c: Color| -> u64 {
            ui.scene()
                .primitives()
                .iter()
                .find_map(|p| match p {
                    Primitive::Rect { color, owner, .. } if *color == c => Some(*owner),
                    _ => None,
                })
                .expect("the primitive is there")
        };

        // The list [red(key 1), green(key 2), blue(key 3)].
        let full = Flex::<Msg>::column()
            .child(Keyed::new(1u64, colored(red)))
            .child(Keyed::new(2u64, colored(green)))
            .child(Keyed::new(3u64, colored(blue)));
        let ui_full = build_ui(
            &full,
            Size::new(200.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );

        // The list [red(1), blue(3)]: the green in the middle is removed → blue goes from index 2 to 1.
        let removed = Flex::<Msg>::column()
            .child(Keyed::new(1u64, colored(red)))
            .child(Keyed::new(3u64, colored(blue)));
        let ui_removed = build_ui(
            &removed,
            Size::new(200.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );

        // Blue's identity (owner, key 3) is UNCHANGED despite the shift in position.
        assert_eq!(owner_of(&ui_full, blue), owner_of(&ui_removed, blue));

        // Without a key, the 2nd child's positional identity DOES change (index 2 vs 1).
        let unkeyed_full = Flex::<Msg>::column()
            .child(colored(red))
            .child(colored(green))
            .child(colored(blue));
        let unkeyed_removed = Flex::<Msg>::column()
            .child(colored(red))
            .child(colored(blue));
        let u1 = build_ui(
            &unkeyed_full,
            Size::new(200.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );
        let u2 = build_ui(
            &unkeyed_removed,
            Size::new(200.0, 200.0),
            &Runtime::default(),
            &Theme::default(),
        );
        assert_ne!(owner_of(&u1, blue), owner_of(&u2, blue));
    }

    #[test]
    fn center_overlay_scrim_click_dismisses() {
        // A Center modal with `.dismiss`: clicking the scrim (outside the content) returns the
        // dismissal message; clicking the content does not.
        let modal = Container::<Msg>::new()
            .width(100.0)
            .height(60.0)
            .color(Color::WHITE);
        let portal: OverlayPortal<Msg> =
            OverlayPortal::new(Container::<Msg>::new().width(20.0).height(20.0))
                .overlay(modal, Placement::Center)
                .dismiss(Msg::A);
        let ui = build_ui(
            &portal,
            Size::new(400.0, 300.0),
            &Runtime::default(),
            &Theme::default(),
        );

        // The top-left corner: on the scrim → it dismisses.
        let corner = ui.hit(Point::new(5.0, 5.0)).expect("a clickable scrim");
        assert_eq!(ui.msg_for(corner), Some(Msg::A));
    }

    /// **The shell's mark reaches the field** (milestone 511): a focused field whose
    /// selection the runtime marks as a touch one paints its two handles; the same
    /// selection unmarked paints none, and so does a marked field that lost the focus.
    #[test]
    fn a_touch_selection_reaches_the_field_as_handles() {
        let tree = Flex::column().width(300.0).height(80.0).child(
            TextField::new("hello world")
                .width(200.0)
                .on_input(Msg::Edited),
        );
        let theme = Theme::default();
        let size = Size::new(300.0, 80.0);
        let (id, _) = build_ui(&tree, size, &Runtime::default(), &theme)
            .focus_hit(Point::new(10.0, 10.0))
            .expect("the field");
        let handles = |focused: bool, marked: bool| {
            let mut rt = Runtime::default();
            rt.edits.insert(
                id,
                Edit {
                    cursor: 11,
                    anchor: Some(6),
                    composing: None,
                },
            );
            rt.input.focused = focused.then_some(id);
            rt.selection_handles = marked.then_some(id);
            let ui = build_ui(&tree, size, &rt, &theme);
            ui.scene()
                .primitives()
                .iter()
                .filter(|p| {
                    matches!(p, Primitive::Path { fill: Some(c), .. } if *c == theme.scheme.primary)
                })
                .count()
        };
        assert_eq!(handles(true, true), 2);
        assert_eq!(handles(true, false), 0, "a selection made with a mouse");
        assert_eq!(handles(false, true), 0, "a field left behind");
    }

    /// A wrapper that fuses with its field shares its identity, so it is the wrapper the
    /// shell asks for the handles — and a wrapper that forgot to pass the question on
    /// would leave a finger nothing to take (the three silent bugs `Responsive` has
    /// already cost, milestones 477 to 495).
    #[test]
    fn the_wrappers_that_fuse_with_a_field_pass_its_handles_on() {
        let field = || TextField::<Msg>::new("hello world").width(200.0);
        let edit = Edit {
            cursor: 11,
            anchor: Some(6),
            composing: None,
        };
        let direct = Widget::<Msg>::selection_handles(&field(), 200.0, &edit, 0.0);
        assert!(direct.is_some());
        let keyed = crate::Keyed::new(1, field());
        let responsive = crate::Responsive::new(crate::SizeClass::Compact).compact(field());
        let boxed: Box<dyn Widget<Msg>> = Box::new(field());
        assert_eq!(keyed.selection_handles(200.0, &edit, 0.0), direct);
        assert_eq!(responsive.selection_handles(200.0, &edit, 0.0), direct);
        assert_eq!(boxed.selection_handles(200.0, &edit, 0.0), direct);
    }

    /// **A field knows the form it is part of** (milestone 512): the stops inside one
    /// [`crate::AutofillGroup`] are that form, in tree order, whichever of them asks; two
    /// groups side by side are two forms; a field in no group is a form of one; and a
    /// group sits in the focus registry, so a cached subtree replays it like any stop.
    #[test]
    fn a_field_knows_the_form_it_is_part_of() {
        use crate::{AutofillGroup, AutofillHint};
        let field = |value: &str, hint: AutofillHint| {
            TextField::new(value)
                .width(200.0)
                .on_input(Msg::Edited)
                .autofill([hint])
        };
        let tree = Flex::column()
            .width(300.0)
            .height(400.0)
            .child(AutofillGroup::new(
                Flex::column()
                    .child(field("someone", AutofillHint::Username))
                    .child(field("secret", AutofillHint::Password)),
            ))
            .child(AutofillGroup::new(field(
                "123456",
                AutofillHint::OneTimeCode,
            )))
            .child(TextField::new("search").width(200.0).on_input(Msg::Edited));
        let ui = build_ui(
            &tree,
            Size::new(300.0, 400.0),
            &Runtime::default(),
            &Theme::default(),
        );
        let ids: Vec<WidgetId> = ui.focusable_ids().collect();
        assert_eq!(ids.len(), 4);
        let form = |id: WidgetId| ui.form_of(id).iter().map(|(f, _)| *f).collect::<Vec<_>>();
        assert_eq!(form(ids[0]), vec![ids[0], ids[1]], "the sign-in pair");
        assert_eq!(
            form(ids[1]),
            vec![ids[0], ids[1]],
            "whichever of the two asks"
        );
        assert_eq!(
            form(ids[2]),
            vec![ids[2]],
            "a second group is a second form"
        );
        assert_eq!(
            form(ids[3]),
            vec![ids[3]],
            "a field in no group is a form of one"
        );
        assert!(ui.form_of(WidgetId::from_u64(7)).is_empty());
        // The two groups are told apart by identity, and a lone field has none.
        let (first, second) = (ui.form_group(ids[0]), ui.form_group(ids[2]));
        assert!(first.is_some() && second.is_some() && first != second);
        assert_eq!(ui.form_group(ids[3]), None);
        assert_eq!(ui.group_stops(first.unwrap()).len(), 2);
        // Each stop carries its box, which is what the platform anchors its offer to.
        assert!(ui.form_of(ids[1]).iter().all(|(_, r)| r.height > 0.0));
    }

    #[test]
    fn find_widget_and_edit_types() {
        let tree = Flex::column()
            .width(300.0)
            .height(80.0)
            .child(TextField::new("hi").width(200.0).on_input(Msg::Edited));
        let rt = Runtime::default();
        let ui = build_ui(&tree, Size::new(300.0, 80.0), &rt, &Theme::default());
        let (id, _rect) = ui.focus_hit(Point::new(10.0, 10.0)).expect("the field");

        let widget = find_widget(&tree, id).expect("the widget was found");
        let mut edit = Edit {
            cursor: 2,
            anchor: None,
            composing: None,
        };
        assert_eq!(
            widget.on_edit(&mut edit, &Key::Text("!".to_string())),
            Some(Msg::Edited("hi!".to_string()))
        );
    }

    #[test]
    fn a_traversal_can_arrive_before_the_layout_pass() {
        // Milestone 415. A `ThemeBuilder`'s subtree does not exist until something has
        // called `build_themed` on it, and `children()` says so in its own doc: "a
        // traversal that arrives first should call `build_themed`, not this".
        //
        // The shell has such a traversal. On a **burst of keystrokes** — a software
        // keyboard, `adb input text`, auto-repeat — it rebuilds the tree from `view` alone
        // and reads it immediately, with no layout pass in between, so every deferred
        // subtree in it is empty and every widget inside one is unreachable.
        let deferred = |value: &str| {
            let value = value.to_string();
            crate::ThemeBuilder::new(move |_: &Theme| {
                TextField::new(value.clone())
                    .width(200.0)
                    .on_input(Msg::Edited)
            })
        };
        let laid_out = Flex::column()
            .width(300.0)
            .height(80.0)
            .child(deferred("hi"));
        let rt = Runtime::default();
        let ui = build_ui(&laid_out, Size::new(300.0, 80.0), &rt, &Theme::default());
        let (id, _) = ui.focus_hit(Point::new(10.0, 10.0)).expect("the field");
        assert!(
            find_widget(&laid_out, id).is_some(),
            "after a layout pass the field is where the hit-test said it was"
        );

        // The same tree, freshly built and not yet laid out. `build_deferred` is what the
        // layout pass does on its way down, and nothing else.
        let fresh = Flex::column()
            .width(300.0)
            .height(80.0)
            .child(deferred("hi"));
        build_deferred(&fresh, &Theme::default(), &Runtime::default());
        assert!(
            find_widget(&fresh, id).is_some(),
            "prepared the same way, the same traversal reaches the same widget"
        );
    }

    #[test]
    #[should_panic(expected = "before it was built")]
    fn reading_an_unbuilt_deferred_subtree_trips_the_wire() {
        // Without the preparation the traversal used to return `None` and the caller
        // shrugged: no field found, no caret revealed, nothing said. The failure mode was
        // **silence**, so the guard is a panic in debug rather than a comment.
        let fresh =
            Flex::<Msg>::column()
                .width(300.0)
                .height(80.0)
                .child(crate::ThemeBuilder::new(|_: &Theme| {
                    Container::<Msg>::new().width(10.0).height(10.0)
                }));
        let _ = find_widget(&fresh, WidgetId::ROOT.child(9));
    }

    #[test]
    fn a_deferred_subtree_is_built_under_its_own_theme() {
        // The layout pass swaps the theme before it builds (`theme_override`), so a
        // builder inside a `Themed` sees the subtree's theme and not the frame's.
        // `build_deferred` has to make the same swap or it would build the wrong subtree
        // — and being *nearly* the walk is worse than not being it at all.
        let seen = std::rc::Rc::new(std::cell::Cell::new(0.0f32));
        let recorder = {
            let seen = seen.clone();
            crate::ThemeBuilder::new(move |theme: &Theme| {
                seen.set(theme.radius);
                Container::<Msg>::new().width(10.0).height(10.0)
            })
        };
        let inner = Theme {
            radius: 99.0,
            ..Theme::default()
        };
        let tree = Flex::<Msg>::column().child(crate::Themed::new(inner, recorder));
        build_deferred(&tree, &Theme::default(), &Runtime::default());
        assert_eq!(seen.get(), 99.0, "the subtree's theme, not the frame's");
    }

    #[test]
    fn find_by_key_resolves_a_keyed_field_to_its_focus_id() {
        // Two named fields: `find_by_key` finds each one's focus identity (the one the
        // hit-test would assign), and it tells the keys apart.
        fn hash(k: &str) -> u64 {
            use std::hash::{Hash, Hasher};
            let mut h = std::collections::hash_map::DefaultHasher::new();
            k.hash(&mut h);
            h.finish()
        }
        let tree: Flex<Msg> = Flex::column()
            .child(Keyed::new(
                "email",
                TextField::new("").on_input(Msg::Edited),
            ))
            .child(Keyed::new(
                "password",
                TextField::new("").on_input(Msg::Edited),
            ));

        let email = find_by_key(&tree, hash("email")).expect("email was found");
        let password = find_by_key(&tree, hash("password")).expect("password was found");
        assert_ne!(email, password, "distinct keys → distinct identities");
        // The identity resolved is indeed the by-key identity (stable, independent of the
        // position).
        assert_eq!(email, WidgetId::ROOT.keyed(hash("email")));
        assert!(
            find_by_key(&tree, hash("absent")).is_none(),
            "an unknown key → None"
        );

        // And above all: it is **exactly** the identity the focus hit-test would assign to
        // that field — so setting this focus really does route to it.
        let rt = Runtime::default();
        let ui = build_ui(&tree, Size::new(300.0, 200.0), &rt, &Theme::default());
        let (hit_id, _) = ui
            .focus_hit(Point::new(10.0, 10.0))
            .expect("the email field under the cursor");
        assert_eq!(email, hit_id, "find_by_key == the field's focus identity");
    }

    #[test]
    fn ink_is_painted_over_the_surface_and_under_its_child() {
        use crate::ink::InkWell;
        let tree = Container::<Msg>::new().width(120.0).height(60.0).child(
            InkWell::<Msg>::new().radius(8.0).on_click(Msg::A).child(
                Container::<Msg>::new()
                    .width(120.0)
                    .height(60.0)
                    .color(frus_core::Color::WHITE),
            ),
        );
        let size = Size::new(120.0, 60.0);

        // Dry: the well paints nothing of its own.
        let rt = Runtime::default();
        let dry = build_ui(&tree, size, &rt, &Theme::default());
        let plain = dry.scene.len();
        let id = dry.inks.first().expect("the well registered its box").0;
        assert_eq!(
            dry.ink_box(id).map(|r| (r.width, r.height)),
            Some((120.0, 60.0)),
            "the registry carries the **whole** box, which is what sizes the splash"
        );

        // A finger lands in the top-left corner, and is still down.
        let mut rt = Runtime::default();
        rt.input.pressed = Some(id);
        rt.ink_press(id, Point::new(10.0, 10.0), Size::new(120.0, 60.0));
        rt.advance_ink(1.0 / 60.0);
        let ui = build_ui(&tree, size, &rt, &Theme::default());
        assert_eq!(ui.scene.len(), plain + 1, "the splash adds one layer");

        // It is a shape-clipped layer, so the ink cannot escape the rounded corners…
        let (index, clip_shape) = ui
            .scene
            .primitives()
            .iter()
            .enumerate()
            .find_map(|(i, p)| match p {
                frus_core::Primitive::Layer { clip_shape, .. } => Some((i, clip_shape.clone())),
                _ => None,
            })
            .expect("the ink is a composited layer");
        assert_eq!(clip_shape, frus_core::ClipShape::RRect(8.0.into()));

        // …and it is painted **before** the child that sits on top of it: the ink is
        // under the content, the way a material surface holds it.
        let child_index = ui
            .scene
            .primitives()
            .iter()
            .rposition(|p| matches!(p, frus_core::Primitive::Rect { .. }))
            .expect("the child painted a rectangle");
        assert!(
            index < child_index,
            "ink at {index} must come before the content at {child_index}"
        );
    }

    #[test]
    fn a_splash_left_unconfirmed_does_not_wait_for_ever() {
        // The finger came down and never came back up on this widget — it slid off, or
        // the widget went away mid-press. Nothing will ever confirm the splash, and
        // without the sweep in `advance_ink` the ink would sit there for good.
        let mut rt = Runtime::default();
        let id = WidgetId::from_u64(42);
        rt.input.pressed = Some(id);
        rt.ink_press(id, Point::new(5.0, 5.0), Size::new(100.0, 40.0));
        // Held for a fifth of a second: the ink is up, and it stays up.
        for _ in 0..12 {
            rt.advance_ink(1.0 / 60.0);
        }
        assert!(rt.ink.contains_key(&id), "the splash waits for the finger");

        // The finger is gone and nothing confirmed the tap.
        rt.input.pressed = None;
        let mut frames = 0;
        while rt.advance_ink(1.0 / 60.0) && frames < 200 {
            frames += 1;
        }
        assert!(rt.ink.is_empty(), "the ink is gone after {frames} frames");
        assert!(frames <= 6, "and quickly: a cancel is 75 ms, took {frames}");
    }

    #[test]
    fn an_overscroll_glow_is_painted_over_its_scroll_area() {
        let tree = SingleChildScrollView::<Msg>::new()
            .width(200.0)
            .height(100.0)
            .child(Container::<Msg>::new().width(100.0).height(400.0));
        let size = Size::new(200.0, 100.0);

        // Quiet: nothing extra is drawn.
        let rt = Runtime::default();
        let plain = build_ui(&tree, size, &rt, &Theme::default()).scene.len();

        // A fling has just landed on the bottom edge.
        let mut rt = Runtime::default();
        let id = build_ui(&tree, size, &rt, &Theme::default()).scroll_regions()[0].id;
        rt.glow_absorb(id, crate::overscroll::GlowEdge::Bottom, 4000.0);
        rt.advance_glow(0.02);
        let ui = build_ui(&tree, size, &rt, &Theme::default());
        assert_eq!(
            ui.scene.len(),
            plain + 1,
            "the glow adds exactly one shape to the frame"
        );
        // The glow sits under the scrollbars, so it is not the last primitive: it is
        // the only filled path in the frame.
        let clip = ui
            .scene
            .primitives()
            .iter()
            .find_map(|p| match p {
                frus_core::Primitive::Path { clip, .. } => Some(*clip),
                _ => None,
            })
            .expect("the glow is a filled path");
        // Drawn against the bottom of the viewport, and inside it.
        assert!(
            (clip.y + clip.height - 100.0).abs() < 1.0,
            "clip = {clip:?}"
        );
        assert!(clip.width <= 200.0 + 1e-3);
    }

    #[test]
    fn a_scroll_area_carries_its_physics_into_the_registry() {
        let content = Container::<Msg>::new().width(100.0).height(400.0);
        // Unset: the region says nothing and the application decides.
        let plain = SingleChildScrollView::new()
            .width(200.0)
            .height(100.0)
            .child(content);
        let rt = Runtime::default();
        let ui = build_ui(&plain, Size::new(200.0, 100.0), &rt, &Theme::default());
        assert_eq!(ui.scroll_regions()[0].physics, None);
        assert_eq!(
            ui.scroll_regions()[0].physics_or(ScrollPhysics::Clamping),
            ScrollPhysics::Clamping,
            "an area with no opinion follows the application"
        );

        // Set: the area's own choice wins over the application's.
        let bouncy = SingleChildScrollView::new()
            .width(200.0)
            .height(100.0)
            .physics(ScrollPhysics::BOUNCING)
            .child(Container::<Msg>::new().width(100.0).height(400.0));
        let ui = build_ui(&bouncy, Size::new(200.0, 100.0), &rt, &Theme::default());
        let area = ui.scroll_regions()[0];
        assert_eq!(area.physics, Some(ScrollPhysics::BOUNCING));
        assert_eq!(
            area.physics_or(ScrollPhysics::Clamping),
            ScrollPhysics::BOUNCING
        );
        // And the metrics it hands the physics describe the right axis.
        let metrics = area.metrics_y(10.0);
        assert_eq!(metrics.pixels, 10.0);
        assert_eq!(metrics.max, 300.0); // 400 of content in a 100 viewport
        assert_eq!(metrics.viewport, 100.0);
    }

    #[test]
    fn scroll_translates_and_clips_content() {
        let content = Flex::<Msg>::column()
            .gap(0.0)
            .child(
                Container::new()
                    .height(60.0)
                    .color(Color::rgb(1.0, 0.0, 0.0)),
            )
            .child(
                Container::new()
                    .height(60.0)
                    .color(Color::rgb(0.0, 1.0, 0.0)),
            )
            .child(
                Container::new()
                    .height(60.0)
                    .color(Color::rgb(0.0, 0.0, 1.0)),
            );
        let tree = SingleChildScrollView::new()
            .width(200.0)
            .height(100.0)
            .child(content);

        let rt = Runtime::default();
        let ui = build_ui(&tree, Size::new(200.0, 100.0), &rt, &Theme::default());
        let area = ui.scrollables[0];
        let sid = area.id;
        assert_eq!(area.max_y, 80.0); // 180 - 100
        assert_eq!(area.max_x, 0.0);
        assert_eq!(ui.first_rect().0.y, 0.0);
        assert_eq!(ui.first_rect().1, Rect::new(0.0, 0.0, 200.0, 100.0));

        let mut rt = Runtime::default();
        rt.scroll.insert(sid, (0.0, 50.0));
        let ui2 = build_ui(&tree, Size::new(200.0, 100.0), &rt, &Theme::default());
        assert_eq!(ui2.first_rect().0.y, -50.0);
    }

    #[test]
    fn kanban_cards_are_reorderable_without_being_clickable() {
        use crate::Kanban;
        let board = Kanban::new(|_, _, _, _| Msg::A).column("To do", ["Card A"]);
        let rt = Runtime::default();
        let ui = build_ui(&board, Size::new(400.0, 300.0), &rt, &Theme::default());
        // The card **and** the drop zone are registered as reorderables.
        assert!(
            ui.reorderables.len() >= 2,
            "the card + the drop zone are in the reorderables registry"
        );
        // A point on the card can be **picked up** (it is reorderable) but is **not clickable**
        // — which is the whole point of the registry: without it, `ui.hit` alone would never
        // find the card.
        let (card_id, card) = ui.reorderables[0];
        let p = Point::new(card.x + 5.0, card.y + 5.0);
        assert!(
            ui.reorderable_at(p).is_some(),
            "the card can be picked up at that point"
        );
        assert!(
            ui.hit(p).is_none(),
            "…but it is not clickable (absent from the hit registry)"
        );
        // `widget_rect` must find the card **through the reorderable fallback** (it is not
        // focusable): otherwise the shell's vertical drag preview never starts.
        assert_eq!(
            ui.widget_rect(card_id),
            Some(card),
            "widget_rect falls back to the reorderables registry"
        );
    }

    #[test]
    fn reorderables_inside_a_scroll_are_still_registered() {
        // The milestone 258/260 scenario: the board (with its reorderable cards) is **wrapped
        // in a `SingleChildScrollView`**. The reorderables must stay registered — otherwise dragging a card
        // stops engaging as soon as the board scrolls.
        use crate::{Axis, Kanban, SingleChildScrollView};
        let board = Kanban::new(|_, _, _, _| Msg::A).column("To do", ["Card A"]);
        let scrolled = SingleChildScrollView::new()
            .axis(Axis::Horizontal)
            .width(400.0)
            .height(300.0)
            .child(board);
        let rt = Runtime::default();
        let ui = build_ui(&scrolled, Size::new(400.0, 300.0), &rt, &Theme::default());
        assert!(
            ui.reorderables.len() >= 2,
            "the card + the drop zone stay reorderable even inside a SingleChildScrollView (got {})",
            ui.reorderables.len()
        );
    }

    #[test]
    fn reorderables_inside_a_per_column_card_scroll_are_still_registered() {
        // Milestone 264: `card_area_height` puts each column's cards inside a **vertical
        // `SingleChildScrollView` with an explicit height**. This is exactly the case that *collapsed* at
        // milestone 263 (a flex scroll with no defined ancestor height → cards clipped to zero
        // and no longer reorderable). With a **defined** height the visible cards must stay
        // registered as reorderables — a guard against a regression of per-column dragging.
        use crate::Kanban;
        let board = Kanban::new(|_, _, _, _| Msg::A)
            .card_area_height(220.0)
            .column("To do", ["Card A", "Card B"]);
        let rt = Runtime::default();
        let ui = build_ui(&board, Size::new(400.0, 300.0), &rt, &Theme::default());
        assert!(
            ui.reorderables.len() >= 3,
            "2 cards + the drop zone stay reorderable inside a vertical scroll with a defined height \
             (got {})",
            ui.reorderables.len()
        );
    }

    #[test]
    fn scrollable_columns_fill_the_board_height_then_scroll() {
        // Milestone 266: `Kanban::scrollable_columns()` makes the columns **fill** the board's
        // height (laid out in an ancestor with a defined height), and each column scrolls its
        // cards vertically **with no explicit height** (the flex does the arithmetic, so the
        // milestone 264 stopgap is gone). This checks that at least one column has a vertical
        // `SingleChildScrollView` whose viewport **fills** the height (far more than the default 200) and
        // **scrolls** (max_y > 0), which is the proof of fill-then-scroll.
        use crate::{Axis, Container, Flex, Kanban, SingleChildScrollView};
        // Enough cards to **overflow** the filled viewport (otherwise max_y = 0: nothing to scroll).
        let long: Vec<String> = (0..24).map(|i| format!("card {i}")).collect();
        let board = Kanban::new(|_, _, _, _| Msg::A)
            .scrollable_columns()
            .column("To do", long);
        // `board_screen`'s nesting: the board inside a **plain `Container` with padding** (the
        // visual margin), itself inside a horizontal `flex(1)` SingleChildScrollView, inside a screen (a Flex
        // column) of bounded height. That `Auto` `Container` **collapsed** at milestone 266
        // (hence the `Flex` `flex(1)` workaround); since `compute_scroll` **fills the
        // constrained axis**, it fills the viewport's height and the board follows — no filler
        // container needed any more.
        let padded = Container::<Msg>::new().padding(24.0).child(board);
        let scroll_h = SingleChildScrollView::new()
            .axis(Axis::Horizontal)
            .width(360.0)
            .flex(1.0)
            .child(padded);
        let root: Flex<Msg> = Flex::column().width(400.0).height(600.0).child(scroll_h);
        let ui = build_ui(
            &root,
            Size::new(400.0, 600.0),
            &Runtime::default(),
            &Theme::default(),
        );
        // A column's **vertical** scroll: a tall viewport (it fills) and it scrolls.
        let filled = ui
            .scrollables
            .iter()
            .any(|area| area.viewport.height > 300.0 && area.max_y > 0.0);
        assert!(
            filled,
            "a column fills the board's height then scrolls (scrollables: {:?})",
            ui.scrollables
        );
    }

    #[test]
    fn subtree_ids_covers_a_widget_and_its_descendants() {
        use crate::Text;
        // Root (Container) > Flex(column) > [Text, Text].
        let tree: Container<Msg> = Container::new().child(
            Flex::<Msg>::column()
                .child(Text::new("a"))
                .child(Text::new("b")),
        );
        let all = collect_ids(&tree);
        // From the root: identical to `collect_ids` (the same positional walk).
        assert_eq!(subtree_ids(&tree, WidgetId::ROOT), all);
        // A child's subtree starts with its own identity and stays a **strict** subset of the
        // tree (which is how a rich card's ghost captures all of its content).
        let flex_id = all[1];
        let sub = subtree_ids(Widget::children(&tree)[0].as_ref(), flex_id);
        assert_eq!(
            sub[0], flex_id,
            "the subtree starts with the identity supplied"
        );
        assert!(
            sub.len() < all.len() && sub.iter().all(|i| all.contains(i)),
            "a subset of the tree including the descendants"
        );
    }

    impl<Msg: Clone> Ui<Msg> {
        fn first_rect(&self) -> (Rect, Rect) {
            for primitive in self.scene.primitives() {
                if let Primitive::Rect { rect, clip, .. } = primitive {
                    return (*rect, *clip);
                }
            }
            panic!("no rect at all");
        }
    }

    /// A static subtree under `RepaintBoundary` (mixed content: text + boxes) — enough to
    /// produce several primitives.
    fn boundary_tree() -> Container<Msg> {
        use crate::Text;
        Container::new().repaint_boundary().child(
            Flex::<Msg>::column()
                .child(Text::new("Statique"))
                .child(Container::new().width(30.0).height(20.0).on_click(Msg::A))
                .child(Button::new("ok").on_press(Msg::B)),
        )
    }

    #[test]
    fn repaint_boundary_reuses_a_static_subtree_bit_identical() {
        let tree = boundary_tree();
        let size = Size::new(200.0, 200.0);
        let theme = Theme::default();
        let rt = Runtime::default();

        // Frame 1: nothing cached → 1 miss (a full paint), the subtree is captured.
        let ui1 = build_ui(&tree, size, &rt, &theme);
        // The **primitives** are what is compared (the scene's transient ambient state — the
        // current clip/owner — is not rendered).
        let dbg1 = format!("{:?}", ui1.scene().primitives());
        assert_eq!(rt.paint_cache.borrow().last_frame_stats(), (0, 1));

        // Frame 2: the same generation + the same state → the boundary is reused.
        let ui2 = build_ui(&tree, size, &rt, &theme);
        let dbg2 = format!("{:?}", ui2.scene().primitives());
        assert_eq!(
            rt.paint_cache.borrow().last_frame_stats(),
            (1, 0),
            "the boundary is reused"
        );
        assert_eq!(
            dbg1, dbg2,
            "the replayed scene is bit-for-bit identical to the full repaint"
        );
        // The interaction maps are replayed too (a click stays routable).
        assert_eq!(ui1.hits.len(), ui2.hits.len());
        assert!(!ui2.hits.is_empty(), "the subtree's hit is indeed replayed");
    }

    #[test]
    fn repaint_boundary_invalidated_by_generation_bump() {
        let tree = boundary_tree();
        let size = Size::new(200.0, 200.0);
        let theme = Theme::default();
        let rt = Runtime::default();

        build_ui(&tree, size, &rt, &theme); // frame 1 : miss + capture

        // The `view` is rebuilt (the config may have changed).
        rt.paint_cache.borrow_mut().bump_generation();
        build_ui(&tree, size, &rt, &theme); // frame 2
        assert_eq!(
            rt.paint_cache.borrow().last_frame_stats(),
            (0, 1),
            "a stale generation → a full repaint"
        );
    }

    #[test]
    fn repaint_boundary_invalidated_by_interaction_change() {
        let tree = boundary_tree();
        let size = Size::new(200.0, 200.0);
        let theme = Theme::default();
        let mut rt = Runtime::default();

        build_ui(&tree, size, &rt, &theme); // frame 1 : miss + capture

        // No rebuild, but a descendant's interaction state changes (the boundary's animated
        // hover) → the fingerprint differs → a repaint.
        rt.anims.insert(
            WidgetId::ROOT,
            crate::Anim {
                hover: 0.5,
                ..Default::default()
            },
        );
        build_ui(&tree, size, &rt, &theme); // frame 2
        assert_eq!(
            rt.paint_cache.borrow().last_frame_stats(),
            (0, 1),
            "the interaction state changed → a full repaint"
        );

        // Once the state has settled, the boundary is reused again.
        build_ui(&tree, size, &rt, &theme); // frame 3
        assert_eq!(rt.paint_cache.borrow().last_frame_stats(), (1, 0));
    }
}