aetna_core/

runtime.rs

//! `RunnerCore` — the backend-agnostic half of every Aetna runner.
//!
//! Holds interaction state ([`UiState`], `last_tree`) and paint scratch
//! buffers (`quad_scratch`, `runs`, `paint_items`) plus the geometry
//! context (`viewport_px`, `surface_size_override`) needed to project
//! layout's logical-pixel rects into physical-pixel scissors. Exposes
//! the identical interaction methods both backends ship: `pointer_*`,
//! `key_down`, `set_hotkeys`, `set_animation_mode`, `ui_state`,
//! `rect_of_key`, `debug_summary`, `set_surface_size`, plus the layout
//! / paint-stream stages that are pure CPU work.
//!
//! Each backend's `Runner` *contains* a `RunnerCore` and forwards the
//! interaction methods to it; only the GPU resources (pipelines,
//! buffers, atlases) and the actual GPU upload + draw work stay
//! per-backend. The split shares what's identical without a trait —
//! same shape as `crate::paint`, larger surface.
//!
//! ## What this module does NOT own
//!
//! - **Pipeline registration.** Each backend builds its own
//!   `pipelines: HashMap<ShaderHandle, BackendPipeline>` because the
//!   pipeline value type is GPU-specific.
//! - **Text upload.** Glyph atlas pages live on the GPU as backend
//!   images; the `TextPaint` that owns them is per-backend. Core
//!   reaches into it through the [`TextRecorder`] trait during the
//!   paint stream loop, then the backend flushes its atlas separately.
//! - **GPU upload of `quad_scratch` / frame uniforms.** Backend
//!   responsibility — `prepare()` orchestrates the full sequence.
//! - **`draw()`.** Both backends walk `core.paint_items` + `core.runs`
//!   themselves because the encoder type (and lifetime) diverges.
//!
//! ## Why no `Painter` trait
//!
//! Extracting a `trait Painter { fn prepare(...); fn draw(...); fn
//! set_scissor(...); }` was considered so backends would share *one*
//! abstraction surface. We declined: the only call sites left after
//! this module + [`crate::paint`] are the two
//! `prepare()` GPU-upload tails and the two `draw()` walks, and both
//! need backend-typed handles (`wgpu::RenderPass<'_>` /
//! `AutoCommandBufferBuilder<...>`) that no trait can hide without
//! generics that re-fragment the surface. A `Painter` trait would
//! reduce to a 1-method `set_scissor` indirection plus host-side
//! ceremony — dead weight. The duplication that *is* worth abstracting
//! is the host harness (winit init, swapchain management,
//! `aetna-{wgpu,vulkano}-demo::run`) — and that lives a layer above
//! the paint surface, not inside it. Revisit if a third backend lands
//! or if the GPU-upload sequences diverge enough to make a typed-state
//! interface earn its keep.

use std::cmp::Ordering;
use std::ops::Range;
use std::time::Duration;

use web_time::Instant;

use crate::draw_ops::{self, DrawOpsStats};
use crate::event::{KeyChord, KeyModifiers, PointerButton, UiEvent, UiEventKind, UiKey, UiTarget};
use crate::focus;
use crate::hit_test;
use crate::ir::{DrawOp, TextAnchor};
use crate::layout;
use crate::paint::{
    InstanceRun, PaintItem, PhysicalScissor, QuadInstance, close_run, pack_instance,
    physical_scissor,
};
use crate::shader::ShaderHandle;
use crate::state::{AnimationMode, SelectionDragGranularity, UiState};
use crate::text::atlas::RunStyle;
use crate::text::metrics::TextLayoutCacheStats;
use crate::theme::Theme;
use crate::toast;
use crate::tooltip;
use crate::tree::{Color, El, FontWeight, Rect, TextWrap};

/// Logical-pixel overlap kept between the pre-page and post-page
/// viewport when the user clicks the scroll track above/below the
/// thumb. Matches browser convention: paging by `viewport_h - overlap`
/// preserves the bottom (resp. top) row across the jump so context
/// isn't lost.
const SCROLL_PAGE_OVERLAP: f32 = 24.0;

/// Reported back from each backend's `prepare(...)` per frame.
///
/// Two redraw deadlines:
///
/// - [`Self::next_layout_redraw_in`] — the next frame that needs a
///   full rebuild + layout pass. Driven by widget
///   [`crate::tree::El::redraw_within`] requests, animations still
///   settling, and pending tooltip / toast fades. The host must call
///   the backend's full `prepare(...)` (build → layout → paint →
///   render) when this elapses.
/// - [`Self::next_paint_redraw_in`] — the next frame a time-driven
///   shader needs but layout state is unchanged (e.g. spinner /
///   skeleton / progress-indeterminate / `samples_time=true` custom
///   shaders). The host can call the backend's lighter `repaint(...)`
///   path which reuses the cached `DrawOp` list, advances
///   `frame.time`, and skips rebuild + layout. Skipping the layout
///   path is only safe when no input has been processed since the
///   last full prepare; hosts must upgrade to the full path on any
///   input event.
///
/// Legacy aggregates [`Self::needs_redraw`] and [`Self::next_redraw_in`]
/// fold both lanes (OR / `min`) for hosts that don't want to split paths.
#[derive(Clone, Copy, Debug, Default)]
pub struct PrepareResult {
    /// Legacy "any redraw needed?" — OR of `next_layout_redraw_in.is_some()`
    /// and `next_paint_redraw_in.is_some()`, plus animation-settling /
    /// tooltip-pending bools the runtime tracks internally.
    pub needs_redraw: bool,
    /// Legacy combined deadline — `min(next_layout_redraw_in,
    /// next_paint_redraw_in)`. Hosts that don't distinguish layout
    /// from paint-only redraws can keep reading this.
    pub next_redraw_in: Option<std::time::Duration>,
    /// Tightest deadline among signals that need a full rebuild +
    /// layout: widget `redraw_within`, animations still settling,
    /// tooltip / toast pending. `Some(ZERO)` for "now."
    pub next_layout_redraw_in: Option<std::time::Duration>,
    /// Tightest deadline among time-driven shaders. The host can
    /// service this with a paint-only frame (reuse cached ops, just
    /// advance `frame.time`). `Some(ZERO)` for "every frame" (the
    /// default for `is_continuous()` shaders today).
    pub next_paint_redraw_in: Option<std::time::Duration>,
    pub timings: PrepareTimings,
}

/// Outcome of a pointer-move dispatch through
/// [`RunnerCore::pointer_moved`] (or its backend wrappers).
///
/// Wayland and most X11 compositors deliver `CursorMoved` at very
/// high frequency while the cursor sits over the surface — even
/// sub-pixel jitter or per-frame compositor sync ticks count as
/// movement. The vast majority of those moves are visual no-ops
/// (the hovered node didn't change, no drag is active, no scrollbar
/// is dragging), so hosts must gate `request_redraw` on
/// `needs_redraw` to avoid spinning the rebuild + layout + render
/// pipeline on every cursor sample.
#[derive(Debug, Default)]
pub struct PointerMove {
    /// Events to dispatch through `App::on_event`. Empty when the
    /// move didn't trigger a `Drag` or selection update.
    pub events: Vec<UiEvent>,
    /// `true` when the runtime's visual state changed enough to
    /// warrant a redraw — hovered identity changed, scrollbar drag
    /// updated a scroll offset, or `events` is non-empty.
    pub needs_redraw: bool,
}

/// What [`RunnerCore::prepare_layout`] returns: the resolved
/// [`DrawOp`] list plus the redraw deadlines split into two lanes (see
/// [`PrepareResult`] for the lane semantics).
///
/// Wrapped in a struct so additions (new redraw signals, lane
/// metadata) don't churn every backend's `prepare` call site.
pub struct LayoutPrepared {
    pub ops: Vec<DrawOp>,
    pub needs_redraw: bool,
    pub next_layout_redraw_in: Option<std::time::Duration>,
    pub next_paint_redraw_in: Option<std::time::Duration>,
}

/// Per-stage CPU timing inside each backend's `prepare`. Cheap to
/// compute (a handful of `Instant::now()` calls per frame) and useful
/// for finding the dominant cost when frame budget is tight.
///
/// Stages:
/// - `layout`: layout pass + focus order sync + state apply + animation tick.
/// - `draw_ops`: tree → DrawOp[] resolution.
/// - `paint`: paint-stream loop (quad packing + text shaping via cosmic-text).
/// - `gpu_upload`: backend-side instance buffer write + atlas flush + frame uniforms.
/// - `snapshot`: cloning the laid-out tree for next-frame hit-testing.
#[derive(Clone, Copy, Debug, Default)]
pub struct PrepareTimings {
    pub layout: Duration,
    pub layout_intrinsic_cache: layout::LayoutIntrinsicCacheStats,
    pub layout_prune: layout::LayoutPruneStats,
    pub draw_ops: Duration,
    pub draw_ops_culled_text_ops: u64,
    pub paint: Duration,
    pub paint_culled_ops: u64,
    pub gpu_upload: Duration,
    pub snapshot: Duration,
    pub text_layout_cache: TextLayoutCacheStats,
}

/// Backend-agnostic runner state.
///
/// Each backend's `Runner` owns one of these as its `core` field and
/// forwards the public interaction surface to it. The fields are `pub`
/// so backends can read them in `draw()` (which has to traverse
/// `paint_items` + `runs` against backend-specific pipeline and
/// instance-buffer objects).
pub struct RunnerCore {
    pub ui_state: UiState,
    /// Snapshot of the last laid-out tree, kept so pointer events
    /// arriving between frames hit-test against the geometry the user
    /// is actually looking at.
    pub last_tree: Option<El>,

    /// Per-frame quad instance scratch — backends `bytemuck::cast_slice`
    /// this into their VBO upload.
    pub quad_scratch: Vec<QuadInstance>,
    pub runs: Vec<InstanceRun>,
    pub paint_items: Vec<PaintItem>,

    /// Cached [`DrawOp`] list, reused by [`Self::prepare_paint_cached`]
    /// for paint-only frames (time-driven shader animation when layout
    /// state is unchanged — only `frame.time` advances). Backends are
    /// expected to overwrite this with the ops returned from
    /// [`Self::prepare_layout`] once they're done with the frame's
    /// `prepare_paint` call.
    pub last_ops: Vec<DrawOp>,

    /// Physical viewport size in pixels. Backends use this for `draw()`
    /// scissor binding (logical scissors get projected into this space
    /// inside `prepare_paint`).
    pub viewport_px: (u32, u32),
    /// When set, overrides the physical viewport derived from
    /// `viewport.w * scale_factor` so paint-side scissor math matches
    /// the actual swapchain extent. Backends call
    /// [`Self::set_surface_size`] from their host's surface-config /
    /// resize hook to keep this in lockstep.
    pub surface_size_override: Option<(u32, u32)>,

    /// Theme used when resolving implicit widget surfaces to shaders.
    pub theme: Theme,
}

impl Default for RunnerCore {
    fn default() -> Self {
        Self::new()
    }
}

impl RunnerCore {
    pub fn new() -> Self {
        Self {
            ui_state: UiState::default(),
            last_tree: None,
            quad_scratch: Vec::new(),
            runs: Vec::new(),
            paint_items: Vec::new(),
            last_ops: Vec::new(),
            viewport_px: (1, 1),
            surface_size_override: None,
            theme: Theme::default(),
        }
    }

    pub fn set_theme(&mut self, theme: Theme) {
        self.theme = theme;
    }

    pub fn theme(&self) -> &Theme {
        &self.theme
    }

    /// Override the physical viewport size. Call after the host's
    /// surface configure or resize so scissor math sees the swapchain's
    /// real extent (fractional `scale_factor` round-trips can otherwise
    /// land `viewport_px` one pixel off and trip
    /// `set_scissor_rect` validation).
    pub fn set_surface_size(&mut self, width: u32, height: u32) {
        self.surface_size_override = Some((width.max(1), height.max(1)));
    }

    pub fn ui_state(&self) -> &UiState {
        &self.ui_state
    }

    pub fn debug_summary(&self) -> String {
        self.ui_state.debug_summary()
    }

    pub fn rect_of_key(&self, key: &str) -> Option<Rect> {
        self.last_tree
            .as_ref()
            .and_then(|t| self.ui_state.rect_of_key(t, key))
    }

    // ---- Input plumbing ----

    /// Pointer moved to `(x, y)` (logical px). Updates the hovered
    /// node (readable via `ui_state().hovered`) and, if the primary
    /// button is currently held, returns a `Drag` event routed to the
    /// originally pressed target. The event's `modifiers` field
    /// reflects the mask currently tracked on `UiState` (set by the
    /// host via `set_modifiers`).
    pub fn pointer_moved(&mut self, x: f32, y: f32) -> PointerMove {
        self.ui_state.pointer_pos = Some((x, y));

        // Active scrollbar drag: translate cursor delta into
        // `scroll.offsets` updates. The drag is captured at
        // `pointer_down` so we can map directly onto the scroll
        // container without going through hit-test, and we suppress
        // the normal hover/Drag event emission while it's in flight.
        if let Some(drag) = self.ui_state.scroll.thumb_drag.clone() {
            let dy = y - drag.start_pointer_y;
            let new_offset = if drag.track_remaining > 0.0 {
                drag.start_offset + dy * (drag.max_offset / drag.track_remaining)
            } else {
                drag.start_offset
            };
            let clamped = new_offset.clamp(0.0, drag.max_offset);
            let prev = self.ui_state.scroll.offsets.insert(drag.scroll_id, clamped);
            let changed = prev.is_none_or(|old| (old - clamped).abs() > f32::EPSILON);
            return PointerMove {
                events: Vec::new(),
                needs_redraw: changed,
            };
        }

        let hit = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::hit_test_target(t, &self.ui_state, (x, y)));
        // Stash the previous hover target so we can pair Leave/Enter
        // events on identity change. `set_hovered` mutates the state
        // and only returns whether identity flipped.
        let prev_hover = self.ui_state.hovered.clone();
        let hover_changed = self.ui_state.set_hovered(hit, Instant::now());
        // Track the link URL under the pointer separately from keyed
        // hover so the cursor resolver can flip to `Pointer` over text
        // runs that aren't themselves hit-test targets. A change here
        // (entering or leaving a link) needs a redraw so the host's
        // per-frame cursor resolution reads the new value.
        let prev_hovered_link = self.ui_state.hovered_link.clone();
        let new_hovered_link = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::link_at(t, &self.ui_state, (x, y)));
        let link_hover_changed = new_hovered_link != prev_hovered_link;
        self.ui_state.hovered_link = new_hovered_link;
        let modifiers = self.ui_state.modifiers;

        let mut out = Vec::new();

        // Hover-transition events: Leave on the prior target (when
        // there was one), Enter on the new target (when there is one).
        // Both fire on identity change only — cursor moves *within* the
        // same hovered node are visual no-ops here, matching the
        // redraw-debouncing semantics. Always Leave-then-Enter so apps
        // observe the cleared state before the new one.
        if hover_changed {
            if let Some(prev) = prev_hover {
                out.push(UiEvent {
                    key: Some(prev.key.clone()),
                    target: Some(prev),
                    pointer: Some((x, y)),
                    key_press: None,
                    text: None,
                    selection: None,
                    modifiers,
                    click_count: 0,
                    path: None,
                    kind: UiEventKind::PointerLeave,
                });
            }
            if let Some(new) = self.ui_state.hovered.clone() {
                out.push(UiEvent {
                    key: Some(new.key.clone()),
                    target: Some(new),
                    pointer: Some((x, y)),
                    key_press: None,
                    text: None,
                    selection: None,
                    modifiers,
                    click_count: 0,
                    path: None,
                    kind: UiEventKind::PointerEnter,
                });
            }
        }

        // Selection drag-extend takes precedence over the focusable
        // Drag emission. Cross-leaf: if the pointer hits a selectable
        // leaf, head migrates there. Otherwise we project the pointer
        // onto the closest selectable leaf in document order so that
        // dragging *past* the last leaf extends to its end (rather
        // than snapping the head home to the anchor leaf).
        if let Some(drag) = self.ui_state.selection.drag.clone()
            && let Some(tree) = self.last_tree.as_ref()
        {
            let raw_head =
                head_for_drag(tree, &self.ui_state, (x, y)).unwrap_or_else(|| drag.anchor.clone());
            let (anchor, head) = selection_range_for_drag(tree, &self.ui_state, &drag, raw_head);
            let new_sel = crate::selection::Selection {
                range: Some(crate::selection::SelectionRange { anchor, head }),
            };
            if new_sel != self.ui_state.current_selection {
                self.ui_state.current_selection = new_sel.clone();
                out.push(selection_event(new_sel, modifiers, Some((x, y))));
            }
        }

        // Drag: pointer moved while primary button is down → emit Drag
        // to the originally pressed target. Cursor escape from the
        // pressed node is the *normal* drag-extend case (e.g. text
        // selection inside an editable widget); we keep emitting until
        // pointer_up clears `pressed`.
        if let Some(p) = self.ui_state.pressed.clone() {
            // Caret-blink reset: drag-selecting inside a text input
            // is ongoing editing activity, so keep the caret solid
            // for the duration of the drag.
            if self.focused_captures_keys() {
                self.ui_state.bump_caret_activity(Instant::now());
            }
            out.push(UiEvent {
                key: Some(p.key.clone()),
                target: Some(p),
                pointer: Some((x, y)),
                key_press: None,
                text: None,
                selection: None,
                modifiers,
                click_count: self.ui_state.current_click_count(),
                path: None,
                kind: UiEventKind::Drag,
            });
        }

        let needs_redraw = hover_changed || link_hover_changed || !out.is_empty();
        PointerMove {
            events: out,
            needs_redraw,
        }
    }

    /// Pointer left the window — clear hover / press trackers.
    /// Returns a `PointerLeave` event for the previously hovered
    /// target (when there was one) so apps can run hover-leave side
    /// effects symmetrically with `PointerEnter`. Cursor positions on
    /// the leave event are the last known pointer position before the
    /// pointer exited, since winit no longer reports coordinates once
    /// the cursor is outside the window.
    pub fn pointer_left(&mut self) -> Vec<UiEvent> {
        let last_pos = self.ui_state.pointer_pos;
        let prev_hover = self.ui_state.hovered.clone();
        let modifiers = self.ui_state.modifiers;
        self.ui_state.pointer_pos = None;
        self.ui_state.set_hovered(None, Instant::now());
        self.ui_state.pressed = None;
        self.ui_state.pressed_secondary = None;
        // Pointer leaves the window → no link is hovered or pressed
        // anymore. Clearing here keeps a stale `Pointer` cursor from
        // sticking after the user moves the mouse out of the canvas
        // and lets re-entry recompute against the actual current
        // position.
        self.ui_state.hovered_link = None;
        self.ui_state.pressed_link = None;

        let mut out = Vec::new();
        if let Some(prev) = prev_hover {
            out.push(UiEvent {
                key: Some(prev.key.clone()),
                target: Some(prev),
                pointer: last_pos,
                key_press: None,
                text: None,
                selection: None,
                modifiers,
                click_count: 0,
                path: None,
                kind: UiEventKind::PointerLeave,
            });
        }
        out
    }

    /// A file is being dragged over the window at logical-pixel
    /// coordinates `(x, y)`. Hosts call this from
    /// `WindowEvent::HoveredFile`. Hit-tests at the cursor position and
    /// emits a `FileHovered` event routed to the keyed leaf at that
    /// point (or window-level when the cursor is over no keyed
    /// surface). Multi-file drags fire one event per file — winit
    /// reports each file separately and the host forwards each call
    /// into this method.
    ///
    /// The hover state is *not* tracked across files; apps that want
    /// to count active hovered files do so themselves between
    /// `FileHovered` and the eventual `FileHoverCancelled` /
    /// `FileDropped`.
    pub fn file_hovered(&mut self, path: std::path::PathBuf, x: f32, y: f32) -> Vec<UiEvent> {
        self.ui_state.pointer_pos = Some((x, y));
        let target = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::hit_test_target(t, &self.ui_state, (x, y)));
        let key = target.as_ref().map(|t| t.key.clone());
        vec![UiEvent {
            key,
            target,
            pointer: Some((x, y)),
            key_press: None,
            text: None,
            selection: None,
            modifiers: self.ui_state.modifiers,
            click_count: 0,
            path: Some(path),
            kind: UiEventKind::FileHovered,
        }]
    }

    /// The user moved a hovered file off the window without dropping
    /// (or pressed Escape). Window-level event — not routed to any
    /// keyed leaf, since winit doesn't tell us which file was being
    /// dragged. Apps clear any drop-zone affordance state.
    pub fn file_hover_cancelled(&mut self) -> Vec<UiEvent> {
        vec![UiEvent {
            key: None,
            target: None,
            pointer: self.ui_state.pointer_pos,
            key_press: None,
            text: None,
            selection: None,
            modifiers: self.ui_state.modifiers,
            click_count: 0,
            path: None,
            kind: UiEventKind::FileHoverCancelled,
        }]
    }

    /// A file was dropped on the window at logical-pixel coordinates
    /// `(x, y)`. Hosts call this from `WindowEvent::DroppedFile`.
    /// Same routing as [`Self::file_hovered`] — keyed leaf at the drop
    /// point, or window-level. One event per file.
    pub fn file_dropped(&mut self, path: std::path::PathBuf, x: f32, y: f32) -> Vec<UiEvent> {
        self.ui_state.pointer_pos = Some((x, y));
        let target = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::hit_test_target(t, &self.ui_state, (x, y)));
        let key = target.as_ref().map(|t| t.key.clone());
        vec![UiEvent {
            key,
            target,
            pointer: Some((x, y)),
            key_press: None,
            text: None,
            selection: None,
            modifiers: self.ui_state.modifiers,
            click_count: 0,
            path: Some(path),
            kind: UiEventKind::FileDropped,
        }]
    }

    /// Primary/secondary/middle pointer button pressed at `(x, y)`.
    /// For the primary button, focuses the hit target and stashes it
    /// as the pressed target; emits a `PointerDown` event so widgets
    /// like text_input can react at down-time (e.g., set the selection
    /// anchor before any drag extends it). Secondary/middle store on a
    /// separate channel and never emit a `PointerDown`.
    ///
    /// Also drives the library's text-selection manager: a primary
    /// press on a `selectable` text leaf starts a drag and produces a
    /// `SelectionChanged` event; a press on any other element clears
    /// any active static-text selection by emitting a
    /// `SelectionChanged` with an empty range.
    pub fn pointer_down(&mut self, x: f32, y: f32, button: PointerButton) -> Vec<UiEvent> {
        // Scrollbar track pre-empts normal hit-test: a primary press
        // inside a scrollable's track column either captures a thumb
        // drag (when the press lands inside the visible thumb rect)
        // or pages the scroll offset by a viewport (when it lands
        // above or below the thumb). Both branches suppress focus /
        // press / event chains for the press itself; `pointer_moved`
        // then drives the drag (no-op for paged clicks) and
        // `pointer_up` clears the drag.
        if matches!(button, PointerButton::Primary)
            && let Some((scroll_id, _track, thumb_rect)) = self.ui_state.thumb_at(x, y)
        {
            let metrics = self
                .ui_state
                .scroll
                .metrics
                .get(&scroll_id)
                .copied()
                .unwrap_or_default();
            let start_offset = self
                .ui_state
                .scroll
                .offsets
                .get(&scroll_id)
                .copied()
                .unwrap_or(0.0);

            // Grab when the press lands inside the visible thumb;
            // page otherwise. The track is wider than the thumb
            // horizontally, so this branch is decided by `y` alone.
            let grabbed = y >= thumb_rect.y && y <= thumb_rect.y + thumb_rect.h;
            if grabbed {
                let track_remaining = (metrics.viewport_h - thumb_rect.h).max(0.0);
                self.ui_state.scroll.thumb_drag = Some(crate::state::ThumbDrag {
                    scroll_id,
                    start_pointer_y: y,
                    start_offset,
                    track_remaining,
                    max_offset: metrics.max_offset,
                });
            } else {
                // Click-to-page. Browser convention: each press
                // shifts the offset by ~one viewport with a small
                // overlap so context isn't lost. Direction is
                // decided by which side of the thumb the press
                // landed on.
                let page = (metrics.viewport_h - SCROLL_PAGE_OVERLAP).max(0.0);
                let delta = if y < thumb_rect.y { -page } else { page };
                let new_offset = (start_offset + delta).clamp(0.0, metrics.max_offset);
                self.ui_state.scroll.offsets.insert(scroll_id, new_offset);
            }
            return Vec::new();
        }

        let hit = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::hit_test_target(t, &self.ui_state, (x, y)));
        // Only the primary button drives focus + the visual press
        // envelope. Secondary/middle clicks shouldn't yank focus from
        // the currently-focused element (matches browser/native behavior
        // where right-clicking a button doesn't take focus).
        if !matches!(button, PointerButton::Primary) {
            // Stash the down-target on the secondary/middle channel so
            // pointer_up can confirm the click landed on the same node.
            self.ui_state.pressed_secondary = hit.map(|h| (h, button));
            return Vec::new();
        }

        // Stash any link URL the press lands on before the keyed-
        // target walk consumes the press. Cleared in `pointer_up`,
        // which only emits `LinkActivated` if the up position resolves
        // to the same URL — same press-then-confirm contract as a
        // normal `Click`. A press that misses every link clears any
        // stale value from the previous press so a drag-released-
        // elsewhere never fires a link from an earlier interaction.
        self.ui_state.pressed_link = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::link_at(t, &self.ui_state, (x, y)));
        self.ui_state.set_focus(hit.clone());
        // `:focus-visible` rule: pointer-driven focus suppresses the
        // ring; widgets that want it on click opt in via
        // `always_show_focus_ring`.
        self.ui_state.set_focus_visible(false);
        self.ui_state.pressed = hit.clone();
        // A press on the hovered node dismisses any tooltip for
        // the rest of this hover session — matches native UIs.
        self.ui_state.tooltip.dismissed_for_hover = true;
        let modifiers = self.ui_state.modifiers;

        // Click counting: extend a multi-click sequence when the press
        // lands on the same target inside the time + distance window.
        let now = Instant::now();
        let click_count =
            self.ui_state
                .next_click_count(now, (x, y), hit.as_ref().map(|t| t.node_id.as_str()));

        let mut out = Vec::new();
        if let Some(p) = hit.clone() {
            // Caret-blink reset: a press inside the focused widget
            // (e.g., to reposition the caret in an already-focused
            // input) is editing activity. The earlier `set_focus`
            // call bumps when focus *changes*; this catches the
            // same-target case so click-to-move-caret resets the
            // blink too.
            if self.focused_captures_keys() {
                self.ui_state.bump_caret_activity(now);
            }
            out.push(UiEvent {
                key: Some(p.key.clone()),
                target: Some(p),
                pointer: Some((x, y)),
                key_press: None,
                text: None,
                selection: None,
                modifiers,
                click_count,
                path: None,
                kind: UiEventKind::PointerDown,
            });
        }

        // Selection routing. The selection hit-test is independent of
        // the focusable hit: a `text(...).key("p").selectable()` leaf is
        // both a (non-focusable) keyed PointerDown target and a
        // selectable text leaf. Apps see both events; selection drag
        // starts in either case. A press that lands on neither a
        // selectable nor a focusable widget clears any active
        // selection.
        if let Some(point) = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::selection_point_at(t, &self.ui_state, (x, y)))
        {
            self.start_selection_drag(point, &mut out, modifiers, (x, y), click_count);
        } else if !self.ui_state.current_selection.is_empty() {
            // Clear-on-click only when the press lands somewhere that
            // can't take selection ownership itself.
            //
            // - If the press is on the widget that already owns the
            //   selection (same key), the widget's PointerDown
            //   handler updates its own caret; a runtime clear here
            //   races and collapses the app's selection back to
            //   default. (User-visible bug: caret alternated between
            //   the click position and byte 0 on every other click.)
            //
            // - If the press is on a *different* capture_keys widget
            //   (e.g., dragging from one text_input into another),
            //   that widget's PointerDown will replace the selection
            //   with one anchored at the click position. The runtime
            //   clear would arrive after the replace and wipe the
            //   anchor — so when the drag began, only `head` would
            //   advance and `anchor` would default to 0, jumping the
            //   selection start to the beginning of the text.
            //
            // Press on a regular focusable (button, etc.) or in dead
            // space still clears, matching the browser idiom.
            let click_handles_selection = match (&hit, &self.ui_state.current_selection.range) {
                (Some(h), Some(range)) => {
                    h.key == range.anchor.key
                        || h.key == range.head.key
                        || self
                            .last_tree
                            .as_ref()
                            .and_then(|t| find_capture_keys(t, &h.node_id))
                            .unwrap_or(false)
                }
                _ => false,
            };
            if !click_handles_selection {
                out.push(selection_event(
                    crate::selection::Selection::default(),
                    modifiers,
                    Some((x, y)),
                ));
                self.ui_state.current_selection = crate::selection::Selection::default();
                self.ui_state.selection.drag = None;
            }
        }

        out
    }

    /// Stamp a new [`crate::state::SelectionDrag`] and emit a
    /// `SelectionChanged` event seeded by `point`. For
    /// `click_count == 2` the anchor / head pair expands to the word
    /// range around `point.byte`; for `click_count >= 3` it expands to
    /// the whole leaf (static-text triple-click typically wants the
    /// paragraph). For other counts (single click, default) the
    /// selection is collapsed at `point`.
    fn start_selection_drag(
        &mut self,
        point: crate::selection::SelectionPoint,
        out: &mut Vec<UiEvent>,
        modifiers: KeyModifiers,
        pointer: (f32, f32),
        click_count: u8,
    ) {
        let leaf_text = self
            .last_tree
            .as_ref()
            .and_then(|t| crate::selection::find_keyed_text(t, &point.key))
            .unwrap_or_default();
        let (anchor_byte, head_byte) = match click_count {
            2 => crate::selection::word_range_at(&leaf_text, point.byte),
            n if n >= 3 => (0, leaf_text.len()),
            _ => (point.byte, point.byte),
        };
        let granularity = match click_count {
            2 => SelectionDragGranularity::Word,
            n if n >= 3 => SelectionDragGranularity::Leaf,
            _ => SelectionDragGranularity::Character,
        };
        let anchor = crate::selection::SelectionPoint::new(point.key.clone(), anchor_byte);
        let head = crate::selection::SelectionPoint::new(point.key.clone(), head_byte);
        let new_sel = crate::selection::Selection {
            range: Some(crate::selection::SelectionRange {
                anchor: anchor.clone(),
                head: head.clone(),
            }),
        };
        self.ui_state.current_selection = new_sel.clone();
        self.ui_state.selection.drag = Some(crate::state::SelectionDrag {
            anchor,
            head,
            granularity,
        });
        out.push(selection_event(new_sel, modifiers, Some(pointer)));
    }

    /// Pointer released. For the primary button, fires `PointerUp`
    /// (always, with the originally pressed target so drag-aware
    /// widgets see drag-end) and additionally `Click` if the release
    /// landed on the same node as the down. For secondary / middle,
    /// fires the corresponding click variant when the up landed on the
    /// same node; no analogue of `PointerUp` since drag is a primary-
    /// button concept here.
    pub fn pointer_up(&mut self, x: f32, y: f32, button: PointerButton) -> Vec<UiEvent> {
        // Scrollbar drag ends without producing app-level events —
        // the press never went through `pressed` / `pressed_secondary`
        // so there's nothing else to clean up. Released from anywhere;
        // the drag is global once captured, matching native scrollbars.
        if matches!(button, PointerButton::Primary) && self.ui_state.scroll.thumb_drag.is_some() {
            self.ui_state.scroll.thumb_drag = None;
            return Vec::new();
        }

        // End any active text-selection drag. The selection itself
        // persists; only the "currently dragging" flag goes away.
        if matches!(button, PointerButton::Primary) {
            self.ui_state.selection.drag = None;
        }

        let hit = self
            .last_tree
            .as_ref()
            .and_then(|t| hit_test::hit_test_target(t, &self.ui_state, (x, y)));
        let modifiers = self.ui_state.modifiers;
        let mut out = Vec::new();
        match button {
            PointerButton::Primary => {
                let pressed = self.ui_state.pressed.take();
                let click_count = self.ui_state.current_click_count();
                if let Some(p) = pressed.clone() {
                    out.push(UiEvent {
                        key: Some(p.key.clone()),
                        target: Some(p),
                        pointer: Some((x, y)),
                        key_press: None,
                        text: None,
                        selection: None,
                        modifiers,
                        click_count,
                        path: None,
                        kind: UiEventKind::PointerUp,
                    });
                }
                if let (Some(p), Some(h)) = (pressed, hit)
                    && p.node_id == h.node_id
                {
                    // Toast dismiss buttons are runtime-managed —
                    // the click drops the matching toast from the
                    // queue and is *not* surfaced to the app, so
                    // `on_event` doesn't have to know about toast
                    // bookkeeping.
                    if let Some(id) = toast::parse_dismiss_key(&p.key) {
                        self.ui_state.dismiss_toast(id);
                    } else {
                        out.push(UiEvent {
                            key: Some(p.key.clone()),
                            target: Some(p),
                            pointer: Some((x, y)),
                            key_press: None,
                            text: None,
                            selection: None,
                            modifiers,
                            click_count,
                            path: None,
                            kind: UiEventKind::Click,
                        });
                    }
                }
                // Link click — surface the URL as a separate event so
                // the app's link policy is independent of any keyed
                // ancestor's `Click`. Press-then-confirm: the up
                // position must resolve to the same URL as the down
                // (cancel-on-drag-away, matching native link UX).
                if let Some(pressed_url) = self.ui_state.pressed_link.take() {
                    let up_link = self
                        .last_tree
                        .as_ref()
                        .and_then(|t| hit_test::link_at(t, &self.ui_state, (x, y)));
                    if up_link.as_ref() == Some(&pressed_url) {
                        out.push(UiEvent {
                            key: Some(pressed_url),
                            target: None,
                            pointer: Some((x, y)),
                            key_press: None,
                            text: None,
                            selection: None,
                            modifiers,
                            click_count: 1,
                            path: None,
                            kind: UiEventKind::LinkActivated,
                        });
                    }
                }
            }
            PointerButton::Secondary | PointerButton::Middle => {
                let pressed = self.ui_state.pressed_secondary.take();
                if let (Some((p, b)), Some(h)) = (pressed, hit)
                    && b == button
                    && p.node_id == h.node_id
                {
                    let kind = match button {
                        PointerButton::Secondary => UiEventKind::SecondaryClick,
                        PointerButton::Middle => UiEventKind::MiddleClick,
                        PointerButton::Primary => unreachable!(),
                    };
                    out.push(UiEvent {
                        key: Some(p.key.clone()),
                        target: Some(p),
                        pointer: Some((x, y)),
                        key_press: None,
                        text: None,
                        selection: None,
                        modifiers,
                        click_count: 1,
                        path: None,
                        kind,
                    });
                }
            }
        }
        out
    }

    pub fn key_down(&mut self, key: UiKey, modifiers: KeyModifiers, repeat: bool) -> Vec<UiEvent> {
        // Capture path: when the focused node opted into raw key
        // capture, editing keys are delivered as raw `KeyDown` events
        // to the focused target. Hotkeys still match first — an app's
        // global Ctrl+S beats a text input's local consumption of S.
        // Escape is both an editing key and the generic "exit editing"
        // command: route it to the widget first so it can collapse a
        // selection, then clear focus.
        if self.focused_captures_keys() {
            if let Some(event) = self.ui_state.try_hotkey(&key, modifiers, repeat) {
                return vec![event];
            }
            // Caret-blink reset: any key arriving at a capture_keys
            // widget is text-editing activity (caret motion, edit,
            // shortcut), so the caret should snap back to solid even
            // when the app doesn't propagate its `Selection` back via
            // `App::selection()`. Without this, hammering arrow keys
            // produces no visible blink reset.
            self.ui_state.bump_caret_activity(Instant::now());
            self.ui_state.set_focus_visible(true);
            let blur_after = matches!(key, UiKey::Escape);
            let out = self
                .ui_state
                .key_down_raw(key, modifiers, repeat)
                .into_iter()
                .collect();
            if blur_after {
                self.ui_state.set_focus(None);
                self.ui_state.set_focus_visible(false);
            }
            return out;
        }

        // Arrow-nav: if the focused node sits inside an arrow-navigable
        // group (typically a popover_panel of menu items), Up / Down /
        // Home / End move focus among its focusable siblings rather
        // than emitting a `KeyDown` event. Hotkeys are still matched
        // first so a global Ctrl+ArrowUp chord beats menu navigation.
        if matches!(
            key,
            UiKey::ArrowUp | UiKey::ArrowDown | UiKey::Home | UiKey::End
        ) && let Some(siblings) = self.focused_arrow_nav_group()
        {
            if let Some(event) = self.ui_state.try_hotkey(&key, modifiers, repeat) {
                return vec![event];
            }
            self.move_focus_in_group(&key, &siblings);
            return Vec::new();
        }

        let mut out: Vec<UiEvent> = self
            .ui_state
            .key_down(key, modifiers, repeat)
            .into_iter()
            .collect();

        // Esc clears any active text selection (parallels the
        // pointer_down "press lands outside selectable+focusable"
        // path). The Escape event itself still fires so apps can
        // dismiss popovers / modals; the SelectionChanged is emitted
        // alongside it. This only runs in the non-capture-keys path,
        // so pressing Esc while typing in an input doesn't clobber
        // the input's selection — matching browser behavior.
        if matches!(out.first().map(|e| e.kind), Some(UiEventKind::Escape))
            && !self.ui_state.current_selection.is_empty()
        {
            self.ui_state.current_selection = crate::selection::Selection::default();
            self.ui_state.selection.drag = None;
            out.push(selection_event(
                crate::selection::Selection::default(),
                modifiers,
                None,
            ));
        }

        out
    }

    /// Look up the focused node's nearest [`El::arrow_nav_siblings`]
    /// parent in the last laid-out tree and return the focusable
    /// siblings (the navigation targets for Up / Down / Home / End).
    /// Returns `None` when no node is focused, the tree hasn't been
    /// built yet, or the focused element isn't inside an
    /// arrow-navigable parent.
    fn focused_arrow_nav_group(&self) -> Option<Vec<UiTarget>> {
        let focused = self.ui_state.focused.as_ref()?;
        let tree = self.last_tree.as_ref()?;
        focus::arrow_nav_group(tree, &self.ui_state, &focused.node_id)
    }

    /// Move the focused element to the appropriate sibling for `key`.
    /// `Up` / `Down` step by one (saturating at the ends — no wrap, so
    /// holding the key doesn't loop visually); `Home` / `End` jump to
    /// the first / last sibling.
    fn move_focus_in_group(&mut self, key: &UiKey, siblings: &[UiTarget]) {
        if siblings.is_empty() {
            return;
        }
        let focused_id = match self.ui_state.focused.as_ref() {
            Some(t) => t.node_id.clone(),
            None => return,
        };
        let idx = siblings.iter().position(|t| t.node_id == focused_id);
        let next_idx = match (key, idx) {
            (UiKey::ArrowUp, Some(i)) => i.saturating_sub(1),
            (UiKey::ArrowDown, Some(i)) => (i + 1).min(siblings.len() - 1),
            (UiKey::Home, _) => 0,
            (UiKey::End, _) => siblings.len() - 1,
            _ => return,
        };
        if Some(next_idx) != idx {
            self.ui_state.set_focus(Some(siblings[next_idx].clone()));
            self.ui_state.set_focus_visible(true);
        }
    }

    /// Look up the focused node in the last laid-out tree and return
    /// its `capture_keys` flag. False when no node is focused or the
    /// tree hasn't been built yet.
    fn focused_captures_keys(&self) -> bool {
        let Some(focused) = self.ui_state.focused.as_ref() else {
            return false;
        };
        let Some(tree) = self.last_tree.as_ref() else {
            return false;
        };
        find_capture_keys(tree, &focused.node_id).unwrap_or(false)
    }

    /// OS-composed text input (printable characters after dead-key /
    /// shift / IME composition). Routed to the focused element as a
    /// `TextInput` event. Returns `None` if no node has focus, or if
    /// `text` is empty (some platforms emit empty composition strings
    /// during IME selection).
    pub fn text_input(&mut self, text: String) -> Option<UiEvent> {
        if text.is_empty() {
            return None;
        }
        let target = self.ui_state.focused.clone()?;
        let modifiers = self.ui_state.modifiers;
        // Caret-blink reset: typing into the focused widget is
        // text-editing activity. See the matching bump in `key_down`.
        self.ui_state.bump_caret_activity(Instant::now());
        Some(UiEvent {
            key: Some(target.key.clone()),
            target: Some(target),
            pointer: None,
            key_press: None,
            text: Some(text),
            selection: None,
            modifiers,
            click_count: 0,
            path: None,
            kind: UiEventKind::TextInput,
        })
    }

    pub fn set_hotkeys(&mut self, hotkeys: Vec<(KeyChord, String)>) {
        self.ui_state.set_hotkeys(hotkeys);
    }

    /// Push the app's current [`crate::selection::Selection`] into the
    /// runtime so the painter can draw highlight bands. Hosts call
    /// this once per frame alongside `set_hotkeys`, sourcing the value
    /// from [`crate::event::App::selection`].
    pub fn set_selection(&mut self, selection: crate::selection::Selection) {
        if self.ui_state.current_selection != selection {
            self.ui_state.bump_caret_activity(Instant::now());
        }
        self.ui_state.current_selection = selection;
    }

    /// Queue toast specs onto the runtime's toast stack. Each spec
    /// is stamped with a monotonic id and `expires_at = now + ttl`;
    /// the next `prepare_layout` call drops expired entries and
    /// synthesizes a `toast_stack` floating layer over the rest.
    /// Hosts wire this from `App::drain_toasts` once per frame.
    pub fn push_toasts(&mut self, specs: Vec<crate::toast::ToastSpec>) {
        let now = Instant::now();
        for spec in specs {
            self.ui_state.push_toast(spec, now);
        }
    }

    /// Programmatically dismiss a single toast by id. Mostly useful
    /// when the app wants to cancel a long-TTL toast in response to
    /// some external event (e.g., the connection reconnected).
    pub fn dismiss_toast(&mut self, id: u64) {
        self.ui_state.dismiss_toast(id);
    }

    /// Queue programmatic focus requests by widget key. Each entry is
    /// resolved during the next `prepare_layout`, after the focus
    /// order has been rebuilt from the new tree; unmatched keys drop
    /// silently. Hosts wire this from [`crate::event::App::drain_focus_requests`]
    /// once per frame, alongside `push_toasts`.
    pub fn push_focus_requests(&mut self, keys: Vec<String>) {
        self.ui_state.push_focus_requests(keys);
    }

    /// Queue programmatic scroll-to-row requests targeting virtual
    /// lists by key. Each request is consumed during layout of the
    /// matching list, where viewport height and row heights are
    /// known. Hosts wire this from [`crate::event::App::drain_scroll_requests`]
    /// once per frame, alongside `push_focus_requests`.
    pub fn push_scroll_requests(&mut self, requests: Vec<crate::scroll::ScrollRequest>) {
        self.ui_state.push_scroll_requests(requests);
    }

    pub fn set_animation_mode(&mut self, mode: AnimationMode) {
        self.ui_state.set_animation_mode(mode);
    }

    pub fn pointer_wheel(&mut self, x: f32, y: f32, dy: f32) -> bool {
        let Some(tree) = self.last_tree.as_ref() else {
            return false;
        };
        self.ui_state.pointer_wheel(tree, (x, y), dy)
    }

    // ---- Per-frame staging ----

    /// Layout + state apply + animation tick + viewport projection +
    /// `DrawOp` resolution. Returns the resolved op list and whether
    /// visual animations need another frame; writes per-stage timings
    /// into `timings` (`layout` + `draw_ops`).
    ///
    /// `samples_time` answers "does this shader's output depend on
    /// `frame.time`?" The runtime calls it once per draw op when no
    /// other in-flight motion has already requested a redraw; any
    /// `true` answer keeps `needs_redraw` set so the host idle loop
    /// keeps ticking. Stock shaders self-report through
    /// [`crate::shader::StockShader::is_continuous`]; backends layer
    /// on the registered set of `samples_time=true` custom shaders.
    /// Callers that have no time-driven shaders pass
    /// [`Self::no_time_shaders`].
    pub fn prepare_layout<F>(
        &mut self,
        root: &mut El,
        viewport: Rect,
        scale_factor: f32,
        timings: &mut PrepareTimings,
        samples_time: F,
    ) -> LayoutPrepared
    where
        F: Fn(&ShaderHandle) -> bool,
    {
        let t0 = Instant::now();
        // Tooltip + toast synthesis run before the real layout: assign
        // ids first so the tooltip pass can resolve the hover anchor
        // by computed_id, then append the runtime-managed floating
        // layers. The subsequent `layout::layout` call re-assigns
        // (idempotently — same path shapes produce the same ids) and
        // lays out the appended layers alongside everything else.
        let mut needs_redraw = {
            crate::profile_span!("prepare::layout");
            {
                crate::profile_span!("prepare::layout::assign_ids");
                layout::assign_ids(root);
            }
            let tooltip_pending = {
                crate::profile_span!("prepare::layout::tooltip");
                tooltip::synthesize_tooltip(root, &self.ui_state, t0)
            };
            let toast_pending = {
                crate::profile_span!("prepare::layout::toast");
                toast::synthesize_toasts(root, &mut self.ui_state, t0)
            };
            {
                crate::profile_span!("prepare::layout::apply_metrics");
                self.theme.apply_metrics(root);
            }
            {
                crate::profile_span!("prepare::layout::layout");
                // `assign_ids` ran above (so tooltip/toast synthesis
                // could resolve nodes by id), and the synthesize
                // functions called `assign_id_appended` on the layers
                // they pushed — so the recursive id walk inside
                // `layout::layout` would be a wasted second pass over
                // the entire tree. Use `layout_post_assign` to skip it.
                layout::layout_post_assign(root, &mut self.ui_state, viewport);
                // Drop scroll requests that didn't match any virtual
                // list this frame (the matching list may have been
                // removed from the tree, or the app may have raced a
                // state change that retired the key).
                self.ui_state.clear_pending_scroll_requests();
            }
            {
                crate::profile_span!("prepare::layout::sync_focus_order");
                self.ui_state.sync_focus_order(root);
            }
            {
                crate::profile_span!("prepare::layout::sync_selection_order");
                self.ui_state.sync_selection_order(root);
            }
            {
                crate::profile_span!("prepare::layout::sync_popover_focus");
                focus::sync_popover_focus(root, &mut self.ui_state);
            }
            {
                // Drain after popover auto-focus so explicit app
                // requests win when both fire on the same frame
                // (e.g. a hotkey opens a popover and then jumps focus
                // to a non-default child).
                crate::profile_span!("prepare::layout::drain_focus_requests");
                self.ui_state.drain_focus_requests();
            }
            {
                crate::profile_span!("prepare::layout::apply_state");
                self.ui_state.apply_to_state();
            }
            self.viewport_px = self.surface_size_override.unwrap_or_else(|| {
                (
                    (viewport.w * scale_factor).ceil().max(1.0) as u32,
                    (viewport.h * scale_factor).ceil().max(1.0) as u32,
                )
            });
            let animations = {
                crate::profile_span!("prepare::layout::tick_animations");
                self.ui_state.tick_visual_animations(root, Instant::now())
            };
            animations || tooltip_pending || toast_pending
        };
        let t_after_layout = Instant::now();
        timings.layout_intrinsic_cache = layout::take_intrinsic_cache_stats();
        timings.layout_prune = layout::take_prune_stats();
        let (ops, draw_ops_stats) = {
            crate::profile_span!("prepare::draw_ops");
            let mut stats = DrawOpsStats::default();
            let ops = draw_ops::draw_ops_with_theme_and_stats(
                root,
                &self.ui_state,
                &self.theme,
                &mut stats,
            );
            (ops, stats)
        };
        let t_after_draw_ops = Instant::now();
        timings.layout = t_after_layout - t0;
        timings.draw_ops = t_after_draw_ops - t_after_layout;
        timings.draw_ops_culled_text_ops = draw_ops_stats.culled_text_ops;
        timings.text_layout_cache = crate::text::metrics::take_shape_cache_stats();

        // Two-lane deadline split:
        //
        // - **Layout lane**: signals that require a rebuild + layout
        //   pass to render correctly on the next frame. Animation
        //   settling, tooltip / toast pending, and widget
        //   `redraw_within` requests all change the El tree's visual
        //   state at their deadline.
        // - **Paint lane**: time-driven shaders (stock continuous, or
        //   `samples_time=true` custom). The El tree is unchanged; only
        //   `frame.time` needs to advance. Hosts that want to skip
        //   layout for these can run a paint-only frame via
        //   [`Self::prepare_paint_cached`] + [`Self::last_ops`].
        //
        // Bool-shaped layout signals (animations settling, tooltip /
        // toast pending) map to `Duration::ZERO`. The widget
        // `redraw_within` aggregate is folded in via `min`.
        let shader_needs_redraw = ops.iter().any(|op| op_is_continuous(op, &samples_time));
        let widget_redraw =
            aggregate_redraw_within(root, viewport, &self.ui_state.layout.computed_rects);

        let next_layout_redraw_in = match (needs_redraw, widget_redraw) {
            (true, Some(d)) => Some(d.min(std::time::Duration::ZERO)),
            (true, None) => Some(std::time::Duration::ZERO),
            (false, d) => d,
        };
        let next_paint_redraw_in = if shader_needs_redraw {
            Some(std::time::Duration::ZERO)
        } else {
            None
        };
        if next_layout_redraw_in.is_some() || next_paint_redraw_in.is_some() {
            needs_redraw = true;
        }

        // Ops are returned by value (not cached on `self`) so the
        // caller can borrow them into the per-frame `prepare_paint`
        // without also locking `&mut self`. The wrapper hands them
        // back to `self.last_ops` after paint — see [`Self::last_ops`].
        LayoutPrepared {
            ops,
            needs_redraw,
            next_layout_redraw_in,
            next_paint_redraw_in,
        }
    }

    /// Run [`Self::prepare_paint`] against the cached
    /// [`Self::last_ops`] from the most recent
    /// [`Self::prepare_layout`] call. Used by hosts that service a
    /// paint-only redraw (driven by
    /// [`PrepareResult::next_paint_redraw_in`]) without re-running
    /// build + layout.
    ///
    /// The caller is responsible for the same paint-time invariants as
    /// [`Self::prepare_paint`]: call `text.frame_begin()` first, and
    /// ensure no input has been processed since the last
    /// `prepare_layout` (otherwise hover / press state is stale and a
    /// full prepare is required instead).
    pub fn prepare_paint_cached<F1, F2>(
        &mut self,
        is_registered: F1,
        samples_backdrop: F2,
        text: &mut dyn TextRecorder,
        scale_factor: f32,
        timings: &mut PrepareTimings,
    ) where
        F1: Fn(&ShaderHandle) -> bool,
        F2: Fn(&ShaderHandle) -> bool,
    {
        // `prepare_paint` only touches `self.{quad_scratch, runs,
        // paint_items}`, not `self.last_ops`, but the borrow checker
        // can't see that — split-borrow via `mem::take` + restore.
        let ops = std::mem::take(&mut self.last_ops);
        self.prepare_paint(
            &ops,
            is_registered,
            samples_backdrop,
            text,
            scale_factor,
            timings,
        );
        self.last_ops = ops;
    }

    /// Standard "no custom time-driven shaders" closure for
    /// [`Self::prepare_layout`]. Backends that haven't wired up the
    /// custom-shader registry yet pass this; only stock shaders that
    /// self-report via `is_continuous()` participate in the scan.
    pub fn no_time_shaders(_shader: &ShaderHandle) -> bool {
        false
    }

    /// Re-evaluate the paint-lane deadline against the currently-cached
    /// [`Self::last_ops`]. Used by backends serving a paint-only frame
    /// (`repaint(...)`) so they can re-arm
    /// [`PrepareResult::next_paint_redraw_in`] without re-running
    /// `prepare_layout`. Returns `Some(Duration::ZERO)` when any cached
    /// op still binds a continuous shader.
    pub fn scan_continuous_shaders<F>(&self, samples_time: F) -> Option<std::time::Duration>
    where
        F: Fn(&ShaderHandle) -> bool,
    {
        let any = self
            .last_ops
            .iter()
            .any(|op| op_is_continuous(op, &samples_time));
        if any {
            Some(std::time::Duration::ZERO)
        } else {
            None
        }
    }

    /// Walk the resolved `DrawOp` list, packing quads into
    /// `quad_scratch` + grouping them into `runs`, interleaving text
    /// records via the backend-supplied [`TextRecorder`]. Returns the
    /// number of quad instances written (so the backend can size its
    /// instance buffer).
    ///
    /// Callers must call `text.frame_begin()` themselves *before*
    /// invoking this — `prepare_paint` does not call it for them
    /// because backends often want to clear other per-frame text
    /// scratch in the same step.
    pub fn prepare_paint<F1, F2>(
        &mut self,
        ops: &[DrawOp],
        is_registered: F1,
        samples_backdrop: F2,
        text: &mut dyn TextRecorder,
        scale_factor: f32,
        timings: &mut PrepareTimings,
    ) where
        F1: Fn(&ShaderHandle) -> bool,
        F2: Fn(&ShaderHandle) -> bool,
    {
        crate::profile_span!("prepare::paint");
        let t0 = Instant::now();
        self.quad_scratch.clear();
        self.runs.clear();
        self.paint_items.clear();

        let mut current: Option<(ShaderHandle, Option<PhysicalScissor>)> = None;
        let mut run_first: u32 = 0;
        // At most one snapshot per frame. Auto-inserted before
        // the first paint that samples the backdrop.
        let mut snapshot_emitted = false;

        for op in ops {
            match op {
                DrawOp::Quad {
                    rect,
                    scissor,
                    shader,
                    uniforms,
                    ..
                } => {
                    if !is_registered(shader) {
                        continue;
                    }
                    if !paint_rect_visible(*rect, *scissor, self.viewport_px, scale_factor) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    let phys = physical_scissor(*scissor, scale_factor, self.viewport_px);
                    if matches!(phys, Some(s) if s.w == 0 || s.h == 0) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    if !snapshot_emitted && samples_backdrop(shader) {
                        close_run(
                            &mut self.runs,
                            &mut self.paint_items,
                            current,
                            run_first,
                            self.quad_scratch.len() as u32,
                        );
                        current = None;
                        run_first = self.quad_scratch.len() as u32;
                        self.paint_items.push(PaintItem::BackdropSnapshot);
                        snapshot_emitted = true;
                    }
                    let inst = pack_instance(*rect, *shader, uniforms);

                    let key = (*shader, phys);
                    if current != Some(key) {
                        close_run(
                            &mut self.runs,
                            &mut self.paint_items,
                            current,
                            run_first,
                            self.quad_scratch.len() as u32,
                        );
                        current = Some(key);
                        run_first = self.quad_scratch.len() as u32;
                    }
                    self.quad_scratch.push(inst);
                }
                DrawOp::GlyphRun {
                    rect,
                    scissor,
                    color,
                    text: glyph_text,
                    size,
                    line_height,
                    family,
                    mono_family,
                    weight,
                    mono,
                    wrap,
                    anchor,
                    underline,
                    strikethrough,
                    link,
                    ..
                } => {
                    let phys = physical_scissor(*scissor, scale_factor, self.viewport_px);
                    if matches!(phys, Some(s) if s.w == 0 || s.h == 0) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    if !paint_rect_visible(*rect, *scissor, self.viewport_px, scale_factor) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    close_run(
                        &mut self.runs,
                        &mut self.paint_items,
                        current,
                        run_first,
                        self.quad_scratch.len() as u32,
                    );
                    current = None;
                    run_first = self.quad_scratch.len() as u32;

                    let mut style = crate::text::atlas::RunStyle::new(*weight, *color)
                        .family(*family)
                        .mono_family(*mono_family);
                    if *mono {
                        style = style.mono();
                    }
                    if *underline {
                        style = style.underline();
                    }
                    if *strikethrough {
                        style = style.strikethrough();
                    }
                    if let Some(url) = link {
                        style = style.with_link(url.clone());
                    }
                    let layers = text.record(
                        *rect,
                        phys,
                        &style,
                        glyph_text,
                        *size,
                        *line_height,
                        *wrap,
                        *anchor,
                        scale_factor,
                    );
                    for index in layers {
                        self.paint_items.push(PaintItem::Text(index));
                    }
                }
                DrawOp::AttributedText {
                    rect,
                    scissor,
                    runs,
                    size,
                    line_height,
                    wrap,
                    anchor,
                    ..
                } => {
                    let phys = physical_scissor(*scissor, scale_factor, self.viewport_px);
                    if matches!(phys, Some(s) if s.w == 0 || s.h == 0) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    if !paint_rect_visible(*rect, *scissor, self.viewport_px, scale_factor) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    close_run(
                        &mut self.runs,
                        &mut self.paint_items,
                        current,
                        run_first,
                        self.quad_scratch.len() as u32,
                    );
                    current = None;
                    run_first = self.quad_scratch.len() as u32;

                    let layers = text.record_runs(
                        *rect,
                        phys,
                        runs,
                        *size,
                        *line_height,
                        *wrap,
                        *anchor,
                        scale_factor,
                    );
                    for index in layers {
                        self.paint_items.push(PaintItem::Text(index));
                    }
                }
                DrawOp::Icon {
                    rect,
                    scissor,
                    source,
                    color,
                    size,
                    stroke_width,
                    ..
                } => {
                    let phys = physical_scissor(*scissor, scale_factor, self.viewport_px);
                    if matches!(phys, Some(s) if s.w == 0 || s.h == 0) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    if !paint_rect_visible(*rect, *scissor, self.viewport_px, scale_factor) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    close_run(
                        &mut self.runs,
                        &mut self.paint_items,
                        current,
                        run_first,
                        self.quad_scratch.len() as u32,
                    );
                    current = None;
                    run_first = self.quad_scratch.len() as u32;

                    let recorded = text.record_icon(
                        *rect,
                        phys,
                        source,
                        *color,
                        *size,
                        *stroke_width,
                        scale_factor,
                    );
                    match recorded {
                        RecordedPaint::Text(layers) => {
                            for index in layers {
                                self.paint_items.push(PaintItem::Text(index));
                            }
                        }
                        RecordedPaint::Icon(runs) => {
                            for index in runs {
                                self.paint_items.push(PaintItem::IconRun(index));
                            }
                        }
                    }
                }
                DrawOp::Image {
                    rect,
                    scissor,
                    image,
                    tint,
                    radius,
                    fit,
                    ..
                } => {
                    let phys = physical_scissor(*scissor, scale_factor, self.viewport_px);
                    if matches!(phys, Some(s) if s.w == 0 || s.h == 0) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    if !paint_rect_visible(*rect, *scissor, self.viewport_px, scale_factor) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    close_run(
                        &mut self.runs,
                        &mut self.paint_items,
                        current,
                        run_first,
                        self.quad_scratch.len() as u32,
                    );
                    current = None;
                    run_first = self.quad_scratch.len() as u32;

                    let recorded =
                        text.record_image(*rect, phys, image, *tint, *radius, *fit, scale_factor);
                    for index in recorded {
                        self.paint_items.push(PaintItem::Image(index));
                    }
                }
                DrawOp::AppTexture {
                    rect,
                    scissor,
                    texture,
                    alpha,
                    transform,
                    ..
                } => {
                    let phys = physical_scissor(*scissor, scale_factor, self.viewport_px);
                    if matches!(phys, Some(s) if s.w == 0 || s.h == 0) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    if !paint_rect_visible(*rect, *scissor, self.viewport_px, scale_factor) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    close_run(
                        &mut self.runs,
                        &mut self.paint_items,
                        current,
                        run_first,
                        self.quad_scratch.len() as u32,
                    );
                    current = None;
                    run_first = self.quad_scratch.len() as u32;

                    let recorded = text.record_app_texture(
                        *rect,
                        phys,
                        texture,
                        *alpha,
                        *transform,
                        scale_factor,
                    );
                    for index in recorded {
                        self.paint_items.push(PaintItem::AppTexture(index));
                    }
                }
                DrawOp::Vector {
                    rect,
                    scissor,
                    asset,
                    render_mode,
                    ..
                } => {
                    let phys = physical_scissor(*scissor, scale_factor, self.viewport_px);
                    if matches!(phys, Some(s) if s.w == 0 || s.h == 0) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    if !paint_rect_visible(*rect, *scissor, self.viewport_px, scale_factor) {
                        timings.paint_culled_ops += 1;
                        continue;
                    }
                    close_run(
                        &mut self.runs,
                        &mut self.paint_items,
                        current,
                        run_first,
                        self.quad_scratch.len() as u32,
                    );
                    current = None;
                    run_first = self.quad_scratch.len() as u32;

                    let recorded =
                        text.record_vector(*rect, phys, asset, *render_mode, scale_factor);
                    for index in recorded {
                        self.paint_items.push(PaintItem::Vector(index));
                    }
                }
                DrawOp::BackdropSnapshot => {
                    close_run(
                        &mut self.runs,
                        &mut self.paint_items,
                        current,
                        run_first,
                        self.quad_scratch.len() as u32,
                    );
                    current = None;
                    run_first = self.quad_scratch.len() as u32;
                    // Cap at one snapshot per frame; an explicit op only
                    // lands if the auto-emitter hasn't fired yet.
                    if !snapshot_emitted {
                        self.paint_items.push(PaintItem::BackdropSnapshot);
                        snapshot_emitted = true;
                    }
                }
            }
        }
        close_run(
            &mut self.runs,
            &mut self.paint_items,
            current,
            run_first,
            self.quad_scratch.len() as u32,
        );
        timings.paint = Instant::now() - t0;
    }

    /// Take a clone of the laid-out tree for next-frame hit-testing.
    /// Call after the per-frame work completes (GPU upload, atlas
    /// flush, etc.) so the snapshot reflects final geometry. Writes
    /// `timings.snapshot`.
    pub fn snapshot(&mut self, root: &El, timings: &mut PrepareTimings) {
        crate::profile_span!("prepare::snapshot");
        let t0 = Instant::now();
        self.last_tree = Some(root.clone());
        timings.snapshot = Instant::now() - t0;
    }
}

fn paint_rect_visible(
    rect: Rect,
    scissor: Option<Rect>,
    viewport_px: (u32, u32),
    scale_factor: f32,
) -> bool {
    if rect.w <= 0.0 || rect.h <= 0.0 {
        return false;
    }
    let scale = scale_factor.max(f32::EPSILON);
    let viewport = Rect::new(
        0.0,
        0.0,
        viewport_px.0 as f32 / scale,
        viewport_px.1 as f32 / scale,
    );
    let Some(clip) = scissor.map_or(Some(viewport), |s| s.intersect(viewport)) else {
        return false;
    };
    rect.intersect(clip).is_some()
}

/// Whether this op binds a shader whose output depends on `frame.time`.
/// Stock shaders self-report through
/// [`crate::shader::StockShader::is_continuous`]; custom shaders
/// answer through the host-supplied closure (which the backend wires
/// to its `samples_time=true` registration set). See
/// [`RunnerCore::prepare_layout`].
fn op_is_continuous<F>(op: &DrawOp, samples_time: &F) -> bool
where
    F: Fn(&ShaderHandle) -> bool,
{
    match op.shader() {
        Some(handle @ ShaderHandle::Stock(s)) => s.is_continuous() || samples_time(handle),
        Some(handle @ ShaderHandle::Custom(_)) => samples_time(handle),
        None => false,
    }
}

/// Walk the El tree and return the tightest [`El::redraw_within`]
/// deadline among visible widgets (rect intersects the viewport, both
/// dimensions positive). Used by [`RunnerCore::prepare_layout`] to
/// surface the inside-out redraw aggregate as
/// [`PrepareResult::next_redraw_in`].
fn aggregate_redraw_within(
    node: &El,
    viewport: Rect,
    rects: &rustc_hash::FxHashMap<String, Rect>,
) -> Option<std::time::Duration> {
    let mut acc: Option<std::time::Duration> = None;
    visit_redraw_within(node, viewport, rects, VisibilityClip::Unclipped, &mut acc);
    acc
}

#[derive(Clone, Copy)]
enum VisibilityClip {
    Unclipped,
    Clipped(Rect),
    Empty,
}

impl VisibilityClip {
    fn intersect(self, rect: Rect) -> Self {
        if rect.w <= 0.0 || rect.h <= 0.0 {
            return Self::Empty;
        }
        match self {
            Self::Unclipped => Self::Clipped(rect),
            Self::Clipped(prev) => prev
                .intersect(rect)
                .map(Self::Clipped)
                .unwrap_or(Self::Empty),
            Self::Empty => Self::Empty,
        }
    }

    fn permits(self, rect: Rect) -> bool {
        if rect.w <= 0.0 || rect.h <= 0.0 {
            return false;
        }
        match self {
            Self::Unclipped => true,
            Self::Clipped(clip) => rect.intersect(clip).is_some(),
            Self::Empty => false,
        }
    }
}

fn visit_redraw_within(
    node: &El,
    viewport: Rect,
    rects: &rustc_hash::FxHashMap<String, Rect>,
    inherited_clip: VisibilityClip,
    acc: &mut Option<std::time::Duration>,
) {
    let rect = rects.get(&node.computed_id).copied();
    if let Some(d) = node.redraw_within {
        if let Some(rect) = rect
            && rect.w > 0.0
            && rect.h > 0.0
            && rect.intersect(viewport).is_some()
            && inherited_clip.permits(rect)
        {
            *acc = Some(match *acc {
                Some(prev) => prev.min(d),
                None => d,
            });
        }
    }
    let child_clip = if node.clip {
        rect.map(|r| inherited_clip.intersect(r))
            .unwrap_or(VisibilityClip::Empty)
    } else {
        inherited_clip
    };
    for child in &node.children {
        visit_redraw_within(child, viewport, rects, child_clip, acc);
    }
}

/// Find the `capture_keys` flag of the node whose `computed_id`
/// equals `id`, walking the laid-out tree. Returns `None` when the id
/// isn't found (the focused target outlived its node — a one-frame
/// race after a rebuild).
pub(crate) fn find_capture_keys(node: &El, id: &str) -> Option<bool> {
    if node.computed_id == id {
        return Some(node.capture_keys);
    }
    node.children.iter().find_map(|c| find_capture_keys(c, id))
}

/// Construct a `SelectionChanged` event carrying the new selection.
fn selection_event(
    new_sel: crate::selection::Selection,
    modifiers: KeyModifiers,
    pointer: Option<(f32, f32)>,
) -> UiEvent {
    UiEvent {
        kind: UiEventKind::SelectionChanged,
        key: None,
        target: None,
        pointer,
        key_press: None,
        text: None,
        selection: Some(new_sel),
        modifiers,
        click_count: 0,
        path: None,
    }
}

/// Resolve the head's [`SelectionPoint`] for the current pointer
/// position during a drag. Browser-style projection rules:
///
/// - If the pointer hits a selectable leaf, head goes there.
/// - Otherwise, head goes to the closest selectable leaf in document
///   order, with `(x, y)` projected onto that leaf's vertical extent.
///   Above all leaves → first leaf at byte 0; below all → last leaf
///   at end; in the gap between two adjacent leaves → whichever is
///   nearer in y.
/// - Horizontally outside the chosen leaf's text → snap to the
///   leaf's left edge (byte 0) or right edge (`text.len()`).
fn head_for_drag(
    root: &El,
    ui_state: &UiState,
    point: (f32, f32),
) -> Option<crate::selection::SelectionPoint> {
    if let Some(p) = hit_test::selection_point_at(root, ui_state, point) {
        return Some(p);
    }

    let order = &ui_state.selection.order;
    if order.is_empty() {
        return None;
    }
    // Prefer a leaf whose vertical extent contains the pointer's y;
    // otherwise pick the y-closest leaf. min_by visits in document
    // order so ties (multiple leaves at the same y-distance) resolve
    // to the earliest one.
    let target = order
        .iter()
        .find(|t| point.1 >= t.rect.y && point.1 < t.rect.y + t.rect.h)
        .or_else(|| {
            order.iter().min_by(|a, b| {
                let da = y_distance(a.rect, point.1);
                let db = y_distance(b.rect, point.1);
                da.partial_cmp(&db).unwrap_or(std::cmp::Ordering::Equal)
            })
        })?;
    let target_rect = target.rect;
    let cy = point
        .1
        .clamp(target_rect.y, target_rect.y + target_rect.h - 1.0);
    if let Some(p) = hit_test::selection_point_at(root, ui_state, (point.0, cy)) {
        return Some(p);
    }
    // Couldn't hit-test (likely because the pointer's x is outside
    // the leaf's rendered text width). Snap to the nearest edge.
    let leaf_len = find_text_len(root, &target.node_id).unwrap_or(0);
    let byte = if point.0 < target_rect.x { 0 } else { leaf_len };
    Some(crate::selection::SelectionPoint {
        key: target.key.clone(),
        byte,
    })
}

fn selection_range_for_drag(
    root: &El,
    ui_state: &UiState,
    drag: &crate::state::SelectionDrag,
    raw_head: crate::selection::SelectionPoint,
) -> (
    crate::selection::SelectionPoint,
    crate::selection::SelectionPoint,
) {
    match drag.granularity {
        SelectionDragGranularity::Character => (drag.anchor.clone(), raw_head),
        SelectionDragGranularity::Word => {
            let text = crate::selection::find_keyed_text(root, &raw_head.key).unwrap_or_default();
            let (lo, hi) = crate::selection::word_range_at(&text, raw_head.byte);
            if point_cmp(ui_state, &raw_head, &drag.anchor) == Ordering::Less {
                (
                    drag.head.clone(),
                    crate::selection::SelectionPoint::new(raw_head.key, lo),
                )
            } else {
                (
                    drag.anchor.clone(),
                    crate::selection::SelectionPoint::new(raw_head.key, hi),
                )
            }
        }
        SelectionDragGranularity::Leaf => {
            let len = crate::selection::find_keyed_text(root, &raw_head.key)
                .map(|text| text.len())
                .unwrap_or(raw_head.byte);
            if point_cmp(ui_state, &raw_head, &drag.anchor) == Ordering::Less {
                (
                    drag.head.clone(),
                    crate::selection::SelectionPoint::new(raw_head.key, 0),
                )
            } else {
                (
                    drag.anchor.clone(),
                    crate::selection::SelectionPoint::new(raw_head.key, len),
                )
            }
        }
    }
}

fn point_cmp(
    ui_state: &UiState,
    a: &crate::selection::SelectionPoint,
    b: &crate::selection::SelectionPoint,
) -> Ordering {
    let order_index = |key: &str| {
        ui_state
            .selection
            .order
            .iter()
            .position(|target| target.key == key)
            .unwrap_or(usize::MAX)
    };
    order_index(&a.key)
        .cmp(&order_index(&b.key))
        .then_with(|| a.byte.cmp(&b.byte))
}

fn y_distance(rect: Rect, y: f32) -> f32 {
    if y < rect.y {
        rect.y - y
    } else if y > rect.y + rect.h {
        y - (rect.y + rect.h)
    } else {
        0.0
    }
}

fn find_text_len(node: &El, id: &str) -> Option<usize> {
    if node.computed_id == id {
        if let Some(source) = &node.selection_source {
            return Some(source.visible_len());
        }
        return node.text.as_ref().map(|t| t.len());
    }
    node.children.iter().find_map(|c| find_text_len(c, id))
}

/// Recorded output from an icon draw op. Backends without a vector-icon
/// path use `Text` fallback layers; wgpu can return dedicated icon runs.
pub enum RecordedPaint {
    Text(Range<usize>),
    Icon(Range<usize>),
}

/// Glyph-recording surface implemented by each backend's `TextPaint`.
/// `prepare_paint` calls into it exactly the same way wgpu and vulkano
/// would call their per-backend equivalents.
pub trait TextRecorder {
    /// Append per-glyph instances for `text` and return the range of
    /// indices written into the backend's `TextLayer` storage. Each
    /// returned index lands in `paint_items` as a `PaintItem::Text`.
    ///
    /// `style` carries weight + color + (optional) decoration flags
    /// — backends fold it into a single-element `(text, style)` slice
    /// and run the same shaping path as [`Self::record_runs`].
    #[allow(clippy::too_many_arguments)]
    fn record(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        style: &RunStyle,
        text: &str,
        size: f32,
        line_height: f32,
        wrap: TextWrap,
        anchor: TextAnchor,
        scale_factor: f32,
    ) -> Range<usize>;

    /// Append per-glyph instances for an attributed paragraph (one
    /// shaped run with per-character RunStyle metadata). Wrapping
    /// decisions cross run boundaries — the result is one ShapedRun
    /// just like a single-style call.
    #[allow(clippy::too_many_arguments)]
    fn record_runs(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        runs: &[(String, RunStyle)],
        size: f32,
        line_height: f32,
        wrap: TextWrap,
        anchor: TextAnchor,
        scale_factor: f32,
    ) -> Range<usize>;

    /// Append a vector icon. Backends with a native vector painter
    /// override this; the default keeps experimental/simple backends on
    /// the previous text-symbol fallback. Built-in icons fall back to
    /// their named glyph; app-supplied SVG icons fall back to a
    /// generic placeholder since they have no canonical glyph.
    #[allow(clippy::too_many_arguments)]
    fn record_icon(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        source: &crate::svg_icon::IconSource,
        color: Color,
        size: f32,
        _stroke_width: f32,
        scale_factor: f32,
    ) -> RecordedPaint {
        let glyph = match source {
            crate::svg_icon::IconSource::Builtin(name) => name.fallback_glyph(),
            crate::svg_icon::IconSource::Custom(_) => "?",
        };
        RecordedPaint::Text(self.record(
            rect,
            scissor,
            &RunStyle::new(FontWeight::Regular, color),
            glyph,
            size,
            crate::text::metrics::line_height(size),
            TextWrap::NoWrap,
            TextAnchor::Middle,
            scale_factor,
        ))
    }

    /// Append a raster image draw. Backends with texture sampling
    /// override this and return one or more indices into their image
    /// storage (each index lands in `paint_items` as
    /// `PaintItem::Image`). The default returns an empty range —
    /// backends without raster support paint nothing for image Els
    /// (the SVG fallback emits a labelled placeholder rect on its own).
    #[allow(clippy::too_many_arguments)]
    fn record_image(
        &mut self,
        _rect: Rect,
        _scissor: Option<PhysicalScissor>,
        _image: &crate::image::Image,
        _tint: Option<Color>,
        _radius: crate::tree::Corners,
        _fit: crate::image::ImageFit,
        _scale_factor: f32,
    ) -> Range<usize> {
        0..0
    }

    /// Append an app-owned-texture composite. Backends with surface
    /// support override this and return one or more indices into their
    /// surface storage (each lands in `paint_items` as
    /// `PaintItem::AppTexture`). The default returns an empty range so
    /// backends without surface support paint nothing for surface Els.
    fn record_app_texture(
        &mut self,
        _rect: Rect,
        _scissor: Option<PhysicalScissor>,
        _texture: &crate::surface::AppTexture,
        _alpha: crate::surface::SurfaceAlpha,
        _transform: crate::affine::Affine2,
        _scale_factor: f32,
    ) -> Range<usize> {
        0..0
    }

    /// Append an app-supplied vector draw. Backends with vector
    /// support override this and return one or more indices into their
    /// vector storage (each lands in `paint_items` as
    /// `PaintItem::Vector`). The default returns an empty range so
    /// backends without vector support paint nothing.
    fn record_vector(
        &mut self,
        _rect: Rect,
        _scissor: Option<PhysicalScissor>,
        _asset: &crate::vector::VectorAsset,
        _render_mode: crate::vector::VectorRenderMode,
        _scale_factor: f32,
    ) -> Range<usize> {
        0..0
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::shader::{ShaderHandle, StockShader, UniformBlock};

    /// Minimal recorder for tests that don't exercise the text path.
    struct NoText;
    impl TextRecorder for NoText {
        fn record(
            &mut self,
            _rect: Rect,
            _scissor: Option<PhysicalScissor>,
            _style: &RunStyle,
            _text: &str,
            _size: f32,
            _line_height: f32,
            _wrap: TextWrap,
            _anchor: TextAnchor,
            _scale_factor: f32,
        ) -> Range<usize> {
            0..0
        }
        fn record_runs(
            &mut self,
            _rect: Rect,
            _scissor: Option<PhysicalScissor>,
            _runs: &[(String, RunStyle)],
            _size: f32,
            _line_height: f32,
            _wrap: TextWrap,
            _anchor: TextAnchor,
            _scale_factor: f32,
        ) -> Range<usize> {
            0..0
        }
    }

    #[derive(Default)]
    struct CountingText {
        records: usize,
    }

    impl TextRecorder for CountingText {
        fn record(
            &mut self,
            _rect: Rect,
            _scissor: Option<PhysicalScissor>,
            _style: &RunStyle,
            _text: &str,
            _size: f32,
            _line_height: f32,
            _wrap: TextWrap,
            _anchor: TextAnchor,
            _scale_factor: f32,
        ) -> Range<usize> {
            self.records += 1;
            0..0
        }

        fn record_runs(
            &mut self,
            _rect: Rect,
            _scissor: Option<PhysicalScissor>,
            _runs: &[(String, RunStyle)],
            _size: f32,
            _line_height: f32,
            _wrap: TextWrap,
            _anchor: TextAnchor,
            _scale_factor: f32,
        ) -> Range<usize> {
            self.records += 1;
            0..0
        }
    }

    fn empty_text_layout(line_height: f32) -> crate::text::metrics::TextLayout {
        crate::text::metrics::TextLayout {
            lines: Vec::new(),
            width: 0.0,
            height: 0.0,
            line_height,
        }
    }

    // ---- input plumbing ----

    /// A tree with one focusable button at (10,10,80,40) keyed "btn",
    /// plus an optional capture_keys text input at (10,60,80,40) keyed
    /// "ti". layout() runs against a 200x200 viewport so the rects
    /// land where we expect.
    fn lay_out_input_tree(capture: bool) -> RunnerCore {
        use crate::tree::*;
        let ti = if capture {
            crate::widgets::text::text("input").key("ti").capture_keys()
        } else {
            crate::widgets::text::text("noop").key("ti").focusable()
        };
        let mut tree =
            crate::column([crate::widgets::button::button("Btn").key("btn"), ti]).padding(10.0);
        let mut core = RunnerCore::new();
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 200.0, 200.0),
        );
        core.ui_state.sync_focus_order(&tree);
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);
        core
    }

    #[test]
    fn pointer_up_emits_pointer_up_then_click() {
        let mut core = lay_out_input_tree(false);
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_moved(cx, cy);
        core.pointer_down(cx, cy, PointerButton::Primary);
        let events = core.pointer_up(cx, cy, PointerButton::Primary);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        assert_eq!(kinds, vec![UiEventKind::PointerUp, UiEventKind::Click]);
    }

    /// Build a tree containing a single inline paragraph with one
    /// linked run, layout to a fixed viewport, and return the runner +
    /// the absolute rect of the paragraph. The linked text is long
    /// enough that probes well into the paragraph land safely inside
    /// the link for any plausible proportional font.
    fn lay_out_link_tree() -> (RunnerCore, Rect, &'static str) {
        use crate::tree::*;
        const URL: &str = "https://github.com/computer-whisperer/aetna";
        let mut tree = crate::column([crate::text_runs([
            crate::text("Visit "),
            crate::text("github.com/computer-whisperer/aetna").link(URL),
            crate::text("."),
        ])])
        .padding(10.0);
        let mut core = RunnerCore::new();
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 600.0, 200.0),
        );
        core.ui_state.sync_focus_order(&tree);
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);
        let para = core
            .last_tree
            .as_ref()
            .and_then(|t| t.children.first())
            .map(|p| core.ui_state.rect(&p.computed_id))
            .expect("paragraph rect");
        (core, para, URL)
    }

    #[test]
    fn pointer_up_on_link_emits_link_activated_with_url() {
        let (mut core, para, url) = lay_out_link_tree();
        // Probe ~100 logical pixels in — past the "Visit " prefix
        // (~40px in default UI font) and well inside the long linked
        // run, which extends ~250+px from there.
        let cx = para.x + 100.0;
        let cy = para.y + para.h * 0.5;
        core.pointer_moved(cx, cy);
        core.pointer_down(cx, cy, PointerButton::Primary);
        let events = core.pointer_up(cx, cy, PointerButton::Primary);
        let link = events
            .iter()
            .find(|e| e.kind == UiEventKind::LinkActivated)
            .expect("LinkActivated event");
        assert_eq!(link.key.as_deref(), Some(url));
    }

    #[test]
    fn pointer_up_after_drag_off_link_does_not_activate() {
        let (mut core, para, _url) = lay_out_link_tree();
        let press_x = para.x + 100.0;
        let cy = para.y + para.h * 0.5;
        core.pointer_moved(press_x, cy);
        core.pointer_down(press_x, cy, PointerButton::Primary);
        // Release far below the paragraph — the user dragged off the
        // link before letting go, which native browsers treat as
        // cancel.
        let events = core.pointer_up(press_x, 180.0, PointerButton::Primary);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        assert!(
            !kinds.contains(&UiEventKind::LinkActivated),
            "drag-off-link should cancel the link activation; got {kinds:?}",
        );
    }

    #[test]
    fn pointer_moved_over_link_resolves_cursor_to_pointer_and_requests_redraw() {
        use crate::cursor::Cursor;
        let (mut core, para, _url) = lay_out_link_tree();
        let cx = para.x + 100.0;
        let cy = para.y + para.h * 0.5;
        // Pointer initially well outside the paragraph.
        let initial = core.pointer_moved(para.x - 50.0, cy);
        assert!(
            !initial.needs_redraw,
            "moving in empty space shouldn't request a redraw"
        );
        let tree = core.last_tree.as_ref().expect("tree").clone();
        assert_eq!(
            core.ui_state.cursor(&tree),
            Cursor::Default,
            "no link under pointer → default cursor"
        );
        // Move onto the link — needs_redraw flips so the host
        // re-resolves the cursor on the next frame.
        let onto = core.pointer_moved(cx, cy);
        assert!(
            onto.needs_redraw,
            "entering a link region should flag a redraw so the cursor refresh isn't stale"
        );
        assert_eq!(
            core.ui_state.cursor(&tree),
            Cursor::Pointer,
            "pointer over a link → Pointer cursor"
        );
        // Move back off — should flag a redraw again so the cursor
        // returns to Default.
        let off = core.pointer_moved(para.x - 50.0, cy);
        assert!(
            off.needs_redraw,
            "leaving a link region should flag a redraw"
        );
        assert_eq!(core.ui_state.cursor(&tree), Cursor::Default);
    }

    #[test]
    fn pointer_up_on_unlinked_text_does_not_emit_link_activated() {
        let (mut core, para, _url) = lay_out_link_tree();
        // Click 1px in from the left edge — inside the "Visit "
        // prefix, before the linked run starts.
        let cx = para.x + 1.0;
        let cy = para.y + para.h * 0.5;
        core.pointer_moved(cx, cy);
        core.pointer_down(cx, cy, PointerButton::Primary);
        let events = core.pointer_up(cx, cy, PointerButton::Primary);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        assert!(
            !kinds.contains(&UiEventKind::LinkActivated),
            "click on the unlinked prefix should not surface a link event; got {kinds:?}",
        );
    }

    #[test]
    fn pointer_up_off_target_emits_only_pointer_up() {
        let mut core = lay_out_input_tree(false);
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        // Release off-target (well outside any keyed node).
        let events = core.pointer_up(180.0, 180.0, PointerButton::Primary);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        assert_eq!(
            kinds,
            vec![UiEventKind::PointerUp],
            "drag-off-target should still surface PointerUp so widgets see drag-end"
        );
    }

    #[test]
    fn pointer_moved_while_pressed_emits_drag() {
        let mut core = lay_out_input_tree(false);
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        let drag = core
            .pointer_moved(cx + 30.0, cy)
            .events
            .into_iter()
            .find(|e| e.kind == UiEventKind::Drag)
            .expect("drag while pressed");
        assert_eq!(drag.target.as_ref().map(|t| t.key.as_str()), Some("btn"));
        assert_eq!(drag.pointer, Some((cx + 30.0, cy)));
    }

    #[test]
    fn toast_dismiss_click_removes_toast_and_suppresses_click_event() {
        use crate::toast::ToastSpec;
        use crate::tree::Size;
        // Build a fresh runner, queue a toast, prepare once so the
        // toast layer is laid out, then synthesize a click on its
        // dismiss button.
        let mut core = RunnerCore::new();
        core.ui_state
            .push_toast(ToastSpec::success("hi"), Instant::now());
        let toast_id = core.ui_state.toasts()[0].id;

        // Build & lay out a tree with the toast layer appended.
        // Root is `stack(...)` (Axis::Overlay) so the synthesized
        // toast layer overlays rather than competing for flex space.
        let mut tree: El = crate::stack(std::iter::empty::<El>())
            .width(Size::Fill(1.0))
            .height(Size::Fill(1.0));
        crate::layout::assign_ids(&mut tree);
        let _ = crate::toast::synthesize_toasts(&mut tree, &mut core.ui_state, Instant::now());
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 800.0, 600.0),
        );
        core.ui_state.sync_focus_order(&tree);
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);

        let dismiss_key = format!("toast-dismiss-{toast_id}");
        let dismiss_rect = core.rect_of_key(&dismiss_key).expect("dismiss button");
        let cx = dismiss_rect.x + dismiss_rect.w * 0.5;
        let cy = dismiss_rect.y + dismiss_rect.h * 0.5;

        core.pointer_down(cx, cy, PointerButton::Primary);
        let events = core.pointer_up(cx, cy, PointerButton::Primary);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        // PointerUp still fires (kept generic so drag-aware widgets
        // observe drag-end); Click is intercepted by the toast
        // bookkeeping.
        assert!(
            !kinds.contains(&UiEventKind::Click),
            "Click on toast-dismiss should not be surfaced: {kinds:?}",
        );
        assert!(
            core.ui_state.toasts().iter().all(|t| t.id != toast_id),
            "toast {toast_id} should be dropped after dismiss-click",
        );
    }

    #[test]
    fn pointer_moved_without_press_emits_no_drag() {
        let mut core = lay_out_input_tree(false);
        let events = core.pointer_moved(50.0, 50.0).events;
        // No press → no Drag emission. Hover-transition events
        // (PointerEnter/Leave) may fire; just assert nothing in the
        // out vec carries the Drag kind.
        assert!(!events.iter().any(|e| e.kind == UiEventKind::Drag));
    }

    #[test]
    fn spinner_in_tree_keeps_needs_redraw_set() {
        // stock::spinner reads frame.time, so the host must keep
        // calling prepare() even when no animation is in flight. Pin
        // the contract: a tree with no other motion still reports
        // needs_redraw=true when a spinner is present.
        use crate::widgets::spinner::spinner;
        let mut tree = crate::column([spinner()]);
        let mut core = RunnerCore::new();
        let mut t = PrepareTimings::default();
        let LayoutPrepared { needs_redraw, .. } = core.prepare_layout(
            &mut tree,
            Rect::new(0.0, 0.0, 200.0, 200.0),
            1.0,
            &mut t,
            RunnerCore::no_time_shaders,
        );
        assert!(
            needs_redraw,
            "tree with a spinner must request continuous redraw",
        );

        // Same shape without a spinner — needs_redraw stays false once
        // any state envelopes settle, demonstrating the signal is
        // spinner-driven rather than always-on.
        let mut bare = crate::column([crate::widgets::text::text("idle")]);
        let mut core2 = RunnerCore::new();
        let mut t2 = PrepareTimings::default();
        let LayoutPrepared {
            needs_redraw: needs_redraw2,
            ..
        } = core2.prepare_layout(
            &mut bare,
            Rect::new(0.0, 0.0, 200.0, 200.0),
            1.0,
            &mut t2,
            RunnerCore::no_time_shaders,
        );
        assert!(
            !needs_redraw2,
            "tree without time-driven shaders should idle: got needs_redraw={needs_redraw2}",
        );
    }

    #[test]
    fn custom_samples_time_shader_keeps_needs_redraw_set() {
        // Pin the generalization: a tree binding a *custom* shader
        // whose name appears in the host's `samples_time` set must
        // request continuous redraw the same way stock::spinner does.
        let mut tree = crate::column([crate::tree::El::new(crate::tree::Kind::Custom("anim"))
            .shader(crate::shader::ShaderBinding::custom("my_animated_glow"))
            .width(crate::tree::Size::Fixed(32.0))
            .height(crate::tree::Size::Fixed(32.0))]);
        let mut core = RunnerCore::new();
        let mut t = PrepareTimings::default();

        let LayoutPrepared {
            needs_redraw: idle, ..
        } = core.prepare_layout(
            &mut tree,
            Rect::new(0.0, 0.0, 200.0, 200.0),
            1.0,
            &mut t,
            RunnerCore::no_time_shaders,
        );
        assert!(
            !idle,
            "without a samples_time registration the host should idle",
        );

        let mut t2 = PrepareTimings::default();
        let LayoutPrepared {
            needs_redraw: animated,
            ..
        } = core.prepare_layout(
            &mut tree,
            Rect::new(0.0, 0.0, 200.0, 200.0),
            1.0,
            &mut t2,
            |handle| matches!(handle, ShaderHandle::Custom("my_animated_glow")),
        );
        assert!(
            animated,
            "custom shader registered as samples_time=true must request continuous redraw",
        );
    }

    #[test]
    fn redraw_within_aggregates_to_minimum_visible_deadline() {
        use std::time::Duration;
        let mut tree = crate::column([
            // 16ms
            crate::widgets::text::text("a")
                .redraw_within(Duration::from_millis(16))
                .width(crate::tree::Size::Fixed(20.0))
                .height(crate::tree::Size::Fixed(20.0)),
            // 50ms — the slower request should NOT win against 16ms.
            crate::widgets::text::text("b")
                .redraw_within(Duration::from_millis(50))
                .width(crate::tree::Size::Fixed(20.0))
                .height(crate::tree::Size::Fixed(20.0)),
        ]);
        let mut core = RunnerCore::new();
        let mut t = PrepareTimings::default();
        let LayoutPrepared {
            needs_redraw,
            next_layout_redraw_in,
            ..
        } = core.prepare_layout(
            &mut tree,
            Rect::new(0.0, 0.0, 200.0, 200.0),
            1.0,
            &mut t,
            RunnerCore::no_time_shaders,
        );
        assert!(needs_redraw, "redraw_within must lift the legacy bool");
        assert_eq!(
            next_layout_redraw_in,
            Some(Duration::from_millis(16)),
            "tightest visible deadline wins, on the layout lane",
        );
    }

    #[test]
    fn redraw_within_off_screen_widget_is_ignored() {
        use std::time::Duration;
        // Layout-rect-based visibility: place the animated widget below
        // the viewport via a tall preceding spacer in a hugging
        // column. The child's computed rect is at y≈150, which lies
        // outside a 0..100 viewport, so the visibility filter must
        // skip it and the host must idle.
        let mut tree = crate::column([
            crate::tree::spacer().height(crate::tree::Size::Fixed(150.0)),
            crate::widgets::text::text("offscreen")
                .redraw_within(Duration::from_millis(16))
                .width(crate::tree::Size::Fixed(10.0))
                .height(crate::tree::Size::Fixed(10.0)),
        ]);
        let mut core = RunnerCore::new();
        let mut t = PrepareTimings::default();
        let LayoutPrepared {
            next_layout_redraw_in,
            ..
        } = core.prepare_layout(
            &mut tree,
            Rect::new(0.0, 0.0, 100.0, 100.0),
            1.0,
            &mut t,
            RunnerCore::no_time_shaders,
        );
        assert_eq!(
            next_layout_redraw_in, None,
            "off-screen redraw_within must not contribute to the aggregate",
        );
    }

    #[test]
    fn redraw_within_clipped_out_widget_is_ignored() {
        use std::time::Duration;

        let clipped = crate::column([crate::widgets::text::text("clipped")
            .redraw_within(Duration::from_millis(16))
            .width(crate::tree::Size::Fixed(10.0))
            .height(crate::tree::Size::Fixed(10.0))])
        .clip()
        .width(crate::tree::Size::Fixed(100.0))
        .height(crate::tree::Size::Fixed(20.0))
        .layout(|ctx| {
            vec![Rect::new(
                ctx.container.x,
                ctx.container.y + 30.0,
                10.0,
                10.0,
            )]
        });
        let mut tree = crate::column([clipped]);

        let mut core = RunnerCore::new();
        let mut t = PrepareTimings::default();
        let LayoutPrepared {
            next_layout_redraw_in,
            ..
        } = core.prepare_layout(
            &mut tree,
            Rect::new(0.0, 0.0, 100.0, 100.0),
            1.0,
            &mut t,
            RunnerCore::no_time_shaders,
        );
        assert_eq!(
            next_layout_redraw_in, None,
            "redraw_within inside an inherited clip but outside the clip rect must not contribute",
        );
    }

    #[test]
    fn pointer_moved_within_same_hovered_node_does_not_request_redraw() {
        // Wayland delivers CursorMoved at very high frequency while
        // the cursor sits over the surface. Hosts gate request_redraw
        // on `needs_redraw`; this test pins the contract so we don't
        // regress to the unconditional-redraw behaviour that pegged
        // settings_modal at 100% CPU under cursor activity.
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let (cx, cy) = (btn.x + btn.w * 0.5, btn.y + btn.h * 0.5);

        // First move enters the button — hover identity changes, so a
        // PointerEnter fires (no preceding Leave because no prior
        // hover target).
        let first = core.pointer_moved(cx, cy);
        assert_eq!(first.events.len(), 1);
        assert_eq!(first.events[0].kind, UiEventKind::PointerEnter);
        assert_eq!(first.events[0].key.as_deref(), Some("btn"));
        assert!(
            first.needs_redraw,
            "entering a focusable should warrant a redraw",
        );

        // Same node, slightly different coords. Hover identity is
        // unchanged, no drag is active — must not redraw or emit any
        // events.
        let second = core.pointer_moved(cx + 1.0, cy);
        assert!(second.events.is_empty());
        assert!(
            !second.needs_redraw,
            "identical hover, no drag → host should idle",
        );

        // Moving off the button into empty space changes hover to
        // None — that's a visible transition (envelope ramps down)
        // and a PointerLeave fires.
        let off = core.pointer_moved(0.0, 0.0);
        assert_eq!(off.events.len(), 1);
        assert_eq!(off.events[0].kind, UiEventKind::PointerLeave);
        assert_eq!(off.events[0].key.as_deref(), Some("btn"));
        assert!(
            off.needs_redraw,
            "leaving a hovered node still warrants a redraw",
        );
    }

    #[test]
    fn pointer_moved_between_keyed_targets_emits_leave_then_enter() {
        // Cursor crossing from one keyed node to another emits a paired
        // PointerLeave (old target) followed by PointerEnter (new
        // target). Apps can observe the cleared state before the new
        // one — important for things like cancelling a hover-intent
        // prefetch on the old target before kicking off one for the
        // new.
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let ti = core.rect_of_key("ti").expect("ti rect");

        // Enter btn first.
        let _ = core.pointer_moved(btn.x + 4.0, btn.y + 4.0);

        // Cross to ti.
        let cross = core.pointer_moved(ti.x + 4.0, ti.y + 4.0);
        let kinds: Vec<UiEventKind> = cross.events.iter().map(|e| e.kind).collect();
        assert_eq!(
            kinds,
            vec![UiEventKind::PointerLeave, UiEventKind::PointerEnter],
            "paired Leave-then-Enter on cross-target hover transition",
        );
        assert_eq!(cross.events[0].key.as_deref(), Some("btn"));
        assert_eq!(cross.events[1].key.as_deref(), Some("ti"));
        assert!(cross.needs_redraw);
    }

    #[test]
    fn pointer_left_emits_leave_for_prior_hover() {
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let _ = core.pointer_moved(btn.x + 4.0, btn.y + 4.0);

        let events = core.pointer_left();
        assert_eq!(events.len(), 1);
        assert_eq!(events[0].kind, UiEventKind::PointerLeave);
        assert_eq!(events[0].key.as_deref(), Some("btn"));
    }

    #[test]
    fn pointer_left_with_no_prior_hover_emits_nothing() {
        let mut core = lay_out_input_tree(false);
        // No prior pointer_moved into a keyed target — pointer_left
        // should be a no-op event-wise (state still gets cleared).
        let events = core.pointer_left();
        assert!(events.is_empty());
    }

    #[test]
    fn ui_state_hovered_key_returns_leaf_key() {
        let mut core = lay_out_input_tree(false);
        assert_eq!(core.ui_state().hovered_key(), None);

        let btn = core.rect_of_key("btn").expect("btn rect");
        core.pointer_moved(btn.x + 4.0, btn.y + 4.0);
        assert_eq!(core.ui_state().hovered_key(), Some("btn"));

        // Off-target → None again.
        core.pointer_moved(0.0, 0.0);
        assert_eq!(core.ui_state().hovered_key(), None);
    }

    #[test]
    fn ui_state_is_hovering_within_walks_subtree() {
        // Card (keyed, focusable) wraps an inner icon-button (keyed).
        // is_hovering_within("card") should be true whenever the
        // cursor is on the card body OR on the inner button.
        use crate::tree::*;
        let mut tree = crate::column([crate::stack([
            crate::widgets::button::button("Inner").key("inner_btn")
        ])
        .key("card")
        .focusable()
        .width(Size::Fixed(120.0))
        .height(Size::Fixed(60.0))])
        .padding(20.0);
        let mut core = RunnerCore::new();
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 400.0, 200.0),
        );
        core.ui_state.sync_focus_order(&tree);
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);

        // Pre-hover: false everywhere.
        assert!(!core.ui_state().is_hovering_within("card"));
        assert!(!core.ui_state().is_hovering_within("inner_btn"));

        // Hover the inner button. Both the leaf and its ancestor card
        // should report subtree-hover true.
        let inner = core.rect_of_key("inner_btn").expect("inner rect");
        core.pointer_moved(inner.x + 4.0, inner.y + 4.0);
        assert!(core.ui_state().is_hovering_within("card"));
        assert!(core.ui_state().is_hovering_within("inner_btn"));

        // Unrelated / unknown keys read as false.
        assert!(!core.ui_state().is_hovering_within("not_a_key"));

        // Off the tree — both flip back to false.
        core.pointer_moved(0.0, 0.0);
        assert!(!core.ui_state().is_hovering_within("card"));
        assert!(!core.ui_state().is_hovering_within("inner_btn"));
    }

    #[test]
    fn hover_driven_scale_via_is_hovering_within_plus_animate() {
        // gh#10. The recipe that replaces a declarative
        // hover_translate / hover_scale / hover_tint API: the build
        // closure reads `cx.is_hovering_within(key)` and writes the
        // target prop value; `.animate(...)` eases between build
        // values across frames. End-to-end check that hover transition
        // → eased scale settle.
        use crate::Theme;
        use crate::anim::Timing;
        use crate::tree::*;

        // Helper that mirrors the documented recipe — closure over a
        // hover boolean so the test can drive the rebuild deterministically.
        let build_card = |hovering: bool| -> El {
            let scale = if hovering { 1.05 } else { 1.0 };
            crate::column([crate::stack(
                [crate::widgets::button::button("Inner").key("inner_btn")],
            )
            .key("card")
            .focusable()
            .scale(scale)
            .animate(Timing::SPRING_QUICK)
            .width(Size::Fixed(120.0))
            .height(Size::Fixed(60.0))])
            .padding(20.0)
        };

        let mut core = RunnerCore::new();
        // Settled mode so the animate tick snaps each retarget to its
        // value — lets us verify final-state values without timing.
        core.ui_state
            .set_animation_mode(crate::state::AnimationMode::Settled);

        // Frame 1: not hovering → app builds with scale=1.0.
        let theme = Theme::default();
        let cx_pre = crate::BuildCx::new(&theme).with_ui_state(core.ui_state());
        assert!(!cx_pre.is_hovering_within("card"));
        let mut tree = build_card(cx_pre.is_hovering_within("card"));
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 400.0, 200.0),
        );
        core.ui_state.sync_focus_order(&tree);
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);
        core.ui_state
            .tick_visual_animations(&mut tree, web_time::Instant::now());
        let card_at_rest = tree.children[0].clone();
        assert!((card_at_rest.scale - 1.0).abs() < 1e-3);

        // Hover the card. is_hovering_within flips true.
        let card_rect = core.rect_of_key("card").expect("card rect");
        core.pointer_moved(card_rect.x + 4.0, card_rect.y + 4.0);

        // Frame 2: app sees hovering=true, rebuilds with scale=1.05.
        // Settled animate tick snaps scale to the new target.
        let cx_hot = crate::BuildCx::new(&theme).with_ui_state(core.ui_state());
        assert!(cx_hot.is_hovering_within("card"));
        let mut tree = build_card(cx_hot.is_hovering_within("card"));
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 400.0, 200.0),
        );
        core.ui_state.sync_focus_order(&tree);
        core.snapshot(&tree, &mut t);
        core.ui_state
            .tick_visual_animations(&mut tree, web_time::Instant::now());
        let card_hot = tree.children[0].clone();
        assert!(
            (card_hot.scale - 1.05).abs() < 1e-3,
            "hover should drive card scale to 1.05 via animate; got {}",
            card_hot.scale,
        );

        // Unhover → app rebuilds with scale=1.0; settled tick snaps back.
        core.pointer_moved(0.0, 0.0);
        let cx_cold = crate::BuildCx::new(&theme).with_ui_state(core.ui_state());
        assert!(!cx_cold.is_hovering_within("card"));
        let mut tree = build_card(cx_cold.is_hovering_within("card"));
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 400.0, 200.0),
        );
        core.ui_state.sync_focus_order(&tree);
        core.snapshot(&tree, &mut t);
        core.ui_state
            .tick_visual_animations(&mut tree, web_time::Instant::now());
        let card_after = tree.children[0].clone();
        assert!((card_after.scale - 1.0).abs() < 1e-3);
    }

    #[test]
    fn file_dropped_routes_to_keyed_leaf_at_pointer() {
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let path = std::path::PathBuf::from("/tmp/screenshot.png");
        let events = core.file_dropped(path.clone(), btn.x + 4.0, btn.y + 4.0);
        assert_eq!(events.len(), 1);
        let event = &events[0];
        assert_eq!(event.kind, UiEventKind::FileDropped);
        assert_eq!(event.key.as_deref(), Some("btn"));
        assert_eq!(event.path.as_deref(), Some(path.as_path()));
        assert_eq!(event.pointer, Some((btn.x + 4.0, btn.y + 4.0)));
    }

    #[test]
    fn file_dropped_outside_keyed_surface_emits_window_level_event() {
        let mut core = lay_out_input_tree(false);
        // Drop in the padding band — outside any keyed leaf.
        let path = std::path::PathBuf::from("/tmp/screenshot.png");
        let events = core.file_dropped(path.clone(), 1.0, 1.0);
        assert_eq!(events.len(), 1);
        let event = &events[0];
        assert_eq!(event.kind, UiEventKind::FileDropped);
        assert!(
            event.target.is_none(),
            "drop outside any keyed surface routes window-level",
        );
        assert!(event.key.is_none());
        // Path still flows through so a global drop sink can pick it up.
        assert_eq!(event.path.as_deref(), Some(path.as_path()));
    }

    #[test]
    fn file_hovered_then_cancelled_pair() {
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let path = std::path::PathBuf::from("/tmp/a.png");

        let hover = core.file_hovered(path.clone(), btn.x + 4.0, btn.y + 4.0);
        assert_eq!(hover.len(), 1);
        assert_eq!(hover[0].kind, UiEventKind::FileHovered);
        assert_eq!(hover[0].key.as_deref(), Some("btn"));
        assert_eq!(hover[0].path.as_deref(), Some(path.as_path()));

        let cancel = core.file_hover_cancelled();
        assert_eq!(cancel.len(), 1);
        assert_eq!(cancel[0].kind, UiEventKind::FileHoverCancelled);
        assert!(cancel[0].target.is_none());
        assert!(cancel[0].path.is_none());
    }

    #[test]
    fn build_cx_hover_accessors_default_off_without_state() {
        use crate::Theme;
        let theme = Theme::default();
        let cx = crate::BuildCx::new(&theme);
        assert_eq!(cx.hovered_key(), None);
        assert!(!cx.is_hovering_within("anything"));
    }

    #[test]
    fn build_cx_hover_accessors_delegate_when_state_attached() {
        use crate::Theme;
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        core.pointer_moved(btn.x + 4.0, btn.y + 4.0);

        let theme = Theme::default();
        let cx = crate::BuildCx::new(&theme).with_ui_state(core.ui_state());
        assert_eq!(cx.hovered_key(), Some("btn"));
        assert!(cx.is_hovering_within("btn"));
        assert!(!cx.is_hovering_within("ti"));
    }

    fn lay_out_paragraph_tree() -> RunnerCore {
        use crate::tree::*;
        let mut tree = crate::column([
            crate::widgets::text::text("First paragraph of text.")
                .key("p1")
                .selectable(),
            crate::widgets::text::text("Second paragraph of text.")
                .key("p2")
                .selectable(),
        ])
        .padding(20.0);
        let mut core = RunnerCore::new();
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 400.0, 300.0),
        );
        core.ui_state.sync_focus_order(&tree);
        core.ui_state.sync_selection_order(&tree);
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);
        core
    }

    #[test]
    fn pointer_down_on_selectable_text_emits_selection_changed() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cx = p1.x + 4.0;
        let cy = p1.y + p1.h * 0.5;
        let events = core.pointer_down(cx, cy, PointerButton::Primary);
        let sel_event = events
            .iter()
            .find(|e| e.kind == UiEventKind::SelectionChanged)
            .expect("SelectionChanged emitted");
        let new_sel = sel_event
            .selection
            .as_ref()
            .expect("SelectionChanged carries a selection");
        let range = new_sel.range.as_ref().expect("collapsed selection at hit");
        assert_eq!(range.anchor.key, "p1");
        assert_eq!(range.head.key, "p1");
        assert_eq!(range.anchor.byte, range.head.byte);
        assert!(core.ui_state.selection.drag.is_some());
    }

    #[test]
    fn pointer_drag_on_selectable_text_extends_head() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cx = p1.x + 4.0;
        let cy = p1.y + p1.h * 0.5;
        core.pointer_moved(cx, cy);
        core.pointer_down(cx, cy, PointerButton::Primary);

        // Drag to the right inside p1.
        let events = core.pointer_moved(p1.x + p1.w - 10.0, cy).events;
        let sel_event = events
            .iter()
            .find(|e| e.kind == UiEventKind::SelectionChanged)
            .expect("Drag emits SelectionChanged");
        let new_sel = sel_event.selection.as_ref().unwrap();
        let range = new_sel.range.as_ref().unwrap();
        assert_eq!(range.anchor.key, "p1");
        assert_eq!(range.head.key, "p1");
        assert!(
            range.head.byte > range.anchor.byte,
            "head should advance past anchor (anchor={}, head={})",
            range.anchor.byte,
            range.head.byte
        );
    }

    #[test]
    fn double_click_hold_drag_inside_selectable_word_keeps_word_selected() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cx = p1.x + 4.0;
        let cy = p1.y + p1.h * 0.5;

        core.pointer_down(cx, cy, PointerButton::Primary);
        core.pointer_up(cx, cy, PointerButton::Primary);
        let down = core.pointer_down(cx, cy, PointerButton::Primary);
        let sel = down
            .iter()
            .find(|e| e.kind == UiEventKind::SelectionChanged)
            .and_then(|e| e.selection.as_ref())
            .and_then(|s| s.range.as_ref())
            .expect("double-click selects word");
        assert_eq!(sel.anchor.byte, 0);
        assert_eq!(sel.head.byte, 5);

        let events = core.pointer_moved(cx + 1.0, cy).events;
        assert!(
            !events
                .iter()
                .any(|e| e.kind == UiEventKind::SelectionChanged),
            "drag jitter within the double-clicked word should not collapse the selection"
        );
        let range = core
            .ui_state
            .current_selection
            .range
            .as_ref()
            .expect("selection persists");
        assert_eq!(range.anchor.byte, 0);
        assert_eq!(range.head.byte, 5);
    }

    #[test]
    fn pointer_up_clears_drag_but_keeps_selection() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cx = p1.x + 4.0;
        let cy = p1.y + p1.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        core.pointer_moved(p1.x + p1.w - 10.0, cy);
        let _ = core.pointer_up(p1.x + p1.w - 10.0, cy, PointerButton::Primary);
        assert!(
            core.ui_state.selection.drag.is_none(),
            "drag flag should clear on pointer_up"
        );
        assert!(
            !core.ui_state.current_selection.is_empty(),
            "selection itself should persist after pointer_up"
        );
    }

    #[test]
    fn drag_past_a_leaf_bottom_keeps_head_in_that_leaf_not_anchor() {
        // Regression: a previous helper (`byte_in_anchor_leaf`)
        // projected any out-of-leaf pointer back onto the anchor leaf.
        // That meant moving the cursor below p2's bottom edge while
        // dragging from p1 caused the head to snap home to p1 — the
        // selection band visibly shrank back instead of extending.
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let p2 = core.rect_of_key("p2").expect("p2 rect");
        // Anchor in p1.
        core.pointer_down(p1.x + 4.0, p1.y + p1.h * 0.5, PointerButton::Primary);
        // Drag into p2 first — head migrates.
        core.pointer_moved(p2.x + 8.0, p2.y + p2.h * 0.5);
        // Now move WELL BELOW p2's rect (well below all selectables).
        // Head should remain in p2 (last leaf in this fixture is p2).
        let events = core.pointer_moved(p2.x + 8.0, p2.y + p2.h + 200.0).events;
        let sel = events
            .iter()
            .find(|e| e.kind == UiEventKind::SelectionChanged)
            .map(|e| e.selection.as_ref().unwrap().clone())
            // No SelectionChanged emitted means the value didn't move
            // — read it back from the live UiState directly.
            .unwrap_or_else(|| core.ui_state.current_selection.clone());
        let r = sel.range.as_ref().expect("selection still active");
        assert_eq!(r.anchor.key, "p1", "anchor unchanged");
        assert_eq!(
            r.head.key, "p2",
            "head must stay in p2 even when pointer is below p2's rect"
        );
    }

    #[test]
    fn drag_into_a_sibling_selectable_extends_head_into_that_leaf() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let p2 = core.rect_of_key("p2").expect("p2 rect");
        // Anchor at the start of p1.
        core.pointer_down(p1.x + 4.0, p1.y + p1.h * 0.5, PointerButton::Primary);
        // Drag down into p2.
        let events = core.pointer_moved(p2.x + 8.0, p2.y + p2.h * 0.5).events;
        let sel_event = events
            .iter()
            .find(|e| e.kind == UiEventKind::SelectionChanged)
            .expect("Drag emits SelectionChanged");
        let new_sel = sel_event.selection.as_ref().unwrap();
        let range = new_sel.range.as_ref().unwrap();
        assert_eq!(range.anchor.key, "p1", "anchor stays in p1");
        assert_eq!(range.head.key, "p2", "head migrates into p2");
    }

    #[test]
    fn pointer_down_on_focusable_owning_selection_does_not_clear_it() {
        // Regression: clicking inside a text_input (focusable but not
        // a `.selectable()` leaf) used to fire SelectionChanged-empty
        // because selection_point_at missed and the runtime's
        // clear-fallback didn't notice the click landed on the same
        // widget that owned the active selection. The input's
        // PointerDown set the caret, then the empty SelectionChanged
        // collapsed it back to byte 0 every other click.
        let mut core = lay_out_input_tree(true);
        // Seed a selection in the input's key — this is what the
        // text_input would have written back via apply_event_with.
        core.set_selection(crate::selection::Selection::caret("ti", 3));
        let ti = core.rect_of_key("ti").expect("ti rect");
        let cx = ti.x + ti.w * 0.5;
        let cy = ti.y + ti.h * 0.5;

        let events = core.pointer_down(cx, cy, PointerButton::Primary);
        let cleared = events.iter().find(|e| {
            e.kind == UiEventKind::SelectionChanged
                && e.selection.as_ref().map(|s| s.is_empty()).unwrap_or(false)
        });
        assert!(
            cleared.is_none(),
            "click on the selection-owning input must not emit a clearing SelectionChanged"
        );
        assert_eq!(
            core.ui_state.current_selection,
            crate::selection::Selection::caret("ti", 3),
            "runtime mirror is preserved when the click owns the selection"
        );
    }

    #[test]
    fn pointer_down_into_a_different_capture_keys_widget_does_not_clear_first() {
        // Regression: clicking into text_input A while the selection
        // lives in text_input B used to trigger the runtime's
        // clear-fallback. The empty SelectionChanged arrived after
        // A's PointerDown (which had set anchor = head = click pos),
        // collapsing the app's selection to default. The next Drag
        // event then read `selection.within(A) = None`, defaulted
        // anchor to 0, and only advanced head — so dragging into A
        // started the selection from byte 0 of the text instead of
        // the click position.
        let mut core = lay_out_input_tree(true);
        // Active selection lives in some other key, not "ti".
        core.set_selection(crate::selection::Selection::caret("other", 4));
        let ti = core.rect_of_key("ti").expect("ti rect");
        let cx = ti.x + ti.w * 0.5;
        let cy = ti.y + ti.h * 0.5;

        let events = core.pointer_down(cx, cy, PointerButton::Primary);
        let cleared = events.iter().any(|e| {
            e.kind == UiEventKind::SelectionChanged
                && e.selection.as_ref().map(|s| s.is_empty()).unwrap_or(false)
        });
        assert!(
            !cleared,
            "click on a different capture_keys widget must not race-clear the selection"
        );
    }

    #[test]
    fn pointer_down_on_non_selectable_clears_existing_selection() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cy = p1.y + p1.h * 0.5;
        // Establish a selection in p1.
        core.pointer_down(p1.x + 4.0, cy, PointerButton::Primary);
        core.pointer_up(p1.x + 4.0, cy, PointerButton::Primary);
        assert!(!core.ui_state.current_selection.is_empty());

        // Press in empty space (no selectable, no focusable).
        let events = core.pointer_down(2.0, 2.0, PointerButton::Primary);
        let cleared = events
            .iter()
            .find(|e| e.kind == UiEventKind::SelectionChanged)
            .expect("clearing emits SelectionChanged");
        let new_sel = cleared.selection.as_ref().unwrap();
        assert!(new_sel.is_empty(), "new selection should be empty");
        assert!(core.ui_state.current_selection.is_empty());
    }

    #[test]
    fn pointer_down_in_dead_space_clears_focus() {
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let cx = btn.x + btn.w * 0.5;
        let cy = btn.y + btn.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        let _ = core.pointer_up(cx, cy, PointerButton::Primary);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("btn")
        );

        core.pointer_down(2.0, 2.0, PointerButton::Primary);

        assert_eq!(core.ui_state.focused.as_ref().map(|t| t.key.as_str()), None);
    }

    #[test]
    fn key_down_bumps_caret_activity_when_focused_widget_captures_keys() {
        // Showcase-style scenario: the app doesn't propagate its
        // Selection back via App::selection(), so set_selection always
        // sees the default-empty value and never bumps. The runtime
        // bump path catches arrow-key navigation directly.
        let mut core = lay_out_input_tree(true);
        let target = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "ti")
            .cloned();
        core.ui_state.set_focus(target); // focus moves → first bump
        let after_focus = core.ui_state.caret.activity_at.expect("focus bump");

        std::thread::sleep(std::time::Duration::from_millis(2));
        let _ = core.key_down(UiKey::ArrowRight, KeyModifiers::default(), false);
        let after_arrow = core
            .ui_state
            .caret
            .activity_at
            .expect("arrow key bumps even without app-side selection");
        assert!(
            after_arrow > after_focus,
            "ArrowRight to a capture_keys focused widget bumps caret activity"
        );
    }

    #[test]
    fn text_input_bumps_caret_activity_when_focused() {
        let mut core = lay_out_input_tree(true);
        let target = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "ti")
            .cloned();
        core.ui_state.set_focus(target);
        let after_focus = core.ui_state.caret.activity_at.unwrap();

        std::thread::sleep(std::time::Duration::from_millis(2));
        let _ = core.text_input("a".into());
        let after_text = core.ui_state.caret.activity_at.unwrap();
        assert!(
            after_text > after_focus,
            "TextInput to focused widget bumps caret activity"
        );
    }

    #[test]
    fn pointer_down_inside_focused_input_bumps_caret_activity() {
        // Clicking again inside an already-focused capture_keys widget
        // doesn't change the focus target, so set_focus is a no-op
        // for activity. The runtime catches this so click-to-move-
        // caret resets the blink.
        let mut core = lay_out_input_tree(true);
        let ti = core.rect_of_key("ti").expect("ti rect");
        let cx = ti.x + ti.w * 0.5;
        let cy = ti.y + ti.h * 0.5;

        // First click → focus moves → bump.
        core.pointer_down(cx, cy, PointerButton::Primary);
        let _ = core.pointer_up(cx, cy, PointerButton::Primary);
        let after_first = core.ui_state.caret.activity_at.unwrap();

        // Second click on the same input → focus doesn't move, but
        // it's still caret-relevant activity.
        std::thread::sleep(std::time::Duration::from_millis(2));
        core.pointer_down(cx + 1.0, cy, PointerButton::Primary);
        let after_second = core
            .ui_state
            .caret
            .activity_at
            .expect("second click bumps too");
        assert!(
            after_second > after_first,
            "click within already-focused capture_keys widget still bumps"
        );
    }

    #[test]
    fn arrow_key_through_apply_event_mutates_selection_and_bumps_on_set() {
        // End-to-end check that the path used by the text_input
        // example does in fact differ-then-bump on each arrow-key
        // press. If this regresses, the caret won't reset its blink
        // when the user moves the cursor — exactly what the polish
        // pass is meant to fix.
        use crate::widgets::text_input;
        let mut sel = crate::selection::Selection::caret("ti", 2);
        let mut value = String::from("hello");

        let mut core = RunnerCore::new();
        // Seed the runtime mirror so the first set_selection below
        // doesn't bump from "default → caret(2)".
        core.set_selection(sel.clone());
        let baseline = core.ui_state.caret.activity_at;

        // Build a synthetic ArrowRight KeyDown for the input's key.
        let arrow_right = UiEvent {
            key: Some("ti".into()),
            target: None,
            pointer: None,
            key_press: Some(crate::event::KeyPress {
                key: UiKey::ArrowRight,
                modifiers: KeyModifiers::default(),
                repeat: false,
            }),
            text: None,
            selection: None,
            modifiers: KeyModifiers::default(),
            click_count: 0,
            path: None,
            kind: UiEventKind::KeyDown,
        };

        // 1. App's on_event would call into this path:
        let mutated = text_input::apply_event(&mut value, &mut sel, "ti", &arrow_right);
        assert!(mutated, "ArrowRight should mutate selection");
        assert_eq!(
            sel.within("ti").unwrap().head,
            3,
            "head moved one char right (h-e-l-l-o, byte 2 → 3)"
        );

        // 2. Next frame's set_selection sees the new value → bump.
        std::thread::sleep(std::time::Duration::from_millis(2));
        core.set_selection(sel);
        let after = core.ui_state.caret.activity_at.unwrap();
        // If a baseline existed, the new bump must be later. Either
        // way the activity is now Some, which the .unwrap() above
        // already enforced.
        if let Some(b) = baseline {
            assert!(after > b, "arrow-key flow should bump activity");
        }
    }

    #[test]
    fn set_selection_bumps_caret_activity_only_when_value_changes() {
        let mut core = lay_out_paragraph_tree();
        // First call with the default selection — no bump (mirror is
        // already default-empty).
        core.set_selection(crate::selection::Selection::default());
        assert!(
            core.ui_state.caret.activity_at.is_none(),
            "no-op set_selection should not bump activity"
        );

        // Move the selection to a real range — bump.
        let sel_a = crate::selection::Selection::caret("p1", 3);
        core.set_selection(sel_a.clone());
        let bumped_at = core
            .ui_state
            .caret
            .activity_at
            .expect("first real selection bumps");

        // Same selection again — must NOT bump (else every frame
        // re-bumps and the caret never blinks).
        core.set_selection(sel_a.clone());
        assert_eq!(
            core.ui_state.caret.activity_at,
            Some(bumped_at),
            "set_selection with same value is a no-op"
        );

        // Caret at a different byte (simulating arrow-key motion) →
        // bump again.
        std::thread::sleep(std::time::Duration::from_millis(2));
        let sel_b = crate::selection::Selection::caret("p1", 7);
        core.set_selection(sel_b);
        let new_bump = core.ui_state.caret.activity_at.expect("second bump");
        assert!(
            new_bump > bumped_at,
            "moving the caret bumps activity again",
        );
    }

    #[test]
    fn escape_clears_active_selection_and_emits_selection_changed() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cy = p1.y + p1.h * 0.5;
        // Drag-select inside p1 to establish a non-empty selection.
        core.pointer_down(p1.x + 4.0, cy, PointerButton::Primary);
        core.pointer_moved(p1.x + p1.w - 10.0, cy);
        core.pointer_up(p1.x + p1.w - 10.0, cy, PointerButton::Primary);
        assert!(!core.ui_state.current_selection.is_empty());

        let events = core.key_down(UiKey::Escape, KeyModifiers::default(), false);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        assert_eq!(
            kinds,
            vec![UiEventKind::Escape, UiEventKind::SelectionChanged],
            "Esc emits Escape (for popover dismiss) AND SelectionChanged"
        );
        let cleared = events
            .iter()
            .find(|e| e.kind == UiEventKind::SelectionChanged)
            .unwrap();
        assert!(cleared.selection.as_ref().unwrap().is_empty());
        assert!(core.ui_state.current_selection.is_empty());
    }

    #[test]
    fn consecutive_clicks_on_same_target_extend_count() {
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let cx = btn.x + btn.w * 0.5;
        let cy = btn.y + btn.h * 0.5;

        // First press: count = 1.
        let down1 = core.pointer_down(cx, cy, PointerButton::Primary);
        let pd1 = down1
            .iter()
            .find(|e| e.kind == UiEventKind::PointerDown)
            .expect("PointerDown emitted");
        assert_eq!(pd1.click_count, 1, "first press starts the sequence");
        let up1 = core.pointer_up(cx, cy, PointerButton::Primary);
        let click1 = up1
            .iter()
            .find(|e| e.kind == UiEventKind::Click)
            .expect("Click emitted");
        assert_eq!(
            click1.click_count, 1,
            "Click carries the same count as its PointerDown"
        );

        // Second press immediately after, same target: count = 2.
        let down2 = core.pointer_down(cx, cy, PointerButton::Primary);
        let pd2 = down2
            .iter()
            .find(|e| e.kind == UiEventKind::PointerDown)
            .unwrap();
        assert_eq!(pd2.click_count, 2, "second press extends the sequence");
        let up2 = core.pointer_up(cx, cy, PointerButton::Primary);
        assert_eq!(
            up2.iter()
                .find(|e| e.kind == UiEventKind::Click)
                .unwrap()
                .click_count,
            2
        );

        // Third: count = 3.
        let down3 = core.pointer_down(cx, cy, PointerButton::Primary);
        let pd3 = down3
            .iter()
            .find(|e| e.kind == UiEventKind::PointerDown)
            .unwrap();
        assert_eq!(pd3.click_count, 3, "third press → triple-click");
        core.pointer_up(cx, cy, PointerButton::Primary);
    }

    #[test]
    fn click_count_resets_when_target_changes() {
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let ti = core.rect_of_key("ti").expect("ti rect");

        // Press on btn → count=1.
        let down1 = core.pointer_down(
            btn.x + btn.w * 0.5,
            btn.y + btn.h * 0.5,
            PointerButton::Primary,
        );
        assert_eq!(
            down1
                .iter()
                .find(|e| e.kind == UiEventKind::PointerDown)
                .unwrap()
                .click_count,
            1
        );
        let _ = core.pointer_up(
            btn.x + btn.w * 0.5,
            btn.y + btn.h * 0.5,
            PointerButton::Primary,
        );

        // Press on ti (different target) → count resets to 1.
        let down2 = core.pointer_down(ti.x + ti.w * 0.5, ti.y + ti.h * 0.5, PointerButton::Primary);
        let pd2 = down2
            .iter()
            .find(|e| e.kind == UiEventKind::PointerDown)
            .unwrap();
        assert_eq!(
            pd2.click_count, 1,
            "press on a new target resets the multi-click sequence"
        );
    }

    #[test]
    fn double_click_on_selectable_text_selects_word_at_hit() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cy = p1.y + p1.h * 0.5;
        // Click near the start of "First paragraph of text." — twice
        // within the multi-click window.
        let cx = p1.x + 4.0;
        core.pointer_down(cx, cy, PointerButton::Primary);
        core.pointer_up(cx, cy, PointerButton::Primary);
        core.pointer_down(cx, cy, PointerButton::Primary);
        // The current selection should now span the first word.
        let sel = &core.ui_state.current_selection;
        let r = sel.range.as_ref().expect("selection set");
        assert_eq!(r.anchor.key, "p1");
        assert_eq!(r.head.key, "p1");
        // "First" is 5 bytes.
        assert_eq!(r.anchor.byte.min(r.head.byte), 0);
        assert_eq!(r.anchor.byte.max(r.head.byte), 5);
    }

    #[test]
    fn triple_click_on_selectable_text_selects_whole_leaf() {
        let mut core = lay_out_paragraph_tree();
        let p1 = core.rect_of_key("p1").expect("p1 rect");
        let cy = p1.y + p1.h * 0.5;
        let cx = p1.x + 4.0;
        core.pointer_down(cx, cy, PointerButton::Primary);
        core.pointer_up(cx, cy, PointerButton::Primary);
        core.pointer_down(cx, cy, PointerButton::Primary);
        core.pointer_up(cx, cy, PointerButton::Primary);
        core.pointer_down(cx, cy, PointerButton::Primary);
        let sel = &core.ui_state.current_selection;
        let r = sel.range.as_ref().expect("selection set");
        assert_eq!(r.anchor.byte, 0);
        // "First paragraph of text." is 24 bytes.
        assert_eq!(r.head.byte, 24);
    }

    #[test]
    fn click_count_resets_when_press_drifts_outside_distance_window() {
        let mut core = lay_out_input_tree(false);
        let btn = core.rect_of_key("btn").expect("btn rect");
        let cx = btn.x + btn.w * 0.5;
        let cy = btn.y + btn.h * 0.5;

        let _ = core.pointer_down(cx, cy, PointerButton::Primary);
        let _ = core.pointer_up(cx, cy, PointerButton::Primary);

        // Move 10 px (well outside MULTI_CLICK_DIST=4.0). Even if same
        // target, the second press starts a fresh sequence.
        let down2 = core.pointer_down(cx + 10.0, cy, PointerButton::Primary);
        let pd2 = down2
            .iter()
            .find(|e| e.kind == UiEventKind::PointerDown)
            .unwrap();
        assert_eq!(pd2.click_count, 1);
    }

    #[test]
    fn escape_with_no_selection_emits_only_escape() {
        let mut core = lay_out_paragraph_tree();
        assert!(core.ui_state.current_selection.is_empty());
        let events = core.key_down(UiKey::Escape, KeyModifiers::default(), false);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        assert_eq!(
            kinds,
            vec![UiEventKind::Escape],
            "no selection → no SelectionChanged side-effect"
        );
    }

    /// Build a 200x200 viewport hosting a `scroll([rows...])` whose
    /// content overflows so the thumb is present.
    fn lay_out_scroll_tree() -> (RunnerCore, String) {
        use crate::tree::*;
        let mut tree = crate::scroll(
            (0..6)
                .map(|i| crate::widgets::text::text(format!("row {i}")).height(Size::Fixed(50.0))),
        )
        .gap(12.0)
        .height(Size::Fixed(200.0));
        let mut core = RunnerCore::new();
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 300.0, 200.0),
        );
        let scroll_id = tree.computed_id.clone();
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);
        (core, scroll_id)
    }

    #[test]
    fn thumb_pointer_down_captures_drag_and_suppresses_events() {
        let (mut core, scroll_id) = lay_out_scroll_tree();
        let thumb = core
            .ui_state
            .scroll
            .thumb_rects
            .get(&scroll_id)
            .copied()
            .expect("scrollable should have a thumb");
        let event = core.pointer_down(
            thumb.x + thumb.w * 0.5,
            thumb.y + thumb.h * 0.5,
            PointerButton::Primary,
        );
        assert!(
            event.is_empty(),
            "thumb press should not emit PointerDown to the app"
        );
        let drag = core
            .ui_state
            .scroll
            .thumb_drag
            .as_ref()
            .expect("scroll.thumb_drag should be set after pointer_down on thumb");
        assert_eq!(drag.scroll_id, scroll_id);
    }

    #[test]
    fn track_click_above_thumb_pages_up_below_pages_down() {
        let (mut core, scroll_id) = lay_out_scroll_tree();
        let track = core
            .ui_state
            .scroll
            .thumb_tracks
            .get(&scroll_id)
            .copied()
            .expect("scrollable should have a track");
        let thumb = core
            .ui_state
            .scroll
            .thumb_rects
            .get(&scroll_id)
            .copied()
            .unwrap();
        let metrics = core
            .ui_state
            .scroll
            .metrics
            .get(&scroll_id)
            .copied()
            .unwrap();

        // Press in the track below the thumb at offset 0 → page down.
        let evt = core.pointer_down(
            track.x + track.w * 0.5,
            thumb.y + thumb.h + 10.0,
            PointerButton::Primary,
        );
        assert!(evt.is_empty(), "track press should not surface PointerDown");
        assert!(
            core.ui_state.scroll.thumb_drag.is_none(),
            "track click outside the thumb should not start a drag",
        );
        let after_down = core.ui_state.scroll_offset(&scroll_id);
        let expected_page = (metrics.viewport_h - SCROLL_PAGE_OVERLAP).max(0.0);
        assert!(
            (after_down - expected_page.min(metrics.max_offset)).abs() < 0.5,
            "page-down offset = {after_down} (expected ~{expected_page})",
        );
        // pointer_up after a track-page is a no-op (no drag to clear).
        let _ = core.pointer_up(0.0, 0.0, PointerButton::Primary);

        // Re-layout to refresh the thumb position at the new offset,
        // then click-to-page up.
        let mut tree = lay_out_scroll_tree_only();
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 300.0, 200.0),
        );
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);
        let track = core
            .ui_state
            .scroll
            .thumb_tracks
            .get(&tree.computed_id)
            .copied()
            .unwrap();
        let thumb = core
            .ui_state
            .scroll
            .thumb_rects
            .get(&tree.computed_id)
            .copied()
            .unwrap();

        core.pointer_down(
            track.x + track.w * 0.5,
            thumb.y - 4.0,
            PointerButton::Primary,
        );
        let after_up = core.ui_state.scroll_offset(&tree.computed_id);
        assert!(
            after_up < after_down,
            "page-up should reduce offset: before={after_down} after={after_up}",
        );
    }

    /// Same fixture as `lay_out_scroll_tree` but doesn't build a
    /// fresh `RunnerCore` — useful when tests want to re-layout
    /// against an existing core to refresh thumb rects after a
    /// scroll offset change.
    fn lay_out_scroll_tree_only() -> El {
        use crate::tree::*;
        crate::scroll(
            (0..6)
                .map(|i| crate::widgets::text::text(format!("row {i}")).height(Size::Fixed(50.0))),
        )
        .gap(12.0)
        .height(Size::Fixed(200.0))
    }

    #[test]
    fn thumb_drag_translates_pointer_delta_into_scroll_offset() {
        let (mut core, scroll_id) = lay_out_scroll_tree();
        let thumb = core
            .ui_state
            .scroll
            .thumb_rects
            .get(&scroll_id)
            .copied()
            .unwrap();
        let metrics = core
            .ui_state
            .scroll
            .metrics
            .get(&scroll_id)
            .copied()
            .unwrap();
        let track_remaining = (metrics.viewport_h - thumb.h).max(0.0);

        let press_y = thumb.y + thumb.h * 0.5;
        core.pointer_down(thumb.x + thumb.w * 0.5, press_y, PointerButton::Primary);
        // Drag 20 px down — offset should advance by `20 * max_offset / track_remaining`.
        let evt = core.pointer_moved(thumb.x + thumb.w * 0.5, press_y + 20.0);
        assert!(
            evt.events.is_empty(),
            "thumb-drag move should suppress Drag event",
        );
        let offset = core.ui_state.scroll_offset(&scroll_id);
        let expected = 20.0 * (metrics.max_offset / track_remaining);
        assert!(
            (offset - expected).abs() < 0.5,
            "offset {offset} (expected {expected})",
        );
        // Overshooting clamps to max_offset.
        core.pointer_moved(thumb.x + thumb.w * 0.5, press_y + 9999.0);
        let offset = core.ui_state.scroll_offset(&scroll_id);
        assert!(
            (offset - metrics.max_offset).abs() < 0.5,
            "overshoot offset {offset} (expected {})",
            metrics.max_offset
        );
        // Release clears the drag without emitting events.
        let events = core.pointer_up(thumb.x, press_y, PointerButton::Primary);
        assert!(events.is_empty(), "thumb release shouldn't emit events");
        assert!(core.ui_state.scroll.thumb_drag.is_none());
    }

    #[test]
    fn secondary_click_does_not_steal_focus_or_press() {
        let mut core = lay_out_input_tree(false);
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        // Focus elsewhere first via primary click on the input.
        let ti_rect = core.rect_of_key("ti").expect("ti rect");
        let tx = ti_rect.x + ti_rect.w * 0.5;
        let ty = ti_rect.y + ti_rect.h * 0.5;
        core.pointer_down(tx, ty, PointerButton::Primary);
        let _ = core.pointer_up(tx, ty, PointerButton::Primary);
        let focused_before = core.ui_state.focused.as_ref().map(|t| t.key.clone());
        // Right-click on the button.
        core.pointer_down(cx, cy, PointerButton::Secondary);
        let events = core.pointer_up(cx, cy, PointerButton::Secondary);
        let kinds: Vec<UiEventKind> = events.iter().map(|e| e.kind).collect();
        assert_eq!(kinds, vec![UiEventKind::SecondaryClick]);
        let focused_after = core.ui_state.focused.as_ref().map(|t| t.key.clone());
        assert_eq!(
            focused_before, focused_after,
            "right-click must not steal focus"
        );
        assert!(
            core.ui_state.pressed.is_none(),
            "right-click must not set primary press"
        );
    }

    #[test]
    fn text_input_routes_to_focused_only() {
        let mut core = lay_out_input_tree(false);
        // No focus yet → no event.
        assert!(core.text_input("a".into()).is_none());
        // Focus the button via primary click.
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        let _ = core.pointer_up(cx, cy, PointerButton::Primary);
        let event = core.text_input("hi".into()).expect("focused → event");
        assert_eq!(event.kind, UiEventKind::TextInput);
        assert_eq!(event.text.as_deref(), Some("hi"));
        assert_eq!(event.target.as_ref().map(|t| t.key.as_str()), Some("btn"));
        // Empty text → no event (some IME paths emit empty composition).
        assert!(core.text_input(String::new()).is_none());
    }

    #[test]
    fn capture_keys_bypasses_tab_traversal_for_focused_node() {
        // Focus the capture_keys input. Tab should NOT move focus —
        // it should be delivered as a raw KeyDown to the input.
        let mut core = lay_out_input_tree(true);
        let ti_rect = core.rect_of_key("ti").expect("ti rect");
        let tx = ti_rect.x + ti_rect.w * 0.5;
        let ty = ti_rect.y + ti_rect.h * 0.5;
        core.pointer_down(tx, ty, PointerButton::Primary);
        let _ = core.pointer_up(tx, ty, PointerButton::Primary);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("ti"),
            "primary click on capture_keys node still focuses it"
        );

        let events = core.key_down(UiKey::Tab, KeyModifiers::default(), false);
        assert_eq!(events.len(), 1, "Tab → exactly one KeyDown");
        let event = &events[0];
        assert_eq!(event.kind, UiEventKind::KeyDown);
        assert_eq!(event.target.as_ref().map(|t| t.key.as_str()), Some("ti"));
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("ti"),
            "Tab inside capture_keys must NOT move focus"
        );
    }

    #[test]
    fn escape_blurs_capture_keys_after_delivering_raw_keydown() {
        let mut core = lay_out_input_tree(true);
        let ti_rect = core.rect_of_key("ti").expect("ti rect");
        let tx = ti_rect.x + ti_rect.w * 0.5;
        let ty = ti_rect.y + ti_rect.h * 0.5;
        core.pointer_down(tx, ty, PointerButton::Primary);
        let _ = core.pointer_up(tx, ty, PointerButton::Primary);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("ti")
        );

        let events = core.key_down(UiKey::Escape, KeyModifiers::default(), false);

        assert_eq!(events.len(), 1);
        let event = &events[0];
        assert_eq!(event.kind, UiEventKind::KeyDown);
        assert_eq!(event.target.as_ref().map(|t| t.key.as_str()), Some("ti"));
        assert!(matches!(
            event.key_press.as_ref().map(|p| &p.key),
            Some(UiKey::Escape)
        ));
        assert_eq!(core.ui_state.focused.as_ref().map(|t| t.key.as_str()), None);
    }

    #[test]
    fn pointer_down_focus_does_not_raise_focus_visible() {
        // `:focus-visible` semantics: clicking a widget focuses it but
        // does NOT light up the focus ring. Verify the runtime flag.
        let mut core = lay_out_input_tree(false);
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("btn"),
            "primary click focuses the button",
        );
        assert!(
            !core.ui_state.focus_visible,
            "click focus must not raise focus_visible — ring stays off",
        );
    }

    #[test]
    fn tab_key_raises_focus_visible_so_ring_appears() {
        let mut core = lay_out_input_tree(false);
        // Pre-focus via click so focus_visible starts low.
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        assert!(!core.ui_state.focus_visible);
        // Tab moves focus and should raise the ring.
        let _ = core.key_down(UiKey::Tab, KeyModifiers::default(), false);
        assert!(
            core.ui_state.focus_visible,
            "Tab must raise focus_visible so the ring paints on the new target",
        );
    }

    #[test]
    fn click_after_tab_clears_focus_visible_again() {
        // Tab raises the ring; a subsequent click on a focusable widget
        // suppresses it again — the user is back on the pointer.
        let mut core = lay_out_input_tree(false);
        let _ = core.key_down(UiKey::Tab, KeyModifiers::default(), false);
        assert!(core.ui_state.focus_visible, "Tab raises ring");
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        assert!(
            !core.ui_state.focus_visible,
            "pointer-down clears focus_visible — ring fades back out",
        );
    }

    #[test]
    fn keypress_on_focused_widget_raises_focus_visible_after_click() {
        // Click a focused-but-non-text widget, then nudge with a key
        // (e.g. arrow on a slider). The keypress is keyboard
        // interaction → ring lights up even though focus didn't move.
        let mut core = lay_out_input_tree(false);
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        assert!(!core.ui_state.focus_visible);
        let _ = core.key_down(UiKey::ArrowRight, KeyModifiers::default(), false);
        assert!(
            core.ui_state.focus_visible,
            "non-Tab key on focused widget raises focus_visible",
        );
    }

    #[test]
    fn arrow_nav_in_sibling_group_raises_focus_visible() {
        let mut core = lay_out_arrow_nav_tree();
        // The fixture pre-sets focus directly without going through
        // the runtime; ensure the flag starts low.
        core.ui_state.set_focus_visible(false);
        let _ = core.key_down(UiKey::ArrowDown, KeyModifiers::default(), false);
        assert!(
            core.ui_state.focus_visible,
            "arrow-nav within an arrow_nav_siblings group is keyboard navigation",
        );
    }

    #[test]
    fn capture_keys_falls_back_to_default_when_focus_off_capturing_node() {
        // Tree has both a normal-focusable button and a capture_keys
        // input. Focus the button (normal focusable). Tab should then
        // do library-default focus traversal.
        let mut core = lay_out_input_tree(true);
        let btn_rect = core.rect_of_key("btn").expect("btn rect");
        let cx = btn_rect.x + btn_rect.w * 0.5;
        let cy = btn_rect.y + btn_rect.h * 0.5;
        core.pointer_down(cx, cy, PointerButton::Primary);
        let _ = core.pointer_up(cx, cy, PointerButton::Primary);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("btn"),
            "primary click focuses button"
        );
        // Tab should move focus to the next focusable (the input).
        let _ = core.key_down(UiKey::Tab, KeyModifiers::default(), false);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("ti"),
            "Tab from non-capturing focused does library-default traversal"
        );
    }

    /// A column whose three buttons sit inside an `arrow_nav_siblings`
    /// parent (the shape `popover_panel` produces). Layout runs against
    /// a 200x300 viewport with 10px padding; each button is 80px wide
    /// and 36px tall stacked vertically, plenty inside the clip.
    fn lay_out_arrow_nav_tree() -> RunnerCore {
        use crate::tree::*;
        let mut tree = crate::column([
            crate::widgets::button::button("Red").key("opt-red"),
            crate::widgets::button::button("Green").key("opt-green"),
            crate::widgets::button::button("Blue").key("opt-blue"),
        ])
        .arrow_nav_siblings()
        .padding(10.0);
        let mut core = RunnerCore::new();
        crate::layout::layout(
            &mut tree,
            &mut core.ui_state,
            Rect::new(0.0, 0.0, 200.0, 300.0),
        );
        core.ui_state.sync_focus_order(&tree);
        let mut t = PrepareTimings::default();
        core.snapshot(&tree, &mut t);
        // Pre-focus the middle option (the typical state right after a
        // popover opens — we'll exercise transitions from there).
        let target = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "opt-green")
            .cloned();
        core.ui_state.set_focus(target);
        core
    }

    #[test]
    fn arrow_nav_moves_focus_among_siblings() {
        let mut core = lay_out_arrow_nav_tree();

        // ArrowDown moves to next sibling, no event emitted (it was
        // consumed by the navigation path).
        let down = core.key_down(UiKey::ArrowDown, KeyModifiers::default(), false);
        assert!(down.is_empty(), "arrow-nav consumes the key event");
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("opt-blue"),
        );

        // ArrowUp moves back.
        core.key_down(UiKey::ArrowUp, KeyModifiers::default(), false);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("opt-green"),
        );

        // Home jumps to first.
        core.key_down(UiKey::Home, KeyModifiers::default(), false);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("opt-red"),
        );

        // End jumps to last.
        core.key_down(UiKey::End, KeyModifiers::default(), false);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("opt-blue"),
        );
    }

    #[test]
    fn arrow_nav_saturates_at_ends() {
        let mut core = lay_out_arrow_nav_tree();
        // Walk to the first option and try to go before it.
        core.key_down(UiKey::Home, KeyModifiers::default(), false);
        core.key_down(UiKey::ArrowUp, KeyModifiers::default(), false);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("opt-red"),
            "ArrowUp at top stays at top — no wrap",
        );
        // Same at the bottom.
        core.key_down(UiKey::End, KeyModifiers::default(), false);
        core.key_down(UiKey::ArrowDown, KeyModifiers::default(), false);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("opt-blue"),
            "ArrowDown at bottom stays at bottom — no wrap",
        );
    }

    /// Build a tree shaped like a real app's `build()` output: a
    /// background row with a "Trigger" button, optionally with a
    /// dropdown popover layered on top.
    fn build_popover_tree(open: bool) -> El {
        use crate::widgets::button::button;
        use crate::widgets::overlay::overlay;
        use crate::widgets::popover::{dropdown, menu_item};
        let mut layers: Vec<El> = vec![button("Trigger").key("trigger")];
        if open {
            layers.push(dropdown(
                "menu",
                "trigger",
                [
                    menu_item("A").key("item-a"),
                    menu_item("B").key("item-b"),
                    menu_item("C").key("item-c"),
                ],
            ));
        }
        overlay(layers).padding(20.0)
    }

    /// Run a full per-frame layout pass against `tree` so all the
    /// post-layout hooks (focus order sync, popover focus stack, etc.)
    /// fire just like a real frame.
    fn run_frame(core: &mut RunnerCore, tree: &mut El) {
        let mut t = PrepareTimings::default();
        core.prepare_layout(
            tree,
            Rect::new(0.0, 0.0, 400.0, 300.0),
            1.0,
            &mut t,
            RunnerCore::no_time_shaders,
        );
        core.snapshot(tree, &mut t);
    }

    #[test]
    fn popover_open_pushes_focus_and_auto_focuses_first_item() {
        let mut core = RunnerCore::new();
        let mut closed = build_popover_tree(false);
        run_frame(&mut core, &mut closed);
        // Pre-focus the trigger as if the user tabbed to it before
        // opening the menu.
        let trigger = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "trigger")
            .cloned();
        core.ui_state.set_focus(trigger);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("trigger"),
        );

        // Open the popover. The runtime should snapshot the trigger
        // onto the focus stack and auto-focus the first menu item.
        let mut open = build_popover_tree(true);
        run_frame(&mut core, &mut open);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("item-a"),
            "popover open should auto-focus the first menu item",
        );
        assert_eq!(
            core.ui_state.popover_focus.focus_stack.len(),
            1,
            "trigger should be saved on the focus stack",
        );
        assert_eq!(
            core.ui_state.popover_focus.focus_stack[0].key.as_str(),
            "trigger",
            "saved focus should be the pre-open target",
        );
    }

    #[test]
    fn popover_close_restores_focus_to_trigger() {
        let mut core = RunnerCore::new();
        let mut closed = build_popover_tree(false);
        run_frame(&mut core, &mut closed);
        let trigger = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "trigger")
            .cloned();
        core.ui_state.set_focus(trigger);

        // Open → focus walks to the menu.
        let mut open = build_popover_tree(true);
        run_frame(&mut core, &mut open);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("item-a"),
        );

        // Close → focus restored to trigger, stack drained.
        let mut closed_again = build_popover_tree(false);
        run_frame(&mut core, &mut closed_again);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("trigger"),
            "closing the popover should pop the saved focus",
        );
        assert!(
            core.ui_state.popover_focus.focus_stack.is_empty(),
            "focus stack should be drained after restore",
        );
    }

    #[test]
    fn popover_close_does_not_override_intentional_focus_move() {
        let mut core = RunnerCore::new();
        // Tree with a second focusable button outside the popover so
        // the user can "click somewhere else" while the menu is open.
        let build = |open: bool| -> El {
            use crate::widgets::button::button;
            use crate::widgets::overlay::overlay;
            use crate::widgets::popover::{dropdown, menu_item};
            let main = crate::row([
                button("Trigger").key("trigger"),
                button("Other").key("other"),
            ]);
            let mut layers: Vec<El> = vec![main];
            if open {
                layers.push(dropdown("menu", "trigger", [menu_item("A").key("item-a")]));
            }
            overlay(layers).padding(20.0)
        };

        let mut closed = build(false);
        run_frame(&mut core, &mut closed);
        let trigger = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "trigger")
            .cloned();
        core.ui_state.set_focus(trigger);

        let mut open = build(true);
        run_frame(&mut core, &mut open);
        assert_eq!(core.ui_state.popover_focus.focus_stack.len(), 1);

        // Simulate an intentional focus move to a sibling that is
        // outside the popover (e.g. the user re-tabbed somewhere). Do
        // this by setting focus directly while the popover is still in
        // the tree — the existing focus-order contains "other".
        let other = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "other")
            .cloned();
        core.ui_state.set_focus(other);

        let mut closed_again = build(false);
        run_frame(&mut core, &mut closed_again);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("other"),
            "focus moved before close should not be overridden by restore",
        );
        assert!(core.ui_state.popover_focus.focus_stack.is_empty());
    }

    #[test]
    fn nested_popovers_stack_and_unwind_focus_correctly() {
        let mut core = RunnerCore::new();
        // Two siblings layered at El root: an outer popover anchored to
        // the trigger, and an inner popover anchored to a button inside
        // the outer panel. Both are real popovers — separate
        // popover_layer ids — so the runtime sees them stack.
        let build = |outer: bool, inner: bool| -> El {
            use crate::widgets::button::button;
            use crate::widgets::overlay::overlay;
            use crate::widgets::popover::{Anchor, popover, popover_panel};
            let main = button("Trigger").key("trigger");
            let mut layers: Vec<El> = vec![main];
            if outer {
                layers.push(popover(
                    "outer",
                    Anchor::below_key("trigger"),
                    popover_panel([button("Open inner").key("inner-trigger")]),
                ));
            }
            if inner {
                layers.push(popover(
                    "inner",
                    Anchor::below_key("inner-trigger"),
                    popover_panel([button("X").key("inner-a"), button("Y").key("inner-b")]),
                ));
            }
            overlay(layers).padding(20.0)
        };

        // Frame 1: nothing open, focus on the trigger.
        let mut closed = build(false, false);
        run_frame(&mut core, &mut closed);
        let trigger = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "trigger")
            .cloned();
        core.ui_state.set_focus(trigger);

        // Frame 2: outer opens. Save trigger, focus inner-trigger.
        let mut outer = build(true, false);
        run_frame(&mut core, &mut outer);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("inner-trigger"),
        );
        assert_eq!(core.ui_state.popover_focus.focus_stack.len(), 1);

        // Frame 3: inner also opens. Save inner-trigger, focus inner-a.
        let mut both = build(true, true);
        run_frame(&mut core, &mut both);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("inner-a"),
        );
        assert_eq!(core.ui_state.popover_focus.focus_stack.len(), 2);

        // Frame 4: inner closes. Pop → restore inner-trigger.
        let mut outer_only = build(true, false);
        run_frame(&mut core, &mut outer_only);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("inner-trigger"),
        );
        assert_eq!(core.ui_state.popover_focus.focus_stack.len(), 1);

        // Frame 5: outer closes. Pop → restore trigger.
        let mut none = build(false, false);
        run_frame(&mut core, &mut none);
        assert_eq!(
            core.ui_state.focused.as_ref().map(|t| t.key.as_str()),
            Some("trigger"),
        );
        assert!(core.ui_state.popover_focus.focus_stack.is_empty());
    }

    #[test]
    fn arrow_nav_does_not_intercept_outside_navigable_groups() {
        // Reuse the input tree (no arrow_nav_siblings parent). Arrow
        // keys must produce a regular `KeyDown` event so a
        // capture_keys widget can interpret them as caret motion.
        let mut core = lay_out_input_tree(false);
        let target = core
            .ui_state
            .focus
            .order
            .iter()
            .find(|t| t.key == "btn")
            .cloned();
        core.ui_state.set_focus(target);
        let events = core.key_down(UiKey::ArrowDown, KeyModifiers::default(), false);
        assert_eq!(
            events.len(),
            1,
            "ArrowDown without navigable parent → event"
        );
        assert_eq!(events[0].kind, UiEventKind::KeyDown);
    }

    fn quad(shader: ShaderHandle) -> DrawOp {
        DrawOp::Quad {
            id: "q".into(),
            rect: Rect::new(0.0, 0.0, 10.0, 10.0),
            scissor: None,
            shader,
            uniforms: UniformBlock::new(),
        }
    }

    #[test]
    fn prepare_paint_skips_ops_outside_viewport() {
        let mut core = RunnerCore::new();
        core.set_surface_size(100, 100);
        core.viewport_px = (100, 100);
        let ops = vec![
            DrawOp::Quad {
                id: "offscreen".into(),
                rect: Rect::new(0.0, 150.0, 10.0, 10.0),
                scissor: None,
                shader: ShaderHandle::Stock(StockShader::RoundedRect),
                uniforms: UniformBlock::new(),
            },
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
        ];
        let mut timings = PrepareTimings::default();
        core.prepare_paint(&ops, |_| true, |_| false, &mut NoText, 1.0, &mut timings);

        assert_eq!(timings.paint_culled_ops, 1);
        assert_eq!(
            core.runs.len(),
            1,
            "only the visible quad should become a paint run"
        );
    }

    #[test]
    fn prepare_paint_does_not_shape_text_outside_clip() {
        let mut core = RunnerCore::new();
        core.set_surface_size(100, 100);
        core.viewport_px = (100, 100);
        let ops = vec![
            DrawOp::GlyphRun {
                id: "offscreen-text".into(),
                rect: Rect::new(0.0, 150.0, 80.0, 20.0),
                scissor: Some(Rect::new(0.0, 0.0, 100.0, 100.0)),
                shader: ShaderHandle::Stock(StockShader::Text),
                color: Color::rgba(255, 255, 255, 255),
                text: "offscreen".into(),
                size: 14.0,
                line_height: 20.0,
                family: Default::default(),
                mono_family: Default::default(),
                weight: FontWeight::Regular,
                mono: false,
                wrap: TextWrap::NoWrap,
                anchor: TextAnchor::Start,
                layout: empty_text_layout(20.0),
                underline: false,
                strikethrough: false,
                link: None,
            },
            DrawOp::GlyphRun {
                id: "visible-text".into(),
                rect: Rect::new(0.0, 10.0, 80.0, 20.0),
                scissor: Some(Rect::new(0.0, 0.0, 100.0, 100.0)),
                shader: ShaderHandle::Stock(StockShader::Text),
                color: Color::rgba(255, 255, 255, 255),
                text: "visible".into(),
                size: 14.0,
                line_height: 20.0,
                family: Default::default(),
                mono_family: Default::default(),
                weight: FontWeight::Regular,
                mono: false,
                wrap: TextWrap::NoWrap,
                anchor: TextAnchor::Start,
                layout: empty_text_layout(20.0),
                underline: false,
                strikethrough: false,
                link: None,
            },
        ];
        let mut text = CountingText::default();
        let mut timings = PrepareTimings::default();
        core.prepare_paint(&ops, |_| true, |_| false, &mut text, 1.0, &mut timings);

        assert_eq!(timings.paint_culled_ops, 1);
        assert_eq!(text.records, 1, "offscreen text must not be shaped");
    }

    #[test]
    fn samples_backdrop_inserts_snapshot_before_first_glass_quad() {
        let mut core = RunnerCore::new();
        core.set_surface_size(100, 100);
        let ops = vec![
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
            quad(ShaderHandle::Custom("liquid_glass")),
            quad(ShaderHandle::Custom("liquid_glass")),
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
        ];
        let mut timings = PrepareTimings::default();
        core.prepare_paint(
            &ops,
            |_| true,
            |s| matches!(s, ShaderHandle::Custom(name) if *name == "liquid_glass"),
            &mut NoText,
            1.0,
            &mut timings,
        );

        let kinds: Vec<&'static str> = core
            .paint_items
            .iter()
            .map(|p| match p {
                PaintItem::QuadRun(_) => "Q",
                PaintItem::IconRun(_) => "I",
                PaintItem::Text(_) => "T",
                PaintItem::Image(_) => "M",
                PaintItem::AppTexture(_) => "A",
                PaintItem::Vector(_) => "V",
                PaintItem::BackdropSnapshot => "S",
            })
            .collect();
        assert_eq!(
            kinds,
            vec!["Q", "S", "Q", "Q"],
            "expected one stock run, snapshot, then a glass run, then a foreground stock run"
        );
    }

    #[test]
    fn no_snapshot_when_no_glass_drawn() {
        let mut core = RunnerCore::new();
        core.set_surface_size(100, 100);
        let ops = vec![
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
        ];
        let mut timings = PrepareTimings::default();
        core.prepare_paint(&ops, |_| true, |_| false, &mut NoText, 1.0, &mut timings);
        assert!(
            !core
                .paint_items
                .iter()
                .any(|p| matches!(p, PaintItem::BackdropSnapshot)),
            "no glass shader registered → no snapshot"
        );
    }

    #[test]
    fn at_most_one_snapshot_per_frame() {
        let mut core = RunnerCore::new();
        core.set_surface_size(100, 100);
        let ops = vec![
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
            quad(ShaderHandle::Custom("g")),
            quad(ShaderHandle::Stock(StockShader::RoundedRect)),
            quad(ShaderHandle::Custom("g")),
        ];
        let mut timings = PrepareTimings::default();
        core.prepare_paint(
            &ops,
            |_| true,
            |s| matches!(s, ShaderHandle::Custom("g")),
            &mut NoText,
            1.0,
            &mut timings,
        );
        let snapshots = core
            .paint_items
            .iter()
            .filter(|p| matches!(p, PaintItem::BackdropSnapshot))
            .count();
        assert_eq!(snapshots, 1, "backdrop depth is capped at 1");
    }
}