teksilo_core/

overlay.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! Overlay system for tooltips, dropdown menus, context menus, and popovers.
//!
//! Overlays render outside the normal layout hierarchy. They float above the
//! main content, positioned relative to an anchor widget or the pointer.
//! The `OverlayManager` coordinates creation, positioning, stacking, dismissal,
//! event routing, and accessibility.

use std::rc::Rc;
use std::time::{Duration, Instant};

use teksilo_canvas::{Point, Rect, Size, Vec2};
use teksilo_tokens::Corner;

use crate::environment::LayoutDirection;
use crate::pointer::PointerId;
use crate::signal::Signal;
use crate::widget_id::WidgetId;

pub mod direction;
mod placement_impl;
mod safe_triangle;
pub mod text_affordance;
mod viewport;

pub use direction::{HorizontalSide, InlineDirection, inline_band_at, inline_edge_band};
pub use text_affordance::{OverlayBand, SelectionHandleKind};
pub use viewport::OverlayViewport;

pub(crate) use safe_triangle::point_in_safe_triangle;

/// How long a submenu's safe region stays armed after the pointer
/// leaves the trigger row.
///
/// The region suppresses both dismissal paths (the sibling
/// hover-switch and the overlay's own pointer-leave grace), so it
/// needs a ceiling: a pointer that stops inside the cone is no longer
/// travelling, and the menu must go back to behaving normally. 600 ms
/// is long enough for a deliberate, slow diagonal across a tall
/// submenu and short enough that a parked pointer resolves before the
/// user notices anything is stuck.
pub(crate) const SAFE_REGION_BUDGET: Duration = Duration::from_millis(600);

/// Why an overlay went away.
///
/// The dismissal routes were previously indistinguishable at the callback,
/// which is what made a dismissed `MessageBox` unable to say whether the user
/// had pressed Escape, clicked outside, or been closed out from under by an
/// ancestor — three answers an application owes its caller and could not tell
/// apart. Five of the manager's dismissal entry points already encode the
/// reason in their own identity; this carries it the rest of the way.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum DismissReason {
    /// The user pressed Escape.
    Escape,
    /// The user pressed outside the overlay's bounds — the scrim, or simply
    /// the rest of the window.
    OutsidePress,
    /// The pointer left the overlay and its anchor, under
    /// [`DismissBehavior::PointerLeave`].
    PointerLeave,
    /// An ancestor overlay was dismissed and took this one with it. The
    /// ancestor's own callback receives the reason that actually happened;
    /// only the descendants it drags along see this.
    Cascade,
    /// The application asked: an explicit `dismiss`, `ctx.dismiss_modal()`, a
    /// widget closing its own overlay, or a sibling replacing it.
    Programmatic,
}

/// Callback invoked by the framework when an overlay is dismissed —
/// regardless of the dismiss path (Escape, click outside, pointer
/// leave, explicit API call, cascade). The anchor widget uses this
/// hook to reset its own interaction state so that SR-facing
/// properties like `set_expanded` on a `ComboBox` or a submenu
/// trigger stay consistent with the actual overlay-visible state.
///
/// Fired exactly once per overlay lifetime, at the point the
/// overlay is removed from the stack. `Fn` rather than `FnOnce`
/// simply because it's easier to pass around by `Rc`; the
/// framework only invokes it once.
///
/// # Why it takes an `EventContext`
///
/// It did not, and that cost a dismissed modal its result: `MessageBox` and
/// `InputDialog` both report through a `Fn(.., &mut EventContext)`, so a
/// callback with no context could not deliver one and the user's answer was
/// dropped on every route except a button press. The manager cannot mint a
/// context — it has no tree — so it no longer invokes these itself: it parks
/// them (`OverlayManager::take_pending_dismiss`, crate-private) and the tree
/// runs them at the point it already holds a `WindowOps`, still before focus
/// is restored to the trigger.
pub type OverlayDismissCallback = Rc<dyn Fn(DismissReason, &mut crate::widget::EventContext)>;

/// Where an overlay goes, as a function of its anchor's bounds (in window
/// coordinates, as the layout pass that is placing the overlay left them) and
/// the layout direction.
///
/// Installed with
/// [`EventContext::track_overlay_placement_by_content`](crate::widget::EventContext::track_overlay_placement_by_content),
/// for an overlay that hangs off a part of its anchor no placement names.
pub type OverlayPlacementSource = Rc<dyn Fn(Rect, LayoutDirection) -> OverlayPlacement>;

impl OverlayPlacement {
    /// Whether this is a modal's placement: [`Centered`](Self::Centered), the
    /// dialog's, or [`TopCenter`](Self::TopCenter), a command palette's. The
    /// tree reads modality off the placement, so these are the overlays it
    /// treats as modal: focus stays inside them, the page behind them refuses
    /// assistive-technology requests, and an overlay opened inside one never
    /// dismisses it.
    pub fn is_modal(&self) -> bool {
        matches!(self, Self::Centered | Self::TopCenter { .. })
    }
}

/// Unique identifier for an active overlay.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct OverlayId(u64);

impl OverlayId {
    pub(crate) fn new(id: u64) -> Self {
        Self(id)
    }
}

/// How an overlay is positioned relative to its anchor.
#[derive(Debug, Clone)]
pub enum OverlayPlacement {
    /// Below the anchor, leading-edge aligned (dropdown).
    ///
    /// The panel is made **at least as wide as the anchor** (the drop-down
    /// convention: a list hanging off a field spans the field) and may be
    /// wider when its content asks for more. Content that must keep its own
    /// width, such as a small popover off a wide trigger, wants
    /// [`NearAnchor`](Self::NearAnchor) or [`TrailingEdge`](Self::TrailingEdge).
    Below,
    /// Above the anchor (fallback when no space below).
    ///
    /// A panel taller than the room above its anchor is pinned to the top of
    /// the usable area and **shrunk to that room**, not slid down onto the
    /// anchor: the control that opened a panel has to stay visible, or the
    /// user is choosing blind. Where there is no room at all to shrink into,
    /// the ideal position is kept — an empty panel is not an improvement on a
    /// badly placed one.
    ///
    /// The panel is made **at least as wide as the anchor** (the drop-down
    /// convention: a list hanging off a field spans the field) and may be
    /// wider when its content asks for more. Content that must keep its own
    /// width, such as a small popover off a wide trigger, wants
    /// [`NearAnchor`](Self::NearAnchor) or [`TrailingEdge`](Self::TrailingEdge).
    Above,
    /// To the trailing side of the anchor (submenu).
    TrailingEdge,
    /// At the pointer position (context menu).
    AtPointer(Point),
    /// At the pointer, but never *under* it: the panel is placed in a quadrant
    /// that clears `avoid` entirely.
    ///
    /// The touch form of [`AtPointer`](Self::AtPointer). A mouse cursor is an
    /// arrow drawn *beside* the pixel it names, so a menu whose corner lands on
    /// that pixel is fully visible; a finger is an opaque disc centred on it,
    /// so the same menu opens with its first two rows underneath the hand. The
    /// fix is not an offset — an offset large enough for a thumb is absurd for
    /// a stylus — but a rectangle to keep clear, which the caller sizes from
    /// the contact patch the digitiser reported.
    ///
    /// Quadrant preference is **inline-start first** (left of the contact under
    /// LTR, right of it under RTL), then above-versus-below, then the mirrored
    /// side: a hand approaches from the reader's own side, so the far side is
    /// the one that stays visible. Every candidate clears `avoid` outright; the
    /// viewport clamp is applied on the axis that is already clear, so clamping
    /// can never push the panel back under the contact.
    AtPointerAvoiding {
        /// Where the contact was reported.
        point: Point,
        /// The rectangle the panel must not overlap — the contact patch,
        /// centred on `point`.
        avoid: Rect,
    },
    /// Above a text selection, centred on it, flipping below when the selection
    /// is against the top of the usable area.
    ///
    /// The selection toolbar's placement. Anchor bounds are ignored: the thing
    /// it hangs off is a range of text, whose rectangle the editor supplies and
    /// updates as the selection changes, not a widget.
    AboveSelection {
        /// The selection's bounding rectangle, in window coordinates.
        selection: Rect,
    },
    /// Below a rectangle, centred on it, flipping above when the rectangle is
    /// against the bottom of the usable area.
    ///
    /// The mirror of [`AboveSelection`](Self::AboveSelection), and like it
    /// anchor-independent: the caller supplies the rectangle in window
    /// coordinates and keeps it current, as a slider's value readout does
    /// with the strip its thumb occupies.
    BelowSelection {
        /// The rectangle to hang below, in window coordinates.
        selection: Rect,
    },
    /// Near the anchor with a preferred alignment and offset (tooltip).
    NearAnchor { offset: Vec2 },
    /// Centered within the viewport (dialog).
    Centered,
    /// Bottom-centered within the viewport (snackbar/toast).
    BottomCenter,
    /// Horizontally centred, with the top edge `offset` below the top of the
    /// usable area (a command palette). Anchor bounds are ignored. The top
    /// edge stays put while the content's height changes, which is the point:
    /// a centred surface that shrinks as its list narrows moves everything
    /// above the list with it. When the content would run past the bottom,
    /// it is raised, and then shrunk, to fit.
    TopCenter { offset: f32 },
    /// Below the anchor if space allows, otherwise above (combo box dropdown).
    /// The viewport height is supplied by `position_overlays()` at layout time.
    ///
    /// When the panel fits on neither side it takes whichever side has more
    /// room and is shrunk to it — a tie keeps the flip upward. It is never slid
    /// over the anchor; see [`Above`](Self::Above).
    ///
    /// The panel is made **at least as wide as the anchor** (the drop-down
    /// convention: a list hanging off a field spans the field) and may be
    /// wider when its content asks for more. Content that must keep its own
    /// width, such as a small popover off a wide trigger, wants
    /// [`NearAnchor`](Self::NearAnchor) or [`TrailingEdge`](Self::TrailingEdge).
    BelowPreferred,
    /// Snaps content to a viewport corner with a per-axis margin
    /// (used by `ToastHost` for stacked toast notifications, also
    /// suitable for picture-in-picture, floating action overlays).
    /// Anchor bounds are ignored. The leading/trailing axis honours
    /// `LayoutDirection`: `TopTrailing` is top-right under LTR and
    /// top-left under RTL.
    ViewportCorner { corner: Corner, margin: Vec2 },
    /// Fills the entire viewport, anchor-independent. Used by the
    /// modal-presentation pipeline to mount a dialog scrim behind a
    /// centered modal panel — the scrim covers the full window so the
    /// content behind dims uniformly. Anchor bounds are ignored.
    FullViewport,
}

/// The contact patch assumed for a coarse pointer whose backend reports none.
///
/// 24 dp is the size of the smallest thing a finger is ever asked to hit, so it
/// is the smallest rectangle a finger can be assumed to cover. Backends that do
/// report a patch (Windows `WM_POINTER`, Wayland `wp_touch` with the shape
/// extension) usually report a larger one, and that number is preferred — this
/// is the floor, not the answer.
pub const ASSUMED_CONTACT_PATCH: Size = Size {
    width: 24.0,
    height: 24.0,
};

impl OverlayPlacement {
    /// The placement a point-anchored panel — a context menu, a drop-down
    /// raised from a long press — should use for the pointer that opened it.
    ///
    /// **One branch, every menu.** A coarse pointer gets
    /// [`AtPointerAvoiding`](Self::AtPointerAvoiding) with the contact patch as
    /// the rectangle to clear; everything else gets the
    /// [`AtPointer`](Self::AtPointer) it has always had, byte for byte. Putting
    /// the decision here rather than at each call site is the point: a menu
    /// that forgot to ask opens under the finger, and there is no way to notice
    /// that from a mouse.
    pub fn at_pointer_for(point: Point, pointer: &crate::pointer::PointerInfo) -> Self {
        if !pointer.kind.is_coarse() {
            return OverlayPlacement::AtPointer(point);
        }
        let contact = pointer.axes.contact.unwrap_or(ASSUMED_CONTACT_PATCH);
        let patch = Size::new(
            contact.width.max(ASSUMED_CONTACT_PATCH.width),
            contact.height.max(ASSUMED_CONTACT_PATCH.height),
        );
        OverlayPlacement::AtPointerAvoiding {
            point,
            avoid: rect_centred_on(point, patch),
        }
    }
}

/// `size`, centred on `point`. `Rect` has no such constructor and the two
/// places that need one must agree exactly, since one computes the rectangle a
/// menu must clear and the other asserts that it did.
pub(crate) fn rect_centred_on(point: Point, size: Size) -> Rect {
    Rect::new(
        point.x - size.width / 2.0,
        point.y - size.height / 2.0,
        size.width,
        size.height,
    )
}

/// Placement preference for a tooltip relative to its anchor. Resolved to
/// a concrete [`OverlayPlacement`] at show time (see
/// `WidgetTree::tooltip_overlay_placement`).
///
/// `Below` is the default (drop below the anchor, flip above near the
/// viewport edge). `Side` opens to the anchor's trailing side (RTL-aware,
/// with a leading fallback) — for anchors stacked **vertically** (menu
/// items, a vertical tab strip, list/tree rows, a docking activity rail,
/// a vertical `RadioTileGroup`) where a `Below` tooltip would cover the
/// next sibling.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TooltipPlacement {
    /// Below the anchor (flips above near the viewport edge). The default.
    #[default]
    Below,
    /// To the anchor's trailing side (RTL-aware, leading fallback).
    Side,
}

/// When an overlay is dismissed.
#[derive(Debug, Clone)]
pub enum DismissBehavior {
    /// Dismiss when the user clicks outside the overlay.
    ClickOutside,
    /// Dismiss when the user presses Escape.
    EscapeKey,
    /// Dismiss on either Escape or an outside click.
    EscapeOrClickOutside,
    /// Dismiss when the pointer leaves both anchor and overlay.
    PointerLeave { delay: Duration },
    /// Dismiss only via explicit API call.
    Manual,
}

/// Where the overlay renders.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OverlayLayer {
    /// Rendered within the application window's wgpu surface.
    InTree,
    /// Rendered in a separate native OS window.
    NativePopup,
    /// Framework decides based on content size.
    Auto,
}

/// A request to show an overlay.
///
/// Built with [`new`](Self::new), which takes what every overlay has to
/// decide, and the builder methods for the rest. The fields stay public, so a
/// request can still be adjusted after it is built: that is how a value that
/// is already an `Option` is set, since the builders take the bare value.
///
/// Non-exhaustive, so that a field added later reaches every caller as its
/// default instead of breaking each struct literal.
#[non_exhaustive]
pub struct OverlayRequest {
    /// The root widget of the overlay content.
    pub content_id: WidgetId,
    /// The widget this overlay is anchored to.
    pub anchor: WidgetId,
    /// Positioning relative to the anchor.
    pub placement: OverlayPlacement,
    /// How the overlay is dismissed.
    pub dismiss: DismissBehavior,
    /// Rendering layer.
    pub layer: OverlayLayer,
    /// Parent overlay (for submenu cascading).
    pub parent_overlay: Option<OverlayId>,
    /// Invoked when the overlay is dismissed by any path. Use this
    /// to reset anchor-side state (e.g. `ComboBox.interaction`)
    /// when the framework tears down the overlay without going
    /// through the anchor's own key/tap handlers.
    pub on_dismiss: Option<OverlayDismissCallback>,
    /// Optional fade-in / fade-out duration. When `Some`, the
    /// framework attaches an animated opacity scope to `content_id`
    /// at show time (using the existing `set_opacity` rendering
    /// pipeline — no `Fade` widget required from the caller), tweens
    /// the opacity from 0 → 1 over `duration`, and on dismiss
    /// reverses the tween and defers the actual stack removal by
    /// `duration`. Set with [`OverlayRequest::with_fade`].
    pub fade_duration: Option<Duration>,
    /// The overlay takes no input. Set with [`OverlayRequest::inert`], which
    /// says what that means.
    pub inert: bool,
    /// Where a command chosen in this overlay is sent from, when that is not
    /// where the overlay gives focus back. Set with
    /// [`OverlayRequest::command_source`].
    #[doc(hidden)]
    pub command_source: Option<WidgetId>,
}

impl OverlayRequest {
    /// A request to show `content_id` at `placement` relative to `anchor`,
    /// taken down the way `dismiss` says.
    ///
    /// `dismiss` is an argument rather than a default because no one value
    /// suits most overlays, and the likeliest default is the worst one to
    /// inherit unawares: a [`Manual`](DismissBehavior::Manual) overlay that
    /// takes input is opaque to Escape, for itself and for every overlay
    /// beneath it (see [`OverlayManager::try_dismiss_top_on_escape`]).
    ///
    /// Everything else starts at the value nearly every overlay uses:
    ///
    /// - [`layer`](Self::layer()): [`OverlayLayer::InTree`].
    /// - [`parent_overlay`](Self::parent_overlay()): `None`, a top-level
    ///   overlay.
    /// - [`on_dismiss`](Self::on_dismiss()): `None`.
    /// - [`with_fade`](Self::with_fade): `None`, so the overlay appears and
    ///   goes without a fade.
    /// - [`inert`](Self::inert()): `false`, an overlay that takes input.
    ///
    /// ```
    /// use std::time::Duration;
    /// use teksilo_core::WidgetId;
    /// use teksilo_core::overlay::{DismissBehavior, OverlayPlacement, OverlayRequest};
    /// # let (popup, trigger) = (WidgetId::default(), WidgetId::default());
    ///
    /// let request = OverlayRequest::new(
    ///     popup,
    ///     trigger,
    ///     OverlayPlacement::BelowPreferred,
    ///     DismissBehavior::EscapeOrClickOutside,
    /// )
    /// .with_fade(Duration::from_millis(150));
    /// assert_eq!(request.fade_duration, Some(Duration::from_millis(150)));
    /// ```
    pub fn new(
        content_id: WidgetId,
        anchor: WidgetId,
        placement: OverlayPlacement,
        dismiss: DismissBehavior,
    ) -> Self {
        Self {
            content_id,
            anchor,
            placement,
            dismiss,
            layer: OverlayLayer::InTree,
            parent_overlay: None,
            on_dismiss: None,
            fade_duration: None,
            inert: false,
            command_source: None,
        }
    }

    /// Where a command chosen in this overlay is sent from, and so what
    /// `WidgetTree::can_handle` answers for while it is open, when that is
    /// not the widget the overlay gives focus back to. A menu bar's menu
    /// opened from the keyboard gives focus back to its title, and its
    /// command goes to the widget focused before the bar took focus, which
    /// the bar names here. Default: `None`, where focus goes back.
    #[doc(hidden)]
    pub fn command_source(mut self, id: WidgetId) -> Self {
        self.command_source = Some(id);
        self
    }

    /// Render the overlay on `layer`. Default: [`OverlayLayer::InTree`].
    pub fn layer(mut self, layer: OverlayLayer) -> Self {
        self.layer = layer;
        self
    }

    /// Nest the overlay under `parent`, so that dismissing `parent` takes this
    /// one down with it, the way a menu takes its submenu. Default: `None`, a
    /// top-level overlay.
    ///
    /// A parent that is already an `Option` is assigned to the
    /// [`parent_overlay`](field@Self::parent_overlay) field instead.
    pub fn parent_overlay(mut self, parent: OverlayId) -> Self {
        self.parent_overlay = Some(parent);
        self
    }

    /// Run `callback` when the overlay is dismissed, whatever the path.
    /// Default: `None`.
    ///
    /// It takes the shared [`OverlayDismissCallback`] rather than a closure
    /// because an anchor usually installs one callback on every route that
    /// opens its overlay; a one-off closure is wrapped in `Rc::new`.
    pub fn on_dismiss(mut self, callback: OverlayDismissCallback) -> Self {
        self.on_dismiss = Some(callback);
        self
    }

    /// Attach a fade-in / fade-out animation to this request.
    /// `duration` controls both directions. The framework wires
    /// everything internally — caller does not create a `Fade`
    /// widget or manage a signal. Default: no fade.
    ///
    /// A duration that is already an `Option` (no fade under reduced motion,
    /// say) is assigned to the [`fade_duration`](Self::fade_duration) field
    /// instead.
    pub fn with_fade(mut self, duration: Duration) -> Self {
        self.fade_duration = Some(duration);
        self
    }

    /// Make the overlay inert: something to look at, never to work. Default:
    /// not inert.
    ///
    /// An inert overlay:
    ///
    /// - lets **pointer input** through to what is under it, whether that is
    ///   another overlay or the window: a press or a hover over it is the
    ///   press or the hover of the widget beneath, and a press there is
    ///   outside every overlay it is outside of, so it still closes a
    ///   click-outside popover;
    /// - is **closed by Escape without consuming the key**, if its
    ///   [`dismiss`](field@Self::dismiss) is one Escape closes
    ///   ([`EscapeKey`](DismissBehavior::EscapeKey),
    ///   [`EscapeOrClickOutside`](DismissBehavior::EscapeOrClickOutside),
    ///   [`PointerLeave`](DismissBehavior::PointerLeave)); whatever its
    ///   `dismiss`, [`Manual`](DismissBehavior::Manual) included, the key goes
    ///   on to what it would have reached with the overlay gone;
    /// - **never records or restores focus**: focus stays where it is when
    ///   the overlay appears and when it goes;
    /// - **does not close when focus leaves its anchor**: the code that raised
    ///   it decides when it goes.
    ///
    /// For an overlay that only reports, such as a slider's value readout. It
    /// is a property of the request, read once when the overlay is shown. The
    /// content root's [`hit_transparent`](crate::widget_builder::WidgetBuilder::hit_transparent)
    /// and [`event_pass_through`](crate::widget_builder::WidgetBuilder::event_pass_through)
    /// keep their own meanings and play no part in it: an inert overlay needs
    /// neither, and setting both does not make an overlay inert.
    pub fn inert(mut self) -> Self {
        self.inert = true;
        self
    }
}

/// Fade-on-show / fade-on-dismiss state for an overlay. Populated by
/// the framework when an [`OverlayRequest`] carries `fade_duration`.
/// The framework owns the `Signal<f32>` (an animated 0..1 opacity)
/// and applies it to the overlay's content via `set_opacity`, so the
/// caller doesn't need to wrap the content in a `Fade` widget — the
/// rendering walker's opacity scope (Item 1) does the work.
///
/// Mirrors the `pointer_leave_started_real/_sim` and
/// `shown_at_real/_sim` dual-clock pattern used elsewhere in
/// `ActiveOverlay`: the real-clock field drives the live event loop;
/// the sim-clock field drives the headless `tick_animations` /
/// `advance_time` test path so deterministic tests can advance the
/// fade-out window without `std::thread::sleep`.
#[derive(Clone)]
pub(crate) struct OverlayFadeState {
    /// Animated opacity (0..1) bound to the overlay's content via
    /// `WidgetTree::set_opacity`. The framework starts the tween at
    /// 0 and animates to 1 on show, then animates back to 0 on
    /// dismiss before the deferred removal fires.
    pub opacity: Signal<f32>,
    /// Tween duration on both directions. Picked from
    /// `theme.motion.duration_fast` for tooltip / popover and
    /// `duration_normal` for snackbar / dialog.
    pub duration: Duration,
    /// `Some(start_real)` when a dismiss has been requested and the
    /// fade-out tween has started. The real-clock processor
    /// considers the overlay ready for removal once
    /// `Instant::now() - start_real >= duration`.
    pub dismissing_started_real: Option<Instant>,
    /// Why the dismissal that started this fade-out happened. Read when the
    /// tween completes, so a faded overlay reports the reason the user
    /// produced rather than the bookkeeping that removed it a frame later.
    pub dismiss_reason: Option<DismissReason>,
    /// `Some(start_sim)` set in lockstep with `dismissing_started_real`
    /// using the tree's `sim_clock`. The sim-clock processor uses
    /// it for deterministic headless tests.
    pub dismissing_started_sim: Option<Instant>,
}

/// An active overlay in the stack.
pub(crate) struct ActiveOverlay {
    pub id: OverlayId,
    pub content_id: WidgetId,
    pub anchor: WidgetId,
    pub placement: OverlayPlacement,
    pub dismiss: DismissBehavior,
    pub layer: OverlayLayer,
    /// Which z-band this overlay sits in. See [`OverlayBand`]; the stack is
    /// kept sorted by it, so this is also the overlay's position class within
    /// `stack`.
    pub band: OverlayBand,
    pub parent_overlay: Option<OverlayId>,
    /// Computed bounds after positioning.
    pub bounds: Rect,
    /// Widget that had focus before this overlay was shown.
    /// Used to restore focus when the overlay is dismissed.
    pub focus_restore: Option<WidgetId>,
    /// [`OverlayRequest::command_source`].
    pub command_source: Option<WidgetId>,
    /// When pointer-leave dismissal started (real time).
    pub pointer_leave_started_real: Option<std::time::Instant>,
    /// When pointer-leave dismissal started (simulated time).
    pub pointer_leave_started_sim: Option<std::time::Instant>,
    /// Apex of the "safe triangle" — the point at which the pointer
    /// left the anchor, armed by [`OverlayManager::arm_safe_region`].
    /// While it is set and unexpired, a pointer inside the triangle
    /// spanned by it and this overlay's near edge counts as still
    /// inside the overlay's region, so the pointer-leave grace does
    /// not run — and a pointer that strays back out only starts that
    /// grace, keeping the apex so a course correction can stop it
    /// again. See [`safe_triangle`].
    pub safe_apex: Option<Point>,
    /// When the safe region was armed (real time). Bounds it by
    /// [`SAFE_REGION_BUDGET`].
    pub safe_apex_started_real: Option<std::time::Instant>,
    /// When the safe region was armed (simulated time).
    pub safe_apex_started_sim: Option<std::time::Instant>,
    /// Dismiss automatically after this duration, if set.
    pub auto_dismiss_after: Option<Duration>,
    /// While the auto-dismiss timer is paused (via
    /// [`OverlayManager::pause_auto_dismiss`]), `auto_dismiss_after`
    /// is cleared and the time that *would have remained* is stashed
    /// here. [`OverlayManager::resume_auto_dismiss`] restores
    /// `auto_dismiss_after = Some(this)` and stamps a fresh
    /// `shown_at_*`. `None` whenever the overlay is not paused.
    pub paused_remaining: Option<Duration>,
    /// When the overlay was shown (real time).
    pub shown_at_real: std::time::Instant,
    /// When the overlay was shown (simulated time).
    pub shown_at_sim: std::time::Instant,
    /// Dismiss callback supplied by the show request. Invoked
    /// exactly once when the overlay is removed from the stack,
    /// regardless of dismiss path.
    pub on_dismiss: Option<OverlayDismissCallback>,
    /// Optional fade-in / fade-out state. Installed post-show by the
    /// crate-internal `OverlayManager::attach_fade`, which
    /// `WidgetTree::attach_overlay_fade` calls whenever the show
    /// request carried a `fade_duration`; read back from outside
    /// through [`OverlayManager::fade_duration`]. When `Some`, all
    /// dismiss paths (auto, escape, click-outside, pointer-leave,
    /// manual) defer the actual removal until the fade-out tween
    /// completes.
    pub fade: Option<OverlayFadeState>,
    /// The request's [`inert`](OverlayRequest::inert) flag, copied when the
    /// overlay is shown and never changed after. Such an overlay is skipped by
    /// every question the manager answers about the pointer —
    /// [`hit_test`](OverlayManager::hit_test), outside-press dismissal,
    /// [`interactive_rects`](OverlayManager::interactive_rects) — so a press or
    /// a hover over it belongs to what is beneath it, an overlay included, and
    /// a press there is outside every overlay it is outside of. It is never
    /// the Escape walk's target and never records a focus to restore.
    pub inert: bool,
    /// Re-derives [`placement`](Self::placement) from the anchor's bounds on
    /// every [`position_overlays`](OverlayManager::position_overlays). See
    /// [`EventContext::track_overlay_placement_by_content`](crate::widget::EventContext::track_overlay_placement_by_content).
    pub placement_source: Option<OverlayPlacementSource>,
}

impl ActiveOverlay {
    /// Whether this overlay is already on its way out — dismissed, but still
    /// on the stack while its fade-out tween runs.
    ///
    /// Such an overlay still answers every stack query, so anything that
    /// *targets* an overlay has to step over it: dismissing it a second time
    /// collapses the tween it is in the middle of, and (for input) spends the
    /// keystroke on a corpse while leaving whatever sits underneath
    /// unreachable.
    pub(crate) fn is_dismissing(&self) -> bool {
        self.fade
            .as_ref()
            .is_some_and(|fade| fade.dismissing_started_real.is_some())
    }
}

// Manual Debug impl: `Rc<dyn Fn()>` doesn't derive Debug, but the
// surrounding systems (tests, logging) want ActiveOverlay to be
// printable. Skip the callback field and tag it with a placeholder.
impl std::fmt::Debug for ActiveOverlay {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ActiveOverlay")
            .field("id", &self.id)
            .field("content_id", &self.content_id)
            .field("anchor", &self.anchor)
            .field("placement", &self.placement)
            .field("dismiss", &self.dismiss)
            .field("layer", &self.layer)
            .field("band", &self.band)
            .field("parent_overlay", &self.parent_overlay)
            .field("bounds", &self.bounds)
            .field("focus_restore", &self.focus_restore)
            .field(
                "pointer_leave_started_real",
                &self.pointer_leave_started_real,
            )
            .field("pointer_leave_started_sim", &self.pointer_leave_started_sim)
            .field("safe_apex", &self.safe_apex)
            .field("auto_dismiss_after", &self.auto_dismiss_after)
            .field("shown_at_real", &self.shown_at_real)
            .field("shown_at_sim", &self.shown_at_sim)
            .field(
                "on_dismiss",
                &self.on_dismiss.as_ref().map(|_| "<callback>"),
            )
            .field("fading", &self.fade.is_some())
            .field("inert", &self.inert)
            .field("tracks_placement", &self.placement_source.is_some())
            .finish()
    }
}

/// Maximum overlay nesting depth. Bounds runaway cascades: a rich-tooltip
/// `[label](:key)` link loop (A→B→A) keeps minting fresh nested overlays
/// (and dormant widgets) on each hop with no natural ceiling. A real
/// menu-submenu or tooltip cascade never gets close to this — once a new
/// overlay would exceed it, `OverlayManager::show*` drops the request
/// instead of growing the stack without bound.
pub(crate) const MAX_OVERLAY_NESTING_DEPTH: usize = 12;

/// What an outside press owes the tree, decided on the arming
/// [`PointerDown`](crate::event::WidgetEvent::PointerDown) and answered again
/// on the release.
///
/// Two questions, asked on two different samples, which is why they are two
/// fields rather than one bool: the `Down` needs to know whether to withhold
/// itself from the widget beneath, and the `Up` needs to know whether anything
/// is still waiting to close.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct DismissArm {
    /// At least one overlay is armed to close when this press completes.
    pub will_dismiss: bool,
    /// The arming press must not be delivered to the widget under it.
    ///
    /// This is the whole point of arming. Today's press-time dismissal *falls
    /// through*, so one tap closes a menu **and** actuates whatever the menu was
    /// covering — a destructive button, a list row, a tab. With a mouse the user
    /// sees the menu vanish under a cursor they aimed deliberately; with a
    /// finger the menu is what they were looking at and the control beneath is
    /// one they never saw.
    pub suppress_beneath: bool,
}

/// An outside press that has not completed yet.
struct ArmedDismiss {
    pointer: PointerId,
    /// The overlays the arming press selected. Re-checked at commit time
    /// against the live stack, so an overlay that closed in the meantime is
    /// simply absent rather than an error.
    overlays: Vec<OverlayId>,
    /// The click-opened overlays' anchors, carried so the commit can report
    /// them exactly as the press-time path does.
    anchors: Vec<WidgetId>,
}

pub struct OverlayManager {
    pub(crate) stack: Vec<ActiveOverlay>,
    /// Outside presses awaiting their release, one per contact. Almost always
    /// empty, and never longer than the number of live contacts.
    arms: Vec<ArmedDismiss>,
    next_id: u64,
    /// Latest known sim-clock value, mirrored from
    /// `WidgetTree::sim_clock` via [`Self::set_sim_clock`]. Read by
    /// `dismiss` to stamp `dismissing_started_sim` in lockstep with
    /// `dismissing_started_real`. Defaults to `Instant::now()` so
    /// constructions outside a tree (tests of OverlayManager in
    /// isolation) still produce sensible values.
    sim_clock: Instant,
    /// Monotonic counter bumped on every stack mutation (show /
    /// dismiss). External observers — notably the inspector's Overlays
    /// tab — bind to this signal to know when the visible overlay set
    /// has changed without polling. Mirrors the
    /// `ShortcutRegistry::version` pattern.
    version: Signal<u64>,
    /// Callbacks whose overlays have already left the stack but which have
    /// not run yet, because they need an `EventContext` this type cannot
    /// build. Drained by `WidgetTree::run_pending_dismiss_callbacks`, which
    /// is called before the dismissed content is parked — so the ordering
    /// `on_dismiss` always had (fires during dismissal, before focus returns
    /// to the trigger) is unchanged.
    pending_dismiss: Vec<(OverlayDismissCallback, DismissReason)>,
}

impl OverlayManager {
    pub fn new() -> Self {
        Self {
            stack: Vec::new(),
            arms: Vec::new(),
            next_id: 1,
            sim_clock: Instant::now(),
            version: Signal::new(0),
            pending_dismiss: Vec::new(),
        }
    }

    /// Reactive handle bumped on every overlay mutation (show /
    /// dismiss / cascade). Cheap clone. Same shape as
    /// [`crate::shortcut::ShortcutRegistry::version`].
    pub fn version(&self) -> &Signal<u64> {
        &self.version
    }

    /// Bump the version signal. Called from every stack-mutating path.
    fn bump_version(&self) {
        self.version.set(self.version.get().wrapping_add(1));
    }

    /// Mirror the tree's sim_clock onto the manager so the fade
    /// dismiss path can stamp the sim-time start in lockstep with
    /// real time. Called by `WidgetTree` whenever `sim_clock` is
    /// advanced (e.g. from `tick_animations` and `advance_time`).
    pub(crate) fn set_sim_clock(&mut self, now_sim: Instant) {
        self.sim_clock = now_sim;
    }

    /// Show a new overlay. Returns the OverlayId.
    pub fn show(&mut self, request: OverlayRequest) -> OverlayId {
        self.show_with_auto_dismiss(request, None, OverlayBand::Standard)
    }

    /// Show a new overlay in an explicit z-band.
    ///
    /// [`show`](Self::show) is this with [`OverlayBand::Standard`]. The other
    /// band exists for the touch text affordances — see
    /// [`text_affordance`] — which must sit
    /// under every menu and survive the presses that drive them.
    ///
    /// A band below the top is inserted **mid-stack**, so
    /// [`set_top_focus_restore`](Self::set_top_focus_restore) — which addresses
    /// the top of the stack — does not describe it. That is correct rather than
    /// a limitation: an affordance in this band never takes focus from the
    /// editor it belongs to, so it has no focus to restore.
    pub fn show_in_band(&mut self, request: OverlayRequest, band: OverlayBand) -> OverlayId {
        self.show_with_auto_dismiss(request, None, band)
    }

    /// Show a new overlay that dismisses automatically after `duration`.
    pub fn show_for(&mut self, request: OverlayRequest, duration: Duration) -> OverlayId {
        self.show_with_auto_dismiss(request, Some(duration), OverlayBand::Standard)
    }

    fn show_with_auto_dismiss(
        &mut self,
        request: OverlayRequest,
        auto_dismiss_after: Option<Duration>,
        band: OverlayBand,
    ) -> OverlayId {
        let id = OverlayId::new(self.next_id);
        self.next_id += 1;

        // push, and return the (now unused) id so an id-keyed follow-up
        // (`set_shown_at_sim`, `attach_fade`) safely no-ops on the absent
        // overlay — `set_top_focus_restore` takes no id, so it still lands
        // on whatever is actually topmost. This is reachable by degenerate-but-real
        if self.ancestor_depth(request.parent_overlay) >= MAX_OVERLAY_NESTING_DEPTH {
            return id;
        }

        let now = std::time::Instant::now();

        let overlay = ActiveOverlay {
            id,
            content_id: request.content_id,
            anchor: request.anchor,
            placement: request.placement,
            dismiss: request.dismiss,
            layer: request.layer,
            band,
            parent_overlay: request.parent_overlay,
            bounds: Rect::ZERO,
            focus_restore: None,
            command_source: request.command_source,
            pointer_leave_started_real: None,
            pointer_leave_started_sim: None,
            safe_apex: None,
            safe_apex_started_real: None,
            safe_apex_started_sim: None,
            auto_dismiss_after,
            paused_remaining: None,
            shown_at_real: now,
            shown_at_sim: now,
            on_dismiss: request.on_dismiss,
            fade: None,
            inert: request.inert,
            placement_source: None,
        };
        // Sorted insert, not a push: an overlay goes above everything in a
        // lower band and below everything in a higher one, so a selection
        // handle raised while a menu is open still lands under the menu. Within
        // a band the historical push order stands — a `Standard` overlay in a
        // tree that raises no text affordance is appended, exactly as before.
        let at = self
            .stack
            .iter()
            .position(|existing| existing.band > band)
            .unwrap_or(self.stack.len());
        self.stack.insert(at, overlay);
        self.bump_version();
        id
    }

    /// Internal: install a framework-managed opacity signal as the
    /// overlay's fade state. Called by `WidgetTree::show_overlay`
    /// when [`OverlayRequest::fade_duration`] is `Some`. The
    /// framework also applies the same signal to `content_id` via
    /// `set_opacity` (so the rendering walker emits the per-frame
    /// opacity scope) and kicks off the 0→1 fade-in tween.
    pub(crate) fn attach_fade(&mut self, id: OverlayId, opacity: Signal<f32>, duration: Duration) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id) {
            overlay.fade = Some(OverlayFadeState {
                opacity,
                duration,
                dismissing_started_real: None,
                dismiss_reason: None,
                dismissing_started_sim: None,
            });
        }
    }

    /// Public read-only accessor for the fade state. Returns the
    /// duration if fade is configured, `None` otherwise. Used by
    /// `WidgetTree::dismiss_overlay` to know whether to leave the
    /// content active for the fade-out window.
    pub fn fade_duration(&self, id: OverlayId) -> Option<Duration> {
        self.stack
            .iter()
            .find(|o| o.id == id)
            .and_then(|o| o.fade.as_ref().map(|f| f.duration))
    }

    pub fn next_auto_dismiss_deadline(&self) -> Option<std::time::Instant> {
        self.stack
            .iter()
            .filter_map(|overlay| {
                overlay
                    .auto_dismiss_after
                    .map(|delay| overlay.shown_at_real + delay)
            })
            .min()
    }

    /// Earliest instant at which a [`DismissBehavior::PointerLeave`] overlay
    /// whose leave-grace is already running becomes due for dismissal.
    ///
    /// The counterpart of
    /// [`next_auto_dismiss_deadline`](Self::next_auto_dismiss_deadline) for the
    /// hover-opened overlays (tooltips, hover submenus). Without it the event
    /// loop has no reason to wake between the pointer's last motion event and
    /// the end of the grace window: `next_timer_deadline` would return `None`,
    /// winit would sit in `ControlFlow::Wait`, and the overlay would stay on
    /// screen until some unrelated input happened to redraw the window.
    pub fn next_pointer_leave_deadline(&self) -> Option<std::time::Instant> {
        self.stack
            .iter()
            .filter_map(|overlay| {
                let DismissBehavior::PointerLeave { delay } = overlay.dismiss else {
                    return None;
                };
                Some(overlay.pointer_leave_started_real? + delay)
            })
            .min()
    }

    /// Pause the auto-dismiss timer for an overlay shown with
    /// [`show_for`](Self::show_for). The remaining time
    /// (`auto_dismiss_after - elapsed`) is stashed; subsequent calls
    /// to [`next_auto_dismiss_deadline`](Self::next_auto_dismiss_deadline)
    /// ignore this overlay until [`resume_auto_dismiss`](Self::resume_auto_dismiss)
    /// is called. Idempotent — pausing an already-paused overlay is
    /// a no-op (the originally-stashed remaining time is preserved).
    ///
    /// Used by `ToastHost` to implement hover-pause: when the user
    /// is hovering over any live toast, all live toasts pause their
    /// timers so the user can read each one without losing the
    /// notification they're about to act on.
    ///
    /// No-op on overlays without `auto_dismiss_after` (persistent
    /// overlays don't have a timer to pause) and on unknown ids.
    pub fn pause_auto_dismiss(&mut self, id: OverlayId) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id)
            && overlay.paused_remaining.is_none()
            && let Some(delay) = overlay.auto_dismiss_after.take()
        {
            let elapsed = overlay.shown_at_real.elapsed();
            overlay.paused_remaining = Some(delay.saturating_sub(elapsed));
        }
    }

    /// Resume an auto-dismiss timer paused via
    /// [`pause_auto_dismiss`](Self::pause_auto_dismiss). The stashed
    /// remaining time becomes the new `auto_dismiss_after`, and
    /// `shown_at_real` / `shown_at_sim` are reset to now so the
    /// deadline computation works correctly. Idempotent — resuming
    /// an un-paused overlay is a no-op.
    pub fn resume_auto_dismiss(&mut self, id: OverlayId) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id)
            && let Some(remaining) = overlay.paused_remaining.take()
        {
            overlay.auto_dismiss_after = Some(remaining);
            let now = std::time::Instant::now();
            overlay.shown_at_real = now;
            overlay.shown_at_sim = self.sim_clock;
        }
    }

    /// Whether the auto-dismiss timer for an overlay is currently paused.
    /// `false` for overlays without `auto_dismiss_after`, unknown ids,
    /// and overlays whose timer is running.
    pub fn is_auto_dismiss_paused(&self, id: OverlayId) -> bool {
        self.stack
            .iter()
            .find(|o| o.id == id)
            .is_some_and(|o| o.paused_remaining.is_some())
    }

    pub(crate) fn set_shown_at_sim(&mut self, id: OverlayId, shown_at_sim: std::time::Instant) {
        if let Some(overlay) = self.stack.iter_mut().find(|overlay| overlay.id == id) {
            overlay.shown_at_sim = shown_at_sim;
        }
    }

    /// Count the ancestor chain length for an overlay whose parent is
    /// `parent` — i.e. the nesting depth the *new* overlay would have.
    /// A root (`parent == None`) is depth 0; a child of a root is depth
    /// 1; and so on. The walk is bounded by the stack length so a
    /// malformed parent cycle can't loop forever.
    fn ancestor_depth(&self, parent: Option<OverlayId>) -> usize {
        let mut depth = 0;
        let mut current = parent;
        while let Some(p) = current {
            depth += 1;
            if depth > self.stack.len() {
                // Defensive: malformed parent cycle. Report a depth that
                // trips the guard rather than spinning.
                break;
            }
            current = self
                .stack
                .iter()
                .find(|overlay| overlay.id == p)
                .and_then(|overlay| overlay.parent_overlay);
        }
        depth
    }

    pub(crate) fn is_descendant_of(&self, child: OverlayId, ancestor: OverlayId) -> bool {
        let mut current = self
            .stack
            .iter()
            .find(|overlay| overlay.id == child)
            .and_then(|overlay| overlay.parent_overlay);

        while let Some(parent) = current {
            if parent == ancestor {
                return true;
            }
            current = self
                .stack
                .iter()
                .find(|overlay| overlay.id == parent)
                .and_then(|overlay| overlay.parent_overlay);
        }

        false
    }

    pub(crate) fn overlay(&self, id: OverlayId) -> Option<&ActiveOverlay> {
        self.stack.iter().find(|overlay| overlay.id == id)
    }

    /// Public accessor for an overlay's currently-laid-out screen
    /// rect. Returns `None` for unknown ids and for overlays that
    /// have not yet been through a layout pass (`bounds == Rect::ZERO`
    /// in that case, but we still hand it back — callers should not
    /// trust a zero-sized rect for hit-test geometry).
    ///
    /// Used by [`MenuList`](../../teksilo_widgets/menu_list/struct.MenuList.html)'s
    /// safe-triangle submenu hover gate, which needs the open
    /// submenu's near-edge to test whether the cursor trajectory is
    /// still headed toward the submenu.
    pub fn bounds_for(&self, id: OverlayId) -> Option<Rect> {
        self.overlay(id).map(|o| o.bounds)
    }

    pub(crate) fn topmost_modal(&self) -> Option<&ActiveOverlay> {
        self.stack
            .iter()
            .rev()
            .find(|overlay| overlay.placement.is_modal())
    }

    /// Dismiss an overlay and all its children (cascade), returning the
    /// dismissed content widget IDs and the overlay's focus_restore target.
    pub fn dismiss_with_focus_restore(
        &mut self,
        id: OverlayId,
    ) -> (Vec<WidgetId>, Option<WidgetId>) {
        self.dismiss_with_focus_restore_because(id, DismissReason::Programmatic)
    }

    /// [`dismiss_with_focus_restore`](Self::dismiss_with_focus_restore),
    /// saying why.
    pub fn dismiss_with_focus_restore_because(
        &mut self,
        id: OverlayId,
        reason: DismissReason,
    ) -> (Vec<WidgetId>, Option<WidgetId>) {
        let focus_restore = self
            .stack
            .iter()
            .find(|overlay| overlay.id == id)
            .and_then(|overlay| overlay.focus_restore);
        let dismissed = self.dismiss_because(id, reason);
        (dismissed, focus_restore)
    }

    /// Dismiss all descendant overlays of `parent`, optionally preserving the
    /// subtree rooted at `preserve`.
    pub fn dismiss_descendants_of(
        &mut self,
        parent: OverlayId,
        preserve: Option<OverlayId>,
    ) -> (Vec<WidgetId>, Option<WidgetId>) {
        let mut to_dismiss = Vec::new();

        for overlay in &self.stack {
            if !self.is_descendant_of(overlay.id, parent) {
                continue;
            }
            if preserve
                .is_some_and(|keep| overlay.id == keep || self.is_descendant_of(overlay.id, keep))
            {
                continue;
            }
            to_dismiss.push(overlay.id);
        }

        if to_dismiss.is_empty() {
            return (Vec::new(), None);
        }

        let focus_restore = self
            .stack
            .iter()
            .rev()
            .find(|overlay| to_dismiss.contains(&overlay.id))
            .and_then(|overlay| overlay.focus_restore);

        let dismissed_content: Vec<WidgetId> = self
            .stack
            .iter()
            .filter(|overlay| to_dismiss.contains(&overlay.id))
            .map(|overlay| overlay.content_id)
            .collect();
        let callbacks: Vec<OverlayDismissCallback> = self
            .stack
            .iter()
            .filter(|overlay| to_dismiss.contains(&overlay.id))
            .filter_map(|overlay| overlay.on_dismiss.clone())
            .collect();
        self.stack
            .retain(|overlay| !to_dismiss.contains(&overlay.id));
        // Everything here is, by construction, a descendant going away with
        // its parent.
        self.pending_dismiss
            .extend(callbacks.into_iter().map(|cb| (cb, DismissReason::Cascade)));

        (dismissed_content, focus_restore)
    }

    /// Update the placement of an existing overlay.
    pub fn update_placement(&mut self, id: OverlayId, placement: OverlayPlacement) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id) {
            overlay.placement = placement;
        }
    }

    /// Re-derive an existing overlay's placement from its anchor on every
    /// positioning pass, for as long as it is up.
    pub(crate) fn set_placement_source(&mut self, id: OverlayId, source: OverlayPlacementSource) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id) {
            overlay.placement_source = Some(source);
        }
    }

    /// Update the parent-overlay link of an existing overlay. Used by the
    /// modal-presentation pipeline to retroactively attach the dialog
    /// scrim (pushed first, below the modal in the stack) to the modal
    /// (pushed second) so that dismissing the modal cascades through
    /// `dismiss_immediate` and also dismisses the scrim.
    pub fn set_parent_overlay(&mut self, id: OverlayId, parent: Option<OverlayId>) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id) {
            overlay.parent_overlay = parent;
        }
    }

    /// Dismiss an overlay and all its children (cascade).
    /// Returns the content widget IDs of all dismissed overlays.
    ///
    /// owned opacity signal and stamps `dismissing_started_real` /
    /// `dismissing_started_sim`, returning an
    /// Cascaded descendants vanish with the leaf's fade-out (they're
    /// typically submenus the user dismissed *via* the leaf, and a
    /// per-descendant tween would compete with the leaf's).
    pub fn dismiss(&mut self, id: OverlayId) -> Vec<WidgetId> {
        self.dismiss_because(id, DismissReason::Programmatic)
    }

    /// [`dismiss`](Self::dismiss), saying why — which is what the overlay's
    /// `on_dismiss` is handed.
    pub fn dismiss_because(&mut self, id: OverlayId, reason: DismissReason) -> Vec<WidgetId> {
        // Fade gate: if the target overlay has fade and isn't
        // already fading out, kick off the fade-out and defer the
        // entire cascade. Stamps both real and sim start times in
        // lockstep — the sim time uses the manager's mirrored
        // `sim_clock`, kept in sync by `WidgetTree::set_sim_clock`.
        let sim_now = self.sim_clock;
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id)
            && let Some(fade) = &mut overlay.fade
            && fade.dismissing_started_real.is_none()
        {
            // Animate opacity 1 → 0 over `duration`. Uses the same
            // try_animate_with_options path the rest of the
            // animation system uses; the scheduler picks it up next
            // frame and ticks the signal, dirty-marking the
            // content's opacity binding for repaint.
            let _ = fade
                .opacity
                .try_animate_with_options(crate::animation::AnimationRequest {
                    target: 0.0,
                    duration: fade.duration,
                    easing: teksilo_tokens::Easing::EaseOut,
                    frame_interval: None,
                    looping: false,
                    epsilon: 0.0,
                    max_duration: None,
                });
            let now_real = Instant::now();
            fade.dismissing_started_real = Some(now_real);
            fade.dismissing_started_sim = Some(sim_now);
            fade.dismiss_reason = Some(reason);
            return Vec::new();
        }
        self.dismiss_immediate(id, reason)
    }

    /// Internal: same shape as the original `dismiss`, but bypasses
    /// the fade gate. Used both by `dismiss` (no fade configured /
    /// already fading out) and by `process_pending_fade_dismissals`
    /// when a fade-out tween has completed. Also used by the orphaned-
    /// overlay GC (`WidgetTree::gc_orphaned_overlays`), where fading is
    /// impossible because the content widget is already destroyed.
    pub(crate) fn dismiss_immediate(
        &mut self,
        id: OverlayId,
        reason: DismissReason,
    ) -> Vec<WidgetId> {
        // Collect IDs to dismiss: the target + all descendants
        let mut to_dismiss = vec![id];
        let mut i = 0;
        while i < to_dismiss.len() {
            let parent = to_dismiss[i];
            for overlay in &self.stack {
                if overlay.parent_overlay == Some(parent) && !to_dismiss.contains(&overlay.id) {
                    to_dismiss.push(overlay.id);
                }
            }
            i += 1;
        }
        let dismissed_content: Vec<WidgetId> = self
            .stack
            .iter()
            .filter(|o| to_dismiss.contains(&o.id))
            .map(|o| o.content_id)
            .collect();
        // Collect dismiss callbacks (via Rc::clone) before retain
        // so we can invoke them AFTER the borrow is released.
        // Callbacks may do anything, including touching the arena,
        // so running them mid-retain would risk re-entrancy.
        let callbacks: Vec<OverlayDismissCallback> = self
            .stack
            .iter()
            .filter(|o| to_dismiss.contains(&o.id))
            .filter_map(|o| o.on_dismiss.clone())
            .collect();
        self.stack.retain(|o| !to_dismiss.contains(&o.id));
        if !to_dismiss.is_empty() {
            self.bump_version();
        }
        // The overlay that was actually asked to go gets the real reason; the
        // descendants it drags with it get `Cascade`, which is the only thing
        // that is true of them.
        let mut callbacks = callbacks.into_iter();
        if let Some(first) = callbacks.next() {
            self.pending_dismiss.push((first, reason));
        }
        self.pending_dismiss
            .extend(callbacks.map(|cb| (cb, DismissReason::Cascade)));
        dismissed_content
    }

    /// Drain overlays whose real-clock fade-out tween has completed.
    /// Call from the live layout pass; the framework dormants the
    /// returned content widget IDs and restores focus where
    /// appropriate. Each entry is
    /// `(overlay_id, dismissed_content_ids, focus_restore)` so the
    /// layout pass can run the same dormant-and-restore-focus flow
    /// it uses for
    /// [`dismiss_with_focus_restore`](Self::dismiss_with_focus_restore).
    pub fn process_pending_fade_dismissals(
        &mut self,
        now: Instant,
    ) -> Vec<(OverlayId, Vec<WidgetId>, Option<WidgetId>)> {
        self.process_pending_fade_dismissals_with(|fade| {
            let started = fade.dismissing_started_real?;
            Some(now.saturating_duration_since(started) >= fade.duration)
        })
    }

    /// Sim-clock variant for deterministic headless tests. Same
    /// shape as [`process_pending_fade_dismissals`](Self::process_pending_fade_dismissals)
    /// but reads `dismissing_started_sim`.
    pub fn process_pending_fade_dismissals_sim(
        &mut self,
        now_sim: Instant,
    ) -> Vec<(OverlayId, Vec<WidgetId>, Option<WidgetId>)> {
        self.process_pending_fade_dismissals_with(|fade| {
            let started = fade.dismissing_started_sim?;
            Some(now_sim.saturating_duration_since(started) >= fade.duration)
        })
    }

    fn process_pending_fade_dismissals_with(
        &mut self,
        mut elapsed_done: impl FnMut(&OverlayFadeState) -> Option<bool>,
    ) -> Vec<(OverlayId, Vec<WidgetId>, Option<WidgetId>)> {
        let ready: Vec<(OverlayId, Option<WidgetId>, Option<DismissReason>)> = self
            .stack
            .iter()
            .filter_map(|o| {
                let fade = o.fade.as_ref()?;
                if elapsed_done(fade)? {
                    Some((o.id, o.focus_restore, fade.dismiss_reason))
                } else {
                    None
                }
            })
            .collect();
        ready
            .into_iter()
            .map(|(id, focus_restore, reason)| {
                let dismissed =
                    self.dismiss_immediate(id, reason.unwrap_or(DismissReason::Programmatic));
                (id, dismissed, focus_restore)
            })
            .collect()
    }

    /// Earliest real-clock deadline at which a fading-out overlay
    /// wants to finish its dismissal. Used by the event-loop wakeup
    /// logic to schedule the next frame.
    pub fn next_fade_dismiss_deadline(&self) -> Option<Instant> {
        self.stack
            .iter()
            .filter_map(|o| {
                let fade = o.fade.as_ref()?;
                let started = fade.dismissing_started_real?;
                Some(started + fade.duration)
            })
            .min()
    }

    /// Dismiss the topmost overlay unconditionally (e.g., ArrowLeft for submenu cascading).
    /// Returns the overlay ID, content widget IDs, and focus_restore target.
    pub fn dismiss_top(&mut self) -> Option<(OverlayId, Vec<WidgetId>, Option<WidgetId>)> {
        self.dismiss_top_because(DismissReason::Programmatic)
    }

    /// [`dismiss_top`](Self::dismiss_top), saying why.
    pub fn dismiss_top_because(
        &mut self,
        reason: DismissReason,
    ) -> Option<(OverlayId, Vec<WidgetId>, Option<WidgetId>)> {
        if let Some(overlay) = self.stack.last() {
            let id = overlay.id;
            let focus_restore = overlay.focus_restore;
            let content_ids = self.dismiss_because(id, reason);
            Some((id, content_ids, focus_restore))
        } else {
            None
        }
    }

    /// Try to dismiss an overlay on Escape, respecting `DismissBehavior`.
    ///
    /// Scans the stack top-down for the first overlay that Escape may close,
    /// rather than consulting only `stack.last()`. Two reasons:
    ///
    /// - A hover-opened overlay (`PointerLeave` — every shown tooltip) is
    ///   Escape-dismissible. WCAG 2.2 SC 1.4.13(a) requires content shown on
    ///   hover to be dismissible *without moving the pointer*, and Escape is
    ///   that mechanism; previously no key could close a plain tooltip.
    /// - A tooltip lives on the same stack as whatever it is anchored inside.
    ///   Hovering a menu item long enough to raise its tooltip put a
    ///   non-Escape overlay on top, so Escape silently did nothing at all
    ///   until the tooltip's own 100 ms leave-grace expired — the keystroke
    ///   was swallowed, not forwarded to the menu underneath.
    ///
    /// `Manual` overlays still block the scan: they are modal-ish by
    /// construction and own the keystroke. An
    /// [inert](OverlayRequest::inert) one owns nothing and is stepped over;
    /// the tree retires the inert overlays Escape may close beforehand,
    /// without spending the key.
    pub fn try_dismiss_top_on_escape(
        &mut self,
    ) -> Option<(OverlayId, Vec<WidgetId>, Option<WidgetId>)> {
        let target = self
            .stack
            .iter()
            .rev()
            // An overlay already fading out stays on the stack until its tween
            // finishes, but it is on its way out and no longer owns the
            // keystroke — targeting it again would spend an Escape on a corpse
            // and leave whatever is underneath unreachable.
            .filter(|o| !o.is_dismissing() && !o.inert)
            .find_map(|o| match o.dismiss {
                DismissBehavior::EscapeKey
                | DismissBehavior::EscapeOrClickOutside
                | DismissBehavior::PointerLeave { .. } => Some(Some(o.id)),
                // Opaque to Escape and to everything under it.
                DismissBehavior::Manual => Some(None),
                DismissBehavior::ClickOutside => None,
            })??;
        let focus_restore = self
            .stack
            .iter()
            .find(|o| o.id == target)
            .and_then(|o| o.focus_restore);
        let content_ids = self.dismiss_because(target, DismissReason::Escape);
        Some((target, content_ids, focus_restore))
    }

    /// Dismiss every [inert](ActiveOverlay::inert) overlay Escape may close,
    /// returning the content ids that went.
    ///
    /// The plain tooltip's rule, for overlays that are not tooltip entries: an
    /// overlay nothing can be done in is never what an Escape is *for*, so it
    /// goes and the key carries on to the field, menu or dialog the user meant
    /// it for. No focus is restored: nothing in such an overlay took any.
    pub(crate) fn dismiss_inert_on_escape(&mut self) -> Vec<WidgetId> {
        let targets: Vec<OverlayId> = self
            .stack
            .iter()
            .filter(|o| o.inert && !o.is_dismissing())
            .filter(|o| {
                matches!(
                    o.dismiss,
                    DismissBehavior::EscapeKey
                        | DismissBehavior::EscapeOrClickOutside
                        | DismissBehavior::PointerLeave { .. }
                )
            })
            .map(|o| o.id)
            .collect();
        targets
            .into_iter()
            .flat_map(|id| self.dismiss_because(id, DismissReason::Escape))
            .collect()
    }

    /// Set the focus_restore target for the topmost overlay.
    ///
    /// Does nothing when that overlay is [inert](OverlayRequest::inert): it
    /// takes no focus, so it has none to give back, and a target recorded
    /// here would hand focus, when it went, to whatever held it when it
    /// appeared, however long ago and wherever focus has been since. Every
    /// show path records its restore target through this, so the rule is
    /// kept here rather than at each of them.
    pub fn set_top_focus_restore(&mut self, focus_restore: WidgetId) {
        if let Some(overlay) = self.stack.last_mut()
            && !overlay.inert
        {
            overlay.focus_restore = Some(focus_restore);
        }
    }

    /// Dismiss all overlays.
    /// Returns the content widget IDs of all dismissed overlays.
    /// Fires every dismissed overlay's `on_dismiss` callback after the
    /// stack is cleared — same contract as [`dismiss`](Self::dismiss),
    /// so wrappers like [`PopoverButton`](crate::widget::EventContext)'s
    /// `popover_open` signal flip back to `false` when a `MenuItem`
    /// fires `ctx.dismiss_all_overlays()`. Without this, the trigger's
    /// next click would observe stale-true and silently retoggle
    /// instead of reopening the menu.
    pub fn dismiss_all(&mut self) -> Vec<WidgetId> {
        self.dismiss_all_because(DismissReason::Programmatic)
    }

    /// [`dismiss_all`](Self::dismiss_all), saying why.
    pub fn dismiss_all_because(&mut self, reason: DismissReason) -> Vec<WidgetId> {
        let content_ids: Vec<WidgetId> = self.stack.iter().map(|o| o.content_id).collect();
        if content_ids.is_empty() {
            return content_ids;
        }
        // Collect dismiss callbacks (via Rc::clone) before clear so we
        // can invoke them AFTER the borrow is released. Callbacks may
        // do anything, including touching the arena, so running them
        // mid-clear would risk re-entrancy. Mirrors the pattern in
        // [`dismiss_immediate`](Self::dismiss_immediate).
        let callbacks: Vec<OverlayDismissCallback> = self
            .stack
            .iter()
            .filter_map(|o| o.on_dismiss.clone())
            .collect();
        self.stack.clear();
        self.bump_version();
        self.pending_dismiss
            .extend(callbacks.into_iter().map(|cb| (cb, reason)));
        content_ids
    }

    /// Dismiss every overlay whose content is **not** in `keep`, parking each
    /// dismissed overlay's `on_dismiss` for the tree to run. Used when opening a
    /// context menu: any
    pub fn dismiss_except(&mut self, keep: &std::collections::HashSet<WidgetId>) -> Vec<WidgetId> {
        self.dismiss_except_because(keep, DismissReason::Programmatic)
    }

    /// [`dismiss_except`](Self::dismiss_except), saying why.
    pub fn dismiss_except_because(
        &mut self,
        keep: &std::collections::HashSet<WidgetId>,
        reason: DismissReason,
    ) -> Vec<WidgetId> {
        let dismissed: Vec<WidgetId> = self
            .stack
            .iter()
            .filter(|o| !keep.contains(&o.content_id))
            .map(|o| o.content_id)
            .collect();
        if dismissed.is_empty() {
            return dismissed;
        }
        // Clone callbacks before mutating the stack, then run them after the
        // borrow is released (they may touch the arena) — mirrors `dismiss_all`.
        let callbacks: Vec<OverlayDismissCallback> = self
            .stack
            .iter()
            .filter(|o| !keep.contains(&o.content_id))
            .filter_map(|o| o.on_dismiss.clone())
            .collect();
        self.stack.retain(|o| keep.contains(&o.content_id));
        self.bump_version();
        self.pending_dismiss
            .extend(callbacks.into_iter().map(|cb| (cb, reason)));
        dismissed
    }

    /// Take the dismissal callbacks parked by the dismissal methods.
    ///
    /// The manager removes an overlay from the stack and collects its
    /// `on_dismiss` before mutating (the re-entrancy discipline the collect
    /// loops already had); it cannot *run* it, because the callback now needs
    /// an `EventContext` and this type has no tree. So it parks it here and
    /// `WidgetTree::run_pending_dismiss_callbacks` drains it.
    ///
    /// Draining is idempotent: a second call returns nothing.
    pub(crate) fn take_pending_dismiss(&mut self) -> Vec<(OverlayDismissCallback, DismissReason)> {
        std::mem::take(&mut self.pending_dismiss)
    }

    /// Whether there are any active overlays.
    pub fn is_empty(&self) -> bool {
        self.stack.is_empty()
    }

    /// Number of active overlays.
    pub fn len(&self) -> usize {
        self.stack.len()
    }

    /// Get all active overlay content widget IDs (for rendering).
    pub fn active_content_ids(&self) -> Vec<WidgetId> {
        self.stack.iter().map(|o| o.content_id).collect()
    }

    /// Get all active overlay IDs (for testing/querying). Excludes
    /// overlays currently fading out — once a dismiss has been
    /// requested the overlay is conceptually gone (the visible
    /// opacity tween is on the way to 0 and the deferred removal
    /// will fire on the next layout pass after the fade-out
    /// completes), so user code asking "is this overlay still up?"
    /// gets the expected answer.
    pub fn active_ids(&self) -> Vec<OverlayId> {
        self.stack
            .iter()
            .filter(|o| {
                o.fade
                    .as_ref()
                    .is_none_or(|f| f.dismissing_started_real.is_none())
            })
            .map(|o| o.id)
            .collect()
    }

    /// Get the anchor widget for an overlay.
    pub fn anchor_for(&self, id: OverlayId) -> Option<WidgetId> {
        self.stack.iter().find(|o| o.id == id).map(|o| o.anchor)
    }

    /// Screen rects of every overlay that is currently *interactive* —
    /// open, not yet fading out and not [inert](OverlayRequest::inert), the
    /// same predicate [`hit_test`](Self::hit_test) uses to route pointer
    /// events.
    /// Zero-area entries are skipped: an overlay shown this frame has
    /// not been through its first layout pass yet (`bounds ==
    /// Rect::ZERO`), and a degenerate rect must not be mistaken for a
    /// hit at the origin.
    ///
    /// Consumed by the paint pass, which hands the list to
    /// [`Widget::after_paint`](crate::widget::Widget::after_paint) via
    /// `WidgetTreeView` so chrome aggregators can subtract floating
    /// content from the regions they publish — `TitleBar` carves these
    /// out of the OS caption so an overlay above the title bar (the
    /// hamburger `MenuBar`'s revealed bar, a tall modal) stays
    /// clickable on Windows instead of dragging the window.
    pub fn interactive_rects(&self) -> Vec<Rect> {
        self.stack
            .iter()
            .filter(|o| {
                !o.inert
                    && o.fade
                        .as_ref()
                        .is_none_or(|f| f.dismissing_started_real.is_none())
            })
            .map(|o| o.bounds)
            .filter(|r| r.width > 0.0 && r.height > 0.0)
            .collect()
    }

    /// Get the topmost overlay.
    #[allow(dead_code)] // used for overlay z-ordering and focus management
    pub(crate) fn topmost(&self) -> Option<&ActiveOverlay> {
        self.stack.last()
    }

    /// Check if a point hits any overlay (topmost first).
    /// Returns the overlay ID if hit, None if the point is outside all overlays.
    ///
    /// Overlays whose fade-out has begun are skipped — the same predicate
    /// [`active_ids`](Self::active_ids) uses. A dismissed-but-still-fading
    /// overlay lingers in the stack until
    /// [`process_pending_fade_dismissals`](Self::process_pending_fade_dismissals)
    /// removes it; treating it as hittable would route clicks into the
    /// vanishing content (and suppress outside-click dismissal of the
    /// overlays beneath it) for the whole fade duration.
    ///
    /// An [inert](OverlayRequest::inert) overlay is skipped for the same
    /// reason, permanently: nothing in it takes the point, so the point is
    /// asked of whatever is beneath it, the next overlay down included.
    pub fn hit_test(&self, point: Point) -> Option<OverlayId> {
        for overlay in self.stack.iter().rev() {
            let fading_out = overlay
                .fade
                .as_ref()
                .is_some_and(|f| f.dismissing_started_real.is_some());
            if !fading_out && !overlay.inert && overlay.bounds.contains(point) {
                return Some(overlay.id);
            }
        }
        None
    }

    /// Handle a click-outside event: if the click is outside all overlays
    /// with ClickOutside dismiss behavior, dismiss them.
    /// Returns the content widget IDs of dismissed overlays (empty if none)
    /// and the focus-restore target — the widget that was focused before
    /// the *bottommost* dismissed overlay opened. Topmost overlays'
    /// `focus_restore` would point inside an overlay that's also being
    /// dismissed in the same pass, which would leave focus on a
    /// dormant widget; the bottommost target represents focus before
    /// any of the dismissed overlays opened. Aligns the click-outside
    /// path with the Esc / ArrowLeft-cascade paths, both of which
    /// already restore focus from the dismissed overlay.
    ///
    /// The third return value lists the anchor widgets of the dismissed
    /// *click-opened* overlays (`ClickOutside` / `EscapeOrClickOutside`).
    /// The dispatcher consumes a primary press that lands on one of these
    /// anchors so the trigger merely closes its overlay rather than
    /// reopening it; every other dismiss-press falls through to the widget
    /// under the cursor (so one click both dismisses the overlay and
    /// activates the control beneath). Hover-opened (`PointerLeave`)
    /// overlays contribute no anchor — a press on their anchor passes
    /// through, e.g. clicking a button that still has its tooltip up.
    pub fn handle_click_outside(
        &mut self,
        point: Point,
    ) -> (Vec<WidgetId>, Option<WidgetId>, Vec<WidgetId>) {
        self.dismiss_outside_press(point, &[])
    }

    /// [`handle_click_outside`](Self::handle_click_outside) with the points at
    /// which *other* contacts are holding a live press.
    ///
    /// A press is only "outside" relative to the overlays nobody else is
    /// working in. A second finger landing on the page while the first is
    /// dragging a menu's scrollbar is not a dismissal gesture; it is the second
    /// finger of a two-finger interaction, and closing the menu under the first
    /// one takes the interaction away mid-flight. Each busy point raises the
    /// floor of the layered rule to the overlay it is inside, so overlays at or
    /// below any busy contact survive and everything above still closes.
    ///
    /// An empty `busy` is the historical behaviour exactly, which is what a
    /// mouse-only tree always passes.
    pub fn dismiss_outside_press(
        &mut self,
        point: Point,
        busy: &[Point],
    ) -> (Vec<WidgetId>, Option<WidgetId>, Vec<WidgetId>) {
        let (to_dismiss, toggle_anchors) = self.outside_press_targets(point, busy);
        self.apply_outside_press(to_dismiss, toggle_anchors)
    }

    /// The overlays an outside press at `point` selects, and the click-opened
    /// ones' anchors. Pure: nothing is dismissed.
    fn outside_press_targets(
        &self,
        point: Point,
        busy: &[Point],
    ) -> (Vec<OverlayId>, Vec<WidgetId>) {
        if self.stack.is_empty() {
            return (Vec::new(), Vec::new());
        }

        // Dismissal is *layered*, not stack-wide. A press that lands inside
        // overlay `k` is still *outside* every overlay stacked above `k`, so
        // those upper overlays with a click-outside policy must close — e.g. a
        // sticky tooltip (or a combo dropdown) floating above a modal is
        // dismissed when the user clicks elsewhere in the modal. Overlays at
        // or below `k` keep their content: the press landed within the stack,
        // not outside it.
        //
        // `hit_index` is the topmost non-fading overlay containing the point,
        // or `None` for a press on the bare background (then nothing is
        // "below" the press and every dismissable overlay closes — the
        // classic outside-click). This replaces an earlier stack-wide
        // short-circuit that returned as soon as the press hit *any* overlay:
        // once a modal — or its full-viewport scrim — was open, that guard
        // made *no* click-outside overlay dismissable at all.
        // An inert overlay is not somewhere a press can land "inside": the
        // press belongs to what is beneath it, so an overlay under it is
        // outside the press exactly when it would be with the inert one gone.
        let index_at = |p: Point| {
            self.stack.iter().enumerate().rev().find_map(|(i, o)| {
                let fading_out = o
                    .fade
                    .as_ref()
                    .is_some_and(|f| f.dismissing_started_real.is_some());
                (!fading_out && !o.inert && o.bounds.contains(p)).then_some(i)
            })
        };
        // The press's own floor, raised by every contact already working inside
        // an overlay — see `dismiss_outside_press`.
        let hit_index = std::iter::once(point)
            .chain(busy.iter().copied())
            .filter_map(index_at)
            .max();

        // Collect the overlays this outside-click should close, and — for
        // the *click-opened* ones — their anchor widgets. The anchors let
        // the dispatcher decide whether the same press may fall through to
        // the widget beneath: a press on a click-opened overlay's own
        // anchor is consumed, since the anchor's tap handler would
        // otherwise reopen what this press just dismissed. Hover-opened
        // overlays (`PointerLeave`) are not click toggles, so their
        // anchors are omitted and a press there falls through.
        let mut to_dismiss: Vec<OverlayId> = Vec::new();
        let mut toggle_anchors: Vec<WidgetId> = Vec::new();
        for (i, o) in self.stack.iter().enumerate() {
            // Skip the hit overlay and everything beneath it — the press
            // landed inside them (or was covered by them), so they survive.
            if hit_index.is_some_and(|k| i <= k) {
                continue;
            }
            // The text-affordance band is not part of anyone's outside-press
            // dismissal: every tap that moves a caret is outside a selection
            // handle, so this rule would retire the handles on the first tap
            // that used them. Their lifetime belongs to the controller that
            // raised them.
            if !o.band.dismissed_by_outside_press() {
                continue;
            }
            match o.dismiss {
                DismissBehavior::ClickOutside | DismissBehavior::EscapeOrClickOutside => {
                    to_dismiss.push(o.id);
                    toggle_anchors.push(o.anchor);
                }
                DismissBehavior::PointerLeave { .. } => to_dismiss.push(o.id),
                DismissBehavior::EscapeKey | DismissBehavior::Manual => {}
            }
        }

        (to_dismiss, toggle_anchors)
    }

    /// Close a selected set and report what the dispatcher needs.
    fn apply_outside_press(
        &mut self,
        to_dismiss: Vec<OverlayId>,
        toggle_anchors: Vec<WidgetId>,
    ) -> (Vec<WidgetId>, Option<WidgetId>, Vec<WidgetId>) {
        if to_dismiss.is_empty() {
            return (Vec::new(), None, Vec::new());
        }

        let focus_restore = self
            .stack
            .iter()
            .find(|o| to_dismiss.contains(&o.id))
            .and_then(|o| o.focus_restore);

        let mut all_dismissed = Vec::new();
        for id in to_dismiss {
            all_dismissed.extend(self.dismiss_because(id, DismissReason::OutsidePress));
        }
        (all_dismissed, focus_restore, toggle_anchors)
    }

    // -----------------------------------------------------------------
    // Release dismissal
    // -----------------------------------------------------------------

    /// Arm an outside press for `pointer` at `point`, to be committed on its
    /// release.
    ///
    /// The direct-pointer half of outside-press dismissal. A mouse dismisses on
    /// the press and falls through, because a cursor names one pixel and the
    /// user aimed at it; a finger covers what it is about to actuate, so a tap
    /// that closes a menu must close only the menu. Arming defers the decision
    /// to the release and, while it stands, withholds the `Down` from whatever
    /// is beneath — so if the press is cancelled, or slid onto the very overlay
    /// it would have closed, the whole gesture delivers nothing at all.
    ///
    /// Returns a zeroed [`DismissArm`] and stores nothing when the press would
    /// close no overlay: an arm that has nothing to commit must not suppress
    /// the press beneath it.
    pub fn arm_dismiss(&mut self, pointer: PointerId, point: Point, busy: &[Point]) -> DismissArm {
        self.abort_dismiss(pointer);
        let (overlays, anchors) = self.outside_press_targets(point, busy);
        if overlays.is_empty() {
            return DismissArm::default();
        }
        self.arms.push(ArmedDismiss {
            pointer,
            overlays,
            anchors,
        });
        DismissArm {
            will_dismiss: true,
            suppress_beneath: true,
        }
    }

    /// Complete `pointer`'s armed dismissal at its release point.
    ///
    /// Returns the same triple as
    /// [`handle_click_outside`](Self::handle_click_outside), empty when the
    /// pointer holds no arm.
    ///
    /// The release point is re-tested, and only overlays the release is *still*
    /// outside are closed. That is the slide-off case: a finger that lands
    /// beside a menu, drags onto it and lifts there has changed its mind, and
    /// the menu it is now touching must not be the thing it closes. The
    /// suppressed `Down` means nothing beneath ever saw the press either, so an
    /// aborted commit leaves the tree exactly as it found it.
    pub fn commit_dismiss(
        &mut self,
        pointer: PointerId,
        point: Point,
    ) -> (Vec<WidgetId>, Option<WidgetId>, Vec<WidgetId>) {
        let Some(index) = self.arms.iter().position(|a| a.pointer == pointer) else {
            return (Vec::new(), None, Vec::new());
        };
        let arm = self.arms.remove(index);
        let (still_outside, _) = self.outside_press_targets(point, &[]);
        let to_dismiss: Vec<OverlayId> = arm
            .overlays
            .into_iter()
            .filter(|id| still_outside.contains(id))
            .collect();
        let anchors = if to_dismiss.is_empty() {
            Vec::new()
        } else {
            arm.anchors
        };
        self.apply_outside_press(to_dismiss, anchors)
    }

    /// Drop `pointer`'s arm without dismissing anything. Returns whether there
    /// was one — a cancelled press, or a contact that ended without a release.
    pub fn abort_dismiss(&mut self, pointer: PointerId) -> bool {
        let before = self.arms.len();
        self.arms.retain(|a| a.pointer != pointer);
        self.arms.len() != before
    }

    /// Whether `pointer` is holding an armed dismissal.
    pub fn has_armed_dismiss(&self, pointer: PointerId) -> bool {
        self.arms.iter().any(|a| a.pointer == pointer)
    }

    /// Every pointer currently holding an arm. Used by the dispatcher to drop
    /// arms whose contact has gone away without either releasing or cancelling.
    pub fn armed_pointers(&self) -> Vec<PointerId> {
        self.arms.iter().map(|a| a.pointer).collect()
    }

    /// Set the content bounds for an overlay (after its content has been laid out).
    pub fn set_content_bounds(&mut self, id: OverlayId, size: Size) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id) {
            overlay.bounds = Rect::new(overlay.bounds.x, overlay.bounds.y, size.width, size.height);
        }
    }

    /// Get overlay by content widget ID (for routing events to the correct overlay).
    pub fn find_by_content(&self, content_id: WidgetId) -> Option<OverlayId> {
        self.stack
            .iter()
            .find(|o| o.content_id == content_id)
            .map(|o| o.id)
    }

    /// Convenience accessor for the safe-triangle hover gate: returns
    /// the bounds rect of the open overlay whose root content widget
    /// id matches `content_id`, or `None` when no such overlay is
    /// active. Equivalent to `find_by_content` + `bounds_for` chained.
    pub fn bounds_for_content(&self, content_id: WidgetId) -> Option<Rect> {
        self.stack
            .iter()
            .find(|o| o.content_id == content_id)
            .map(|o| o.bounds)
    }

    // -------------------- Safe region (submenu traversal) --------------------

    /// Arm the safe triangle for the overlay whose root content widget
    /// is `content_id`, with its apex at `apex` — the point the pointer
    /// left the anchor at.
    ///
    /// While armed and unexpired, a pointer inside the triangle
    /// spanned by the apex and this overlay's near vertical edge is
    /// treated as still inside the overlay's region, so neither the
    /// pointer-leave grace nor a sibling's hover-switch dismisses it.
    /// Re-arming an already-armed region restarts its budget.
    /// No-ops when no such overlay is open.
    pub(crate) fn arm_safe_region(
        &mut self,
        content_id: WidgetId,
        apex: Point,
        real_now: Instant,
        sim_now: Instant,
    ) {
        if let Some(overlay) = self
            .stack
            .iter_mut()
            .find(|o| o.content_id == content_id && !o.is_dismissing())
        {
            overlay.safe_apex = Some(apex);
            overlay.safe_apex_started_real = Some(real_now);
            overlay.safe_apex_started_sim = Some(sim_now);
        }
    }

    /// Disarm the safe triangle on the overlay with the given id. Called
    /// when the pointer arrives (or returns) and when the budget is
    /// spent — after which the overlay dismisses on the ordinary
    /// schedule. Straying out of the cone does **not** disarm: it only
    /// starts the pointer-leave grace, which a re-entry cancels. See
    /// [`safe_triangle`].
    pub(crate) fn clear_safe_region(&mut self, id: OverlayId) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id) {
            overlay.safe_apex = None;
            overlay.safe_apex_started_real = None;
            overlay.safe_apex_started_sim = None;
        }
    }

    /// The armed apex of the overlay rooted at `content_id`, if any —
    /// without regard to the budget, which only the tree's clocks can
    /// judge. Callers wanting the answer a widget may act on go through
    /// `WidgetTree::unexpired_safe_apex_for_content`, which is what
    /// fills the per-dispatch `EventContext` snapshot.
    pub(crate) fn safe_apex_for_content(&self, content_id: WidgetId) -> Option<Point> {
        self.stack
            .iter()
            .find(|o| o.content_id == content_id)
            .and_then(|o| o.safe_apex)
    }

    /// Whether `point` currently sits inside the armed safe triangle of
    /// the overlay with the given id. `false` when the region is not
    /// armed or the overlay has no bounds yet.
    pub(crate) fn point_in_safe_region(&self, id: OverlayId, point: Point) -> bool {
        self.stack
            .iter()
            .find(|o| o.id == id)
            .and_then(|o| o.safe_apex.map(|apex| (apex, o.bounds)))
            .is_some_and(|(apex, bounds)| point_in_safe_triangle(point, apex, bounds))
    }

    /// Change the dismiss behavior of an active overlay in place.
    ///
    /// Used by rich tooltips that promote from "ephemeral hover" to
    /// "sticky panel" after a dwell timer: at t=2s the tooltip calls
    /// this to swap `PointerLeave` for `EscapeOrClickOutside`, so the
    /// overlay stops vanishing the moment the pointer leaves the
    /// anchor. Also cancels any in-flight pointer-leave countdown.
    pub fn set_dismiss(&mut self, id: OverlayId, behavior: DismissBehavior) {
        if let Some(overlay) = self.stack.iter_mut().find(|o| o.id == id) {
            overlay.dismiss = behavior;
            overlay.pointer_leave_started_real = None;
            overlay.pointer_leave_started_sim = None;
        }
    }
}

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

impl std::fmt::Debug for OverlayManager {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("OverlayManager")
            .field("active_count", &self.stack.len())
            .finish()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use slotmap::KeyData;

    pub(super) fn fake_id(n: u64) -> WidgetId {
        KeyData::from_ffi(n).into()
    }

    #[test]
    fn a_new_request_takes_the_documented_defaults_and_each_builder_sets_its_field() {
        let request = OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::TrailingEdge,
            DismissBehavior::EscapeKey,
        );
        assert_eq!(request.content_id, fake_id(10));
        assert_eq!(request.anchor, fake_id(1));
        assert!(matches!(request.placement, OverlayPlacement::TrailingEdge));
        assert!(matches!(request.dismiss, DismissBehavior::EscapeKey));
        assert_eq!(request.layer, OverlayLayer::InTree);
        assert_eq!(request.parent_overlay, None);
        assert!(request.on_dismiss.is_none());
        assert_eq!(request.fade_duration, None);
        assert!(!request.inert);

        let callback: OverlayDismissCallback = Rc::new(|_, _| {});
        let request = request.layer(OverlayLayer::NativePopup);
        assert_eq!(request.layer, OverlayLayer::NativePopup);
        let request = request.parent_overlay(OverlayId::new(7));
        assert_eq!(request.parent_overlay, Some(OverlayId::new(7)));
        let request = request.on_dismiss(callback.clone());
        assert!(
            request
                .on_dismiss
                .as_ref()
                .is_some_and(|installed| Rc::ptr_eq(installed, &callback)),
        );
        let request = request.with_fade(Duration::from_millis(150));
        assert_eq!(request.fade_duration, Some(Duration::from_millis(150)));
        let request = request.inert();
        assert!(request.inert);

        // No builder reaches past its own field.
        assert_eq!(request.content_id, fake_id(10));
        assert_eq!(request.anchor, fake_id(1));
        assert!(matches!(request.placement, OverlayPlacement::TrailingEdge));
        assert!(matches!(request.dismiss, DismissBehavior::EscapeKey));
        assert_eq!(request.layer, OverlayLayer::NativePopup);
        assert_eq!(request.parent_overlay, Some(OverlayId::new(7)));
        assert!(request.on_dismiss.is_some());
        assert_eq!(request.fade_duration, Some(Duration::from_millis(150)));
    }

    #[test]
    fn dismiss_all_fires_on_dismiss_callbacks() {
        // Regression: a `MenuItem`'s tap handler calls
        // `ctx.dismiss_all_overlays()` to close the menu after firing
        // its action. The dismiss callback set on the parent
        // `PopoverButton`/`PopoverIconButton`'s `OverlayRequest`
        // (which flips `popover_open` back to `false`) must fire so
        // the next trigger click reopens the menu instead of
        // observing stale-true and silently retoggling.
        //
        // The manager no longer *runs* these — a dismissal callback takes an
        // `EventContext` and the manager has no tree — so what it owes is
        // that every dismissed overlay's callback is parked for the tree to
        // run. Losing one here loses it everywhere.
        use std::rc::Rc;
        let mut mgr = OverlayManager::new();
        let cb_a: OverlayDismissCallback = Rc::new(|_, _| {});
        let cb_b: OverlayDismissCallback = Rc::new(|_, _| {});
        mgr.show(
            OverlayRequest::new(
                fake_id(10),
                fake_id(1),
                OverlayPlacement::Below,
                DismissBehavior::ClickOutside,
            )
            .on_dismiss(cb_a),
        );
        mgr.show(
            OverlayRequest::new(
                fake_id(11),
                fake_id(2),
                OverlayPlacement::Below,
                DismissBehavior::ClickOutside,
            )
            .on_dismiss(cb_b),
        );
        let dismissed = mgr.dismiss_all();
        assert_eq!(dismissed.len(), 2);
        assert!(mgr.is_empty());
        let parked = mgr.take_pending_dismiss();
        assert_eq!(
            parked.len(),
            2,
            "both overlays' on_dismiss must be parked for the tree to run",
        );
        assert!(
            parked
                .iter()
                .all(|(_, reason)| *reason == DismissReason::Programmatic),
            "`dismiss_all` is the application asking, so that is what the \
             callbacks are told",
        );
        assert!(
            mgr.take_pending_dismiss().is_empty(),
            "draining is not repeatable — a second read must not re-run them",
        );
    }

    #[test]
    fn show_and_dismiss() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::ClickOutside,
        ));
        assert_eq!(mgr.len(), 1);

        mgr.dismiss(id);
        assert!(mgr.is_empty());
    }

    #[test]
    fn cascade_dismissal() {
        let mut mgr = OverlayManager::new();
        let parent = mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::ClickOutside,
        ));
        let _child = mgr.show(
            OverlayRequest::new(
                fake_id(11),
                fake_id(10),
                OverlayPlacement::TrailingEdge,
                DismissBehavior::ClickOutside,
            )
            .parent_overlay(parent),
        );
        assert_eq!(mgr.len(), 2);

        // Dismissing parent cascades to child
        mgr.dismiss(parent);
        assert!(mgr.is_empty());
    }

    #[test]
    fn cascade_depth_is_bounded() {
        // A cyclic tooltip `:key` cascade (A→B→A) keeps minting nested
        // overlays with no natural ceiling. `MAX_OVERLAY_NESTING_DEPTH`
        // bounds it: once a new overlay would nest at the cap, `show`
        // drops it rather than growing the stack forever — and must not
        // panic, since this is reachable by real user clicking.
        let mut mgr = OverlayManager::new();
        let mut parent = mgr.show(OverlayRequest::new(
            fake_id(100),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));
        // Root is depth 0; fill the chain so MAX overlays exist, the
        // deepest at depth MAX-1.
        for i in 1..MAX_OVERLAY_NESTING_DEPTH {
            parent = mgr.show(
                OverlayRequest::new(
                    fake_id(100 + i as u64),
                    fake_id(1),
                    OverlayPlacement::Below,
                    DismissBehavior::Manual,
                )
                .parent_overlay(parent),
            );
        }
        assert_eq!(
            mgr.len(),
            MAX_OVERLAY_NESTING_DEPTH,
            "chain should fill exactly to the cap"
        );

        // The next child would nest at depth == MAX → dropped.
        let dropped = mgr.show(
            OverlayRequest::new(
                fake_id(999),
                fake_id(1),
                OverlayPlacement::Below,
                DismissBehavior::Manual,
            )
            .parent_overlay(parent),
        );
        assert_eq!(
            mgr.len(),
            MAX_OVERLAY_NESTING_DEPTH,
            "over-cap overlay must not be pushed"
        );
        assert!(
            mgr.stack.iter().all(|o| o.id != dropped),
            "the dropped overlay id must not appear in the stack"
        );
    }

    #[test]
    fn dismiss_top() {
        let mut mgr = OverlayManager::new();
        let _a = mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));
        let b = mgr.show(OverlayRequest::new(
            fake_id(11),
            fake_id(2),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));

        let dismissed = mgr.dismiss_top();
        assert_eq!(dismissed.map(|(id, _, _)| id), Some(b));
        assert_eq!(mgr.len(), 1);
    }

    #[test]
    fn click_outside_dismisses() {
        let mut mgr = OverlayManager::new();
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::ClickOutside,
        ));

        // Set overlay bounds
        let id = mgr.active_ids()[0];
        mgr.set_content_bounds(id, Size::new(100.0, 50.0));

        // Click inside — no dismiss
        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(50.0, 25.0));
        assert!(dismissed.is_empty());
        assert_eq!(mgr.len(), 1);

        // Click outside — dismissed
        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(500.0, 500.0));
        assert!(!dismissed.is_empty());
        assert!(mgr.is_empty());
    }

    #[test]
    fn click_outside_returns_focus_restore() {
        let mut mgr = OverlayManager::new();
        let trigger = fake_id(99);
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::ClickOutside,
        ));
        let id = mgr.active_ids()[0];
        mgr.set_content_bounds(id, Size::new(100.0, 50.0));
        mgr.set_top_focus_restore(trigger);

        let (dismissed, focus_restore, _) = mgr.handle_click_outside(Point::new(500.0, 500.0));
        assert_eq!(dismissed.len(), 1);
        assert_eq!(focus_restore, Some(trigger));
    }

    #[test]
    fn click_outside_focus_restore_picks_bottommost() {
        // When click-outside dismisses several stacked top-level
        // overlays in one pass, focus should land on the *oldest*
        // overlay's restore target — the focus state from before any
        // overlay opened. The topmost overlay's restore target points
        // inside the (now-dismissed) overlay below it.
        let mut mgr = OverlayManager::new();
        let pre_overlay_focus = fake_id(99);
        let inside_a = fake_id(50);
        let a = mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::ClickOutside,
        ));
        mgr.set_content_bounds(a, Size::new(100.0, 50.0));
        mgr.set_top_focus_restore(pre_overlay_focus);
        let b = mgr.show(OverlayRequest::new(
            fake_id(11),
            fake_id(2),
            OverlayPlacement::Below,
            DismissBehavior::ClickOutside,
        ));
        mgr.set_content_bounds(b, Size::new(100.0, 50.0));
        mgr.set_top_focus_restore(inside_a);

        let (_, focus_restore, _) = mgr.handle_click_outside(Point::new(500.0, 500.0));
        assert_eq!(focus_restore, Some(pre_overlay_focus));
    }

    #[test]
    fn manual_dismiss_ignores_click_outside() {
        let mut mgr = OverlayManager::new();
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));

        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(500.0, 500.0));
        assert!(dismissed.is_empty());
        assert_eq!(mgr.len(), 1);
    }

    #[test]
    fn escape_dismisses_escape_or_click_outside() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::EscapeOrClickOutside,
        ));

        let dismissed = mgr.try_dismiss_top_on_escape();
        assert_eq!(dismissed.map(|(oid, _, _)| oid), Some(id));
        assert!(mgr.is_empty());
    }

    #[test]
    fn escape_dismisses_escape_key_only() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::EscapeKey,
        ));

        // Escape should dismiss
        let dismissed = mgr.try_dismiss_top_on_escape();
        assert_eq!(dismissed.map(|(oid, _, _)| oid), Some(id));
        assert!(mgr.is_empty());
    }

    #[test]
    fn escape_does_not_dismiss_click_outside_only() {
        let mut mgr = OverlayManager::new();
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::ClickOutside,
        ));

        assert!(mgr.try_dismiss_top_on_escape().is_none());
        assert_eq!(mgr.len(), 1);
    }

    #[test]
    fn escape_does_not_dismiss_manual() {
        let mut mgr = OverlayManager::new();
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));

        assert!(mgr.try_dismiss_top_on_escape().is_none());
        assert_eq!(mgr.len(), 1);
    }

    #[test]
    fn click_outside_dismisses_escape_or_click_outside() {
        let mut mgr = OverlayManager::new();
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::EscapeOrClickOutside,
        ));

        let id = mgr.active_ids()[0];
        mgr.set_content_bounds(id, Size::new(100.0, 50.0));

        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(500.0, 500.0));
        assert!(!dismissed.is_empty());
        assert!(mgr.is_empty());
    }

    #[test]
    fn click_outside_reports_click_opened_anchors_only() {
        // An outside click dismisses both a click-opened dropdown and a
        // hover-opened tooltip, but only the click-opened overlay's anchor
        // is reported as a re-toggle guard: clicking a tooltip's anchor
        // should still fall through to the widget beneath.
        let mut mgr = OverlayManager::new();
        let click_anchor = fake_id(1);
        let hover_anchor = fake_id(2);

        let click_overlay = mgr.show(OverlayRequest::new(
            fake_id(10),
            click_anchor,
            OverlayPlacement::Below,
            DismissBehavior::EscapeOrClickOutside,
        ));
        mgr.set_content_bounds(click_overlay, Size::new(100.0, 50.0));

        let hover_overlay = mgr.show(OverlayRequest::new(
            fake_id(11),
            hover_anchor,
            OverlayPlacement::Below,
            DismissBehavior::PointerLeave {
                delay: std::time::Duration::from_millis(150),
            },
        ));
        mgr.set_content_bounds(hover_overlay, Size::new(100.0, 50.0));

        let (dismissed, _focus, toggle_anchors) =
            mgr.handle_click_outside(Point::new(500.0, 500.0));

        // Both overlays close on the outside click...
        assert_eq!(dismissed.len(), 2);
        assert!(mgr.is_empty());
        // ...but only the click-opened dropdown contributes a guard anchor.
        assert_eq!(toggle_anchors, vec![click_anchor]);
    }

    #[test]
    fn click_outside_does_not_dismiss_escape_key_only() {
        let mut mgr = OverlayManager::new();
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::EscapeKey,
        ));

        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(500.0, 500.0));
        assert!(dismissed.is_empty());
        assert_eq!(mgr.len(), 1);
    }

    #[test]
    fn click_outside_is_layered_over_a_modal() {
        // A modal card with a sticky tooltip floating above it (as a rich
        // tooltip becomes after it dwells). Regression for: while any modal
        // (or its full-viewport scrim) was open, the old stack-wide `hit_test`
        // short-circuit made *no* click-outside overlay dismissable, so the
        // sticky tooltip never closed on a click elsewhere in the modal.
        fn set_bounds(mgr: &mut OverlayManager, id: OverlayId, r: Rect) {
            mgr.stack.iter_mut().find(|o| o.id == id).unwrap().bounds = r;
        }
        // Build a fresh [modal, tooltip] stack. The modal card spans
        // x∈[300,900], y∈[60,740]; the sticky tooltip sits near the card's
        // bottom and *overflows* below it (y∈[620,760]).
        fn build() -> (OverlayManager, OverlayId, OverlayId) {
            let mut mgr = OverlayManager::new();
            let modal = mgr.show(OverlayRequest::new(
                fake_id(10),
                fake_id(1),
                OverlayPlacement::Centered,
                DismissBehavior::EscapeOrClickOutside,
            ));
            set_bounds(&mut mgr, modal, Rect::new(300.0, 60.0, 600.0, 680.0));
            let tooltip = mgr.show(OverlayRequest::new(
                fake_id(11),
                fake_id(2),
                OverlayPlacement::Below,
                // A promoted sticky rich tooltip: EscapeOrClickOutside.
                DismissBehavior::EscapeOrClickOutside,
            ));
            set_bounds(&mut mgr, tooltip, Rect::new(400.0, 620.0, 200.0, 140.0));
            (mgr, modal, tooltip)
        }

        // 1. Click elsewhere inside the modal card (outside the tooltip) →
        //    the tooltip (stacked above) dismisses; the modal stays up.
        let (mut mgr, modal, _tooltip) = build();
        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(350.0, 100.0));
        assert!(dismissed.contains(&fake_id(11)), "tooltip should dismiss");
        assert!(
            mgr.active_ids().contains(&modal),
            "modal must survive a click inside itself"
        );

        // 2. Click inside the tooltip — even the part overflowing below the
        //    card — leaves BOTH standing (nothing is stacked above the hit).
        let (mut mgr, modal, tooltip) = build();
        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(450.0, 750.0));
        assert!(
            dismissed.is_empty(),
            "clicking the tooltip dismisses nothing"
        );
        assert!(mgr.active_ids().contains(&modal));
        assert!(mgr.active_ids().contains(&tooltip));

        // 3. Click the bare background (outside both) → both dismiss, as
        //    before (each per its own click-outside policy).
        let (mut mgr, _modal, _tooltip) = build();
        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(10.0, 10.0));
        assert!(dismissed.contains(&fake_id(10)));
        assert!(dismissed.contains(&fake_id(11)));
        assert!(mgr.is_empty());
    }

    #[test]
    fn active_content_ids() {
        let mut mgr = OverlayManager::new();
        mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));
        mgr.show(OverlayRequest::new(
            fake_id(20),
            fake_id(2),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));

        let ids = mgr.active_content_ids();
        assert_eq!(ids.len(), 2);
        assert_eq!(ids[0], fake_id(10));
        assert_eq!(ids[1], fake_id(20));
    }

    #[test]
    fn hit_test_topmost_first() {
        let mut mgr = OverlayManager::new();
        let a = mgr.show(OverlayRequest::new(
            fake_id(10),
            fake_id(1),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));
        let b = mgr.show(OverlayRequest::new(
            fake_id(11),
            fake_id(2),
            OverlayPlacement::Below,
            DismissBehavior::Manual,
        ));

        // Both overlays at origin with same bounds
        mgr.set_content_bounds(a, Size::new(100.0, 50.0));
        mgr.set_content_bounds(b, Size::new(100.0, 50.0));

        // Hit test should find topmost (b)
        assert_eq!(mgr.hit_test(Point::new(50.0, 25.0)), Some(b));
    }

    #[test]
    fn hit_test_skips_a_fading_out_overlay() {
        // Regression: dismissing a faded overlay only starts the fade-out and
        // defers stack removal, so the overlay lingers in the stack (and its
        // content stays interactive) for the fade duration. `hit_test` must
        // treat it as gone — matching `active_ids` — so clicks reach the
        // widget underneath and outside-click dismissal of lower overlays
        // isn't suppressed by the ghost.
        let mut mgr = OverlayManager::new();
        let id = mgr.show(
            OverlayRequest::new(
                fake_id(10),
                fake_id(1),
                OverlayPlacement::Below,
                DismissBehavior::ClickOutside,
            )
            .with_fade(Duration::from_millis(150)),
        );
        mgr.set_content_bounds(id, Size::new(100.0, 50.0));
        let point = Point::new(50.0, 25.0);

        // Live overlay: hittable, and reported by active_ids.
        assert_eq!(mgr.hit_test(point), Some(id));
        assert!(mgr.active_ids().contains(&id));

        // The fade machinery is populated post-show by the framework.
        mgr.attach_fade(id, Signal::new(1.0), Duration::from_millis(150));

        // Dismissing only starts the fade-out — the overlay is still in the
        // stack until `process_pending_fade_dismissals` fires.
        let dismissed = mgr.dismiss(id);
        assert!(dismissed.is_empty(), "fade-out defers removal");
        assert_eq!(mgr.stack.len(), 1, "overlay lingers during the fade");

        // Both predicates now agree it's gone.
        assert_eq!(
            mgr.hit_test(point),
            None,
            "fading overlay no longer eats clicks"
        );
        assert!(!mgr.active_ids().contains(&id));
    }

    // --- Auto-dismiss pause / resume ---

    #[test]
    fn pause_auto_dismiss_removes_overlay_from_deadline_set() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show_for(
            OverlayRequest::new(
                fake_id(10),
                fake_id(1),
                OverlayPlacement::Centered,
                DismissBehavior::Manual,
            ),
            Duration::from_secs(10),
        );
        assert!(mgr.next_auto_dismiss_deadline().is_some());
        assert!(!mgr.is_auto_dismiss_paused(id));

        mgr.pause_auto_dismiss(id);
        assert!(mgr.is_auto_dismiss_paused(id));
        assert!(
            mgr.next_auto_dismiss_deadline().is_none(),
            "paused overlay must drop out of the deadline-min query"
        );

        mgr.resume_auto_dismiss(id);
        assert!(!mgr.is_auto_dismiss_paused(id));
        assert!(mgr.next_auto_dismiss_deadline().is_some());
    }

    #[test]
    fn pause_then_resume_restores_remaining_time() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show_for(
            OverlayRequest::new(
                fake_id(11),
                fake_id(1),
                OverlayPlacement::Centered,
                DismissBehavior::Manual,
            ),
            Duration::from_secs(10),
        );

        mgr.pause_auto_dismiss(id);
        // Sleep equivalent: rely on the fact pausing right after show
        // captures ~10s remaining (elapsed is ~0).
        let overlay = mgr.stack.iter().find(|o| o.id == id).unwrap();
        let remaining = overlay.paused_remaining.unwrap();
        assert!(
            remaining >= Duration::from_secs(9),
            "remaining should be near the original 10s, got {remaining:?}"
        );
        assert!(remaining <= Duration::from_secs(10));

        mgr.resume_auto_dismiss(id);
        let overlay = mgr.stack.iter().find(|o| o.id == id).unwrap();
        // After resume, auto_dismiss_after equals the previously-stashed
        // remaining, and shown_at_real has been refreshed so the new
        // deadline starts from "now + remaining".
        assert_eq!(overlay.auto_dismiss_after, Some(remaining));
        assert!(overlay.paused_remaining.is_none());
    }

    #[test]
    fn pause_is_idempotent() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show_for(
            OverlayRequest::new(
                fake_id(12),
                fake_id(1),
                OverlayPlacement::Centered,
                DismissBehavior::Manual,
            ),
            Duration::from_secs(10),
        );
        mgr.pause_auto_dismiss(id);
        let first_remaining = mgr.stack[0].paused_remaining;
        mgr.pause_auto_dismiss(id); // second pause must not overwrite
        let second_remaining = mgr.stack[0].paused_remaining;
        assert_eq!(
            first_remaining, second_remaining,
            "double-pause must preserve the original stashed remaining"
        );
    }

    #[test]
    fn resume_on_unpaused_is_noop() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show_for(
            OverlayRequest::new(
                fake_id(13),
                fake_id(1),
                OverlayPlacement::Centered,
                DismissBehavior::Manual,
            ),
            Duration::from_secs(10),
        );
        let before = mgr.stack[0].auto_dismiss_after;
        mgr.resume_auto_dismiss(id); // never paused
        let after = mgr.stack[0].auto_dismiss_after;
        assert_eq!(before, after);
    }

    #[test]
    fn pause_on_persistent_overlay_is_noop() {
        let mut mgr = OverlayManager::new();
        let id = mgr.show(OverlayRequest::new(
            fake_id(14),
            fake_id(1),
            OverlayPlacement::Centered,
            DismissBehavior::Manual,
        ));
        // No auto_dismiss_after — pause should be a no-op.
        mgr.pause_auto_dismiss(id);
        assert!(!mgr.is_auto_dismiss_paused(id));
        assert!(mgr.stack[0].paused_remaining.is_none());
    }

    #[test]
    fn pause_on_unknown_id_is_noop() {
        let mut mgr = OverlayManager::new();
        mgr.pause_auto_dismiss(OverlayId::new(9999)); // must not panic
        mgr.resume_auto_dismiss(OverlayId::new(9999));
    }

    // -----------------------------------------------------------------
    // Bands
    // -----------------------------------------------------------------

    fn show_at(
        mgr: &mut OverlayManager,
        content: u64,
        bounds: Rect,
        dismiss: DismissBehavior,
        band: OverlayBand,
    ) -> OverlayId {
        let id = mgr.show_in_band(
            OverlayRequest::new(
                fake_id(content),
                fake_id(content + 100),
                OverlayPlacement::Centered,
                dismiss,
            ),
            band,
        );
        if let Some(overlay) = mgr.stack.iter_mut().find(|o| o.id == id) {
            overlay.bounds = bounds;
        }
        id
    }

    /// A selection handle raised while a menu is open must go **under** the
    /// menu. Show order alone would put it on top, and then the menu would be
    /// unreachable behind a 44 dp handle.
    #[test]
    fn a_text_affordance_is_inserted_below_the_menus_already_open() {
        let mut mgr = OverlayManager::new();
        let menu = show_at(
            &mut mgr,
            1,
            Rect::new(0.0, 0.0, 100.0, 100.0),
            DismissBehavior::ClickOutside,
            OverlayBand::Standard,
        );
        let handle = show_at(
            &mut mgr,
            2,
            Rect::new(200.0, 200.0, 44.0, 44.0),
            DismissBehavior::Manual,
            OverlayBand::TextAffordance,
        );
        let order: Vec<OverlayId> = mgr.stack.iter().map(|o| o.id).collect();
        assert_eq!(order, vec![handle, menu], "the handle sits under the menu");
        assert_eq!(mgr.topmost().map(|o| o.id), Some(menu));
    }

    /// Every tap that moves a caret is "outside" a selection handle, so
    /// outside-press dismissal would retire the handles on the first tap that
    /// used them. The band is exempt; the menu above it still closes.
    #[test]
    fn an_outside_press_leaves_the_text_affordance_band_alone() {
        let mut mgr = OverlayManager::new();
        let handle = show_at(
            &mut mgr,
            2,
            Rect::new(200.0, 200.0, 44.0, 44.0),
            DismissBehavior::ClickOutside,
            OverlayBand::TextAffordance,
        );
        let menu = show_at(
            &mut mgr,
            1,
            Rect::new(0.0, 0.0, 100.0, 100.0),
            DismissBehavior::ClickOutside,
            OverlayBand::Standard,
        );
        let (dismissed, _, _) = mgr.handle_click_outside(Point::new(600.0, 600.0));
        assert_eq!(dismissed, vec![fake_id(1)], "only the menu closes");
        assert!(mgr.overlay(handle).is_some());
        assert!(mgr.overlay(menu).is_none());
    }

    // -----------------------------------------------------------------
    // Release dismissal
    // -----------------------------------------------------------------

    fn contact(n: u64) -> PointerId {
        crate::pointer::PointerIdAllocator::global()
            .begin(crate::pointer::BackendDeviceKey::new(0x0FA1), n)
    }

    fn with_one_menu() -> (OverlayManager, OverlayId) {
        let mut mgr = OverlayManager::new();
        let menu = show_at(
            &mut mgr,
            1,
            Rect::new(100.0, 100.0, 200.0, 200.0),
            DismissBehavior::ClickOutside,
            OverlayBand::Standard,
        );
        (mgr, menu)
    }

    #[test]
    fn an_armed_press_suppresses_the_down_and_dismisses_on_the_up() {
        let (mut mgr, menu) = with_one_menu();
        let finger = contact(1);
        let arm = mgr.arm_dismiss(finger, Point::new(500.0, 500.0), &[]);
        assert!(arm.will_dismiss && arm.suppress_beneath);
        assert!(mgr.overlay(menu).is_some(), "nothing closes on the press");

        let (dismissed, _, anchors) = mgr.commit_dismiss(finger, Point::new(500.0, 500.0));
        assert_eq!(dismissed, vec![fake_id(1)]);
        assert_eq!(anchors, vec![fake_id(101)]);
        assert!(!mgr.has_armed_dismiss(finger));
    }

    /// A press that would close nothing must not suppress itself — otherwise
    /// every touch anywhere in a window with no overlay open would be eaten.
    #[test]
    fn a_press_with_nothing_to_close_arms_nothing() {
        let mut mgr = OverlayManager::new();
        let finger = contact(2);
        assert_eq!(
            mgr.arm_dismiss(finger, Point::new(10.0, 10.0), &[]),
            DismissArm::default()
        );
        assert!(!mgr.has_armed_dismiss(finger));
    }

    #[test]
    fn a_cancelled_press_aborts_the_arm() {
        let (mut mgr, menu) = with_one_menu();
        let finger = contact(3);
        assert!(
            mgr.arm_dismiss(finger, Point::new(500.0, 500.0), &[])
                .will_dismiss
        );
        assert!(mgr.abort_dismiss(finger));
        assert!(mgr.overlay(menu).is_some(), "the menu survives a cancel");
        assert!(!mgr.abort_dismiss(finger), "aborting twice is a no-op");

        // And a commit after the abort finds nothing to do.
        let (dismissed, restore, anchors) = mgr.commit_dismiss(finger, Point::new(500.0, 500.0));
        assert!(dismissed.is_empty() && restore.is_none() && anchors.is_empty());
    }

    /// Land beside the menu, drag onto it, lift there: the finger changed its
    /// mind, and the menu it is now touching is not the thing it closes.
    #[test]
    fn a_press_that_slides_onto_the_menu_dismisses_nothing() {
        let (mut mgr, menu) = with_one_menu();
        let finger = contact(4);
        assert!(
            mgr.arm_dismiss(finger, Point::new(500.0, 500.0), &[])
                .will_dismiss
        );
        let (dismissed, _, anchors) = mgr.commit_dismiss(finger, Point::new(150.0, 150.0));
        assert!(dismissed.is_empty(), "the release landed inside the menu");
        assert!(anchors.is_empty());
        assert!(mgr.overlay(menu).is_some());
    }

    /// A second finger landing on the page while the first works inside the
    /// menu is not a dismissal gesture.
    #[test]
    fn a_second_contact_cannot_dismiss_what_the_first_is_manipulating() {
        let (mut mgr, menu) = with_one_menu();
        let second = contact(5);
        let busy = [Point::new(150.0, 150.0)]; // the first finger, inside the menu
        assert_eq!(
            mgr.arm_dismiss(second, Point::new(500.0, 500.0), &busy),
            DismissArm::default()
        );
        assert!(mgr.overlay(menu).is_some());

        // With the first finger lifted the same press closes it.
        assert!(
            mgr.arm_dismiss(second, Point::new(500.0, 500.0), &[])
                .will_dismiss
        );
        let (dismissed, _, _) = mgr.commit_dismiss(second, Point::new(500.0, 500.0));
        assert_eq!(dismissed, vec![fake_id(1)]);
    }

    /// Two contacts, each with its own arm: neither may commit the other's.
    #[test]
    fn arms_are_tracked_per_pointer() {
        let mut mgr = OverlayManager::new();
        let lower = show_at(
            &mut mgr,
            1,
            Rect::new(0.0, 0.0, 100.0, 100.0),
            DismissBehavior::ClickOutside,
            OverlayBand::Standard,
        );
        let upper = show_at(
            &mut mgr,
            2,
            Rect::new(400.0, 0.0, 100.0, 100.0),
            DismissBehavior::ClickOutside,
            OverlayBand::Standard,
        );
        let a = contact(6);
        let b = contact(7);
        // `a` lands inside the lower overlay: only the upper one is above it.
        assert!(mgr.arm_dismiss(a, Point::new(50.0, 50.0), &[]).will_dismiss);
        // `b` lands on the background: both are above it.
        assert!(
            mgr.arm_dismiss(b, Point::new(700.0, 700.0), &[])
                .will_dismiss
        );
        assert_eq!(mgr.armed_pointers().len(), 2);

        let (dismissed, _, _) = mgr.commit_dismiss(a, Point::new(50.0, 50.0));
        assert_eq!(dismissed, vec![fake_id(2)], "only the overlay above `a`");
        assert!(mgr.overlay(lower).is_some());
        assert!(mgr.overlay(upper).is_none());

        // `b`'s arm still names the upper overlay, which is gone; committing it
        // closes what is left and does not panic on the absent id.
        let (dismissed, _, _) = mgr.commit_dismiss(b, Point::new(700.0, 700.0));
        assert_eq!(dismissed, vec![fake_id(1)]);
        assert!(mgr.armed_pointers().is_empty());
    }

    /// Re-arming the same pointer replaces its arm rather than stacking one.
    #[test]
    fn a_second_arm_for_one_pointer_replaces_the_first() {
        let (mut mgr, _menu) = with_one_menu();
        let finger = contact(8);
        assert!(
            mgr.arm_dismiss(finger, Point::new(500.0, 500.0), &[])
                .will_dismiss
        );
        assert!(
            mgr.arm_dismiss(finger, Point::new(600.0, 600.0), &[])
                .will_dismiss
        );
        assert_eq!(mgr.armed_pointers(), vec![finger]);
    }
}