repose_core/

runtime.rs

use std::any::Any;
use std::cell::RefCell;
use std::collections::HashSet;
use std::panic::Location;
use std::rc::Rc;
use std::sync::atomic::{AtomicU64, Ordering};

use rustc_hash::FxHashMap;

use crate::scope::Scope;
use crate::{CursorIcon, Rect, Scene, View, input::PhysicalKey, semantics::Role};

thread_local! {
    pub static COMPOSER: RefCell<Composer> = RefCell::new(Composer::default());
    static ROOT_SCOPE: RefCell<Option<Scope>> = const { RefCell::new(None) };

    /// Programmatic focus requests queued by `FocusRequester`. A queue (not a
    /// single slot) so multiple requests in one frame are honored in order
    /// instead of last-wins. `CLEAR_FOCUS_MARKER` entries clear focus.
    static FOCUS_REQUESTS: RefCell<std::collections::VecDeque<u64>> =
        const { RefCell::new(std::collections::VecDeque::new()) };
}

/// Sentinel value meaning "clear focus entirely".
pub const CLEAR_FOCUS_MARKER: u64 = u64::MAX;

/// Process-wide unique id for namespacing `remember_with_key` slots
/// (dialogs, menus, sheets, tooltips, ...).
static COMPONENT_ID: AtomicU64 = AtomicU64::new(1);

/// Returns a fresh unique component id. See [`COMPONENT_ID`].
pub fn unique_component_id() -> u64 {
    COMPONENT_ID.fetch_add(1, Ordering::Relaxed)
}

pub fn take_focus_request() -> Option<u64> {
    FOCUS_REQUESTS.with(|r| r.borrow_mut().pop_front())
}

/// Drain all queued focus requests in FIFO order.
pub fn drain_focus_requests() -> Vec<u64> {
    FOCUS_REQUESTS.with(|r| r.borrow_mut().drain(..).collect())
}

/// A handle that can programmatically request focus for a widget.
///
/// Similar to Compose's `FocusRequester`. Create one via `remember(FocusRequester::new)`,
/// attach it via `.focus_requester(...)` on a modifier, and call `request_focus()` to
/// move keyboard focus to the associated widget on the next frame.
#[derive(Clone)]
pub struct FocusRequester {
    /// Target view ID, set during layout/paint by the modifier system.
    pub target: Rc<RefCell<Option<u64>>>,
}

impl FocusRequester {
    pub fn new() -> Self {
        Self {
            target: Rc::new(RefCell::new(None)),
        }
    }

    /// Request focus for the associated widget on the next frame.
    /// Queued; unlike the old single-slot behavior, multiple requests in one
    /// frame are all honored in order. If the target is not laid out yet the
    /// request is dropped (target assigned during layout/paint).
    pub fn request_focus(&self) {
        if let Some(id) = *self.target.borrow() {
            FOCUS_REQUESTS.with(|r| r.borrow_mut().push_back(id));
        }
    }

    /// Free/clear focus from the associated widget on the next frame.
    /// If the associated widget currently has focus, focus is cleared entirely.
    /// Corresponds to Compose's `freeFocus()`.
    pub fn free_focus(&self) {
        FOCUS_REQUESTS.with(|r| r.borrow_mut().push_back(CLEAR_FOCUS_MARKER));
    }

    /// Request focus for the associated widget on the next frame,
    /// bypassing some focusability checks. Corresponds to Compose's
    /// `captureFocus()`, which is typically used internally by the focus system.
    /// In repose this is an alias for `request_focus()`.
    pub fn capture_focus(&self) {
        self.request_focus();
    }
}

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

/// Direction for focus movement.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FocusDirection {
    Next,
    Previous,
    Left,
    Right,
    Up,
    Down,
}

/// A manager for programmatic focus navigation.
///
/// Wraps a `&Scheduler` and provides methods to move focus.
/// Can also be used standalone with a focus chain and focused element.
#[derive(Clone)]
pub struct FocusManager {
    /// The ordered list of focusable element IDs.
    pub chain: Vec<u64>,
    /// The currently focused element (if any).
    pub focused: Option<u64>,
    /// Hit regions for focus group lookups.
    pub hit_regions: Vec<HitRegion>,
}

impl FocusManager {
    pub fn new(chain: Vec<u64>, focused: Option<u64>) -> Self {
        Self {
            chain,
            focused,
            hit_regions: Vec::new(),
        }
    }

    /// Move focus in the given direction.
    /// Returns the new focused element ID, or `None` if no movement is possible.
    pub fn move_focus(&mut self, dir: FocusDirection) -> Option<u64> {
        match dir {
            FocusDirection::Next | FocusDirection::Previous => {
                self.move_tab(dir == FocusDirection::Previous)
            }
            _ => None, // use move_focus_spatial when hit regions are available
        }
    }

    /// Clears focus entirely on the next frame.
    /// Corresponds to Compose's `FocusManager.clearFocus()`.
    /// The `force` parameter is accepted for API compatibility. In repose
    /// focus is always cleared immediately (no keep-focus mechanism).
    pub fn clear_focus(&self, _force: bool) {
        FOCUS_REQUESTS.with(|r| r.borrow_mut().push_back(CLEAR_FOCUS_MARKER));
    }

    /// Spatial focus navigation: find the closest focusable element in a given
    /// direction using bounding rect geometry.
    pub fn move_focus_spatial(
        &mut self,
        dir: FocusDirection,
        hit_regions: &[HitRegion],
    ) -> Option<u64> {
        let next = spatial_focus_next(&self.chain, hit_regions, self.focused, dir)?;
        self.focused = Some(next);
        Some(next)
    }

    /// Tab forward or backward in the focus chain.
    /// When the current focus belongs to a focus group, navigation is restricted
    /// to elements within that group.
    pub fn move_tab(&mut self, reverse: bool) -> Option<u64> {
        if self.chain.is_empty() {
            return None;
        }
        let next = if let Some(sub_chain) =
            focus_group_chain(&self.chain, &self.hit_regions, self.focused)
        {
            if sub_chain.is_empty() {
                return None;
            }
            if let Some(cur) = self.focused {
                if let Some(idx) = sub_chain.iter().position(|&id| id == cur) {
                    if reverse {
                        if idx == 0 {
                            sub_chain[sub_chain.len() - 1]
                        } else {
                            sub_chain[idx - 1]
                        }
                    } else {
                        sub_chain[(idx + 1) % sub_chain.len()]
                    }
                } else {
                    sub_chain[0]
                }
            } else if reverse {
                sub_chain[sub_chain.len() - 1]
            } else {
                sub_chain[0]
            }
        } else {
            if let Some(cur) = self.focused {
                if let Some(idx) = self.chain.iter().position(|&id| id == cur) {
                    if reverse {
                        if idx == 0 {
                            self.chain[self.chain.len() - 1]
                        } else {
                            self.chain[idx - 1]
                        }
                    } else {
                        self.chain[(idx + 1) % self.chain.len()]
                    }
                } else {
                    self.chain[0]
                }
            } else if reverse {
                self.chain[self.chain.len() - 1]
            } else {
                self.chain[0]
            }
        };
        self.focused = Some(next);
        Some(next)
    }

    /// Set target ID on a FocusRequester (called during layout).
    pub fn set_requester_target(requester: &FocusRequester, id: u64) {
        *requester.target.borrow_mut() = Some(id);
    }
}

/// Sub-chain of ids sharing the focused element's focus group.
/// Returns `None` when focus is outside any group (full chain applies).
/// Tab and spatial navigation both scope to this so modals trap focus.
pub fn focus_group_chain(
    chain: &[u64],
    hit_regions: &[HitRegion],
    current: Option<u64>,
) -> Option<Vec<u64>> {
    let cur = current?;
    let group_id = hit_regions.iter().find(|h| h.id == cur)?.focus_group_id?;
    Some(
        chain
            .iter()
            .copied()
            .filter(|&id| {
                id == group_id
                    || hit_regions
                        .iter()
                        .any(|h| h.id == id && h.focus_group_id == Some(group_id))
            })
            .collect(),
    )
}

/// Find the next focusable element in a given spatial direction.
///
/// Uses the bounding rects from `hit_regions` to determine which element is
/// "next" in the given direction from the currently focused element.
pub fn spatial_focus_next(
    chain: &[u64],
    hit_regions: &[HitRegion],
    current: Option<u64>,
    dir: FocusDirection,
) -> Option<u64> {
    if chain.is_empty() {
        return None;
    }

    let current_rect =
        current.and_then(|id| hit_regions.iter().find(|h| h.id == id).map(|h| h.rect));

    // For Next/Previous, use tab-order navigation
    match dir {
        FocusDirection::Next | FocusDirection::Previous => {
            let mut fm = FocusManager {
                chain: chain.to_vec(),
                focused: current,
                hit_regions: hit_regions.to_vec(),
            };
            return fm.move_tab(dir == FocusDirection::Previous);
        }
        _ => {}
    }

    let (cx, cy) = match current_rect {
        Some(r) => (r.x + r.w / 2.0, r.y + r.h / 2.0),
        None => {
            // For games: Tab/Shift-Tab should establish initial focus, not arrows.
            return None;
        }
    };

    let mut best: Option<(u64, f32)> = None;

    // Modal trap: arrows stay inside the focused element's focus group.
    let scoped: Vec<u64>;
    let chain: &[u64] = match focus_group_chain(chain, hit_regions, current) {
        Some(sub) => {
            scoped = sub;
            &scoped
        }
        None => chain,
    };

    for &id in chain {
        if Some(id) == current {
            continue;
        }
        let Some(hr) = hit_regions.iter().find(|h| h.id == id) else {
            continue;
        };
        let r = hr.rect;
        let other_cx = r.x + r.w / 2.0;
        let other_cy = r.y + r.h / 2.0;
        let dx = other_cx - cx;
        let dy = other_cy - cy;

        let in_direction = match dir {
            FocusDirection::Left => dx < 0.0 && dy.abs() <= r.h.max(1.0),
            FocusDirection::Right => dx > 0.0 && dy.abs() <= r.h.max(1.0),
            FocusDirection::Up => dy < 0.0 && dx.abs() <= r.w.max(1.0),
            FocusDirection::Down => dy > 0.0 && dx.abs() <= r.w.max(1.0),
            _ => false,
        };

        if !in_direction {
            continue;
        }

        let dist = dx * dx + dy * dy;
        let weight = dist / (r.w * r.h + 1.0).max(1.0);

        match best {
            Some((_, best_weight)) if weight >= best_weight => {}
            _ => best = Some((id, weight)),
        }
    }

    best.map(|(id, _)| id)
}

#[derive(Default)]
pub struct Composer {
    pub slots: Vec<Box<dyn Any>>,
    pub slot_callers: Vec<&'static Location<'static>>,
    pub cursor: usize,
    pub keyed_slots: FxHashMap<String, Box<dyn Any>>,
    pub keyed_owner: FxHashMap<String, String>,
    pub live_keyed_owners: rustc_hash::FxHashSet<String>,
    pub scope_caches: FxHashMap<String, crate::scope_cache::ScopeCache>,
    pub live_scope_keys: rustc_hash::FxHashSet<String>,
}

pub struct ComposeGuard {
    scope: Scope,
}

pub(crate) fn current_scope_key_for_remember() -> Option<String> {
    crate::scope_cache::current_scope_key()
}

impl ComposeGuard {
    pub fn begin() -> Self {
        COMPOSER.with(|c| {
            let mut c = c.borrow_mut();
            c.cursor = 0;
            c.live_scope_keys.clear();
            c.live_keyed_owners.clear();
            c.live_scope_keys.insert(String::new());
            c.live_keyed_owners.insert(String::new());
        });

        let scope = ROOT_SCOPE.with(|rs| {
            if let Some(existing) = rs.borrow().clone() {
                existing
            } else {
                let s = Scope::new();
                *rs.borrow_mut() = Some(s.clone());
                s
            }
        });

        ComposeGuard { scope }
    }

    pub fn scope(&self) -> &Scope {
        &self.scope
    }
}

impl Drop for ComposeGuard {
    fn drop(&mut self) {
        COMPOSER.with(|c| {
            let mut c = c.borrow_mut();
            let n = c.cursor;
            if c.slots.len() > n {
                c.slots.truncate(n);
            }
            if c.slot_callers.len() > n {
                c.slot_callers.truncate(n);
            }
        });
        crate::scope_cache::gc_dead_scopes();
    }
}

/// Dispose the root composition scope and clear all composer caches.
///
/// Call once on process exit (desktop `exiting`, tests). After this the next
/// `ComposeGuard::begin` starts from a fresh root scope.
pub fn shutdown_composition() {
    ROOT_SCOPE.with(|rs| {
        if let Some(scope) = rs.borrow_mut().take() {
            scope.dispose();
        }
    });
    COMPOSER.with(|c| {
        let mut c = c.borrow_mut();
        c.slots.clear();
        c.slot_callers.clear();
        c.keyed_slots.clear();
        c.keyed_owner.clear();
        c.live_keyed_owners.clear();
        c.scope_caches.clear();
        c.live_scope_keys.clear();
        c.cursor = 0;
    });
    crate::scope_cache::clear_all_scope_deps();
}

/// Slot-based remember (sequential composition only).
/// This prevents state aliasing when the composition tree structure changes between frames
#[track_caller]
pub fn remember<T: 'static>(init: impl FnOnce() -> T) -> Rc<T> {
    // Capture BEFORE any closure -> Location::caller() returns the correct
    // track_caller location only at the function's top level, not inside closures.
    let caller = Location::caller();
    COMPOSER.with(|c| {
        let mut c = c.borrow_mut();
        let cursor = c.cursor;
        c.cursor += 1;

        if cursor >= c.slots.len() {
            let rc: Rc<T> = Rc::new(init());
            c.slots.push(Box::new(rc.clone()));
            c.slot_callers.push(caller);
            return rc;
        }

        let stored_caller = c.slot_callers.get(cursor).copied();
        if stored_caller != Some(caller) {
            let rc: Rc<T> = Rc::new(init());
            c.slots[cursor] = Box::new(rc.clone());
            if cursor < c.slot_callers.len() {
                c.slot_callers[cursor] = caller;
            } else {
                c.slot_callers.push(caller);
            }
            return rc;
        }

        if let Some(rc) = c.slots[cursor].downcast_ref::<Rc<T>>() {
            rc.clone()
        } else {
            log::warn!(
                "remember: slot {} type changed {}. \
                 Use remember_with_key(key, || ...) for conditional branches.",
                cursor,
                std::any::type_name::<T>(),
            );
            let rc: Rc<T> = Rc::new(init());
            c.slots[cursor] = Box::new(rc.clone());
            rc
        }
    })
}

/// Key-based remember.
pub fn remember_with_key<T: 'static>(key: impl Into<String>, init: impl FnOnce() -> T) -> Rc<T> {
    let owner = current_scope_key_for_remember().unwrap_or_default();
    COMPOSER.with(|c| {
        let mut c = c.borrow_mut();
        let key = key.into();

        if let Some(existing) = c.keyed_slots.get(&key) {
            if let Some(rc) = existing.downcast_ref::<Rc<T>>() {
                let rc = rc.clone();
                c.keyed_owner.insert(key.clone(), owner.clone());
                c.live_keyed_owners.insert(owner);
                return rc;
            } else {
                log::warn!(
                    "remember_with_key: key '{}' reused with a different type; replacing.",
                    key
                );
            }
        }

        if cfg!(debug_assertions) && c.keyed_slots.len() > 10_000 {
            log::warn!(
                "remember_with_key: more than 10k keys stored; \
                are you generating unbounded dynamic keys (e.g., using timestamps)?"
            );
        }

        let rc: Rc<T> = Rc::new(init());
        c.keyed_slots.insert(key.clone(), Box::new(rc.clone()));
        c.keyed_owner.insert(key, owner.clone());
        c.live_keyed_owners.insert(owner);
        rc
    })
}

/// Raw slot state (`Rc<RefCell<T>>`). Writes via `borrow_mut()` don't request a
/// frame - prefer [`remember_mutable`] if a write must always recompose.
#[track_caller]
pub fn remember_state<T: 'static>(init: impl FnOnce() -> T) -> Rc<RefCell<T>> {
    remember(|| RefCell::new(init()))
}

/// Key-based variant of [`remember_state`]. Same no-frame-on-write caveat.
pub fn remember_state_with_key<T: 'static>(
    key: impl Into<String>,
    init: impl FnOnce() -> T,
) -> Rc<RefCell<T>> {
    remember_with_key(key, || RefCell::new(init()))
}

/// Frame - output of composition for a tick: scene + input/semantics.
#[derive(Clone)]
pub struct Frame {
    pub scene: Scene,
    pub hit_regions: Vec<HitRegion>,
    pub semantics_nodes: Vec<SemNode>,
    pub focus_chain: Vec<u64>,
}

/// Hit-test region in physical pixels (`rect` carries px magnitudes,
/// like Compose `Rect`).
#[derive(Clone, Default)]
pub struct HitRegion {
    pub id: u64,
    pub rect: Rect,
    /// Tree depth: 0 = root, higher = deeper child. Used for three-pass
    /// pointer dispatch to determine ancestor/descendant ordering.
    pub depth: u32,
    pub parent: Option<u64>,
    pub on_click: Option<Rc<dyn Fn()>>,
    pub on_double_click: Option<Rc<dyn Fn()>>,
    pub on_long_click: Option<Rc<dyn Fn()>>,
    pub on_scroll: Option<Rc<dyn Fn(crate::Vec2) -> crate::Vec2>>,
    pub focusable: bool,
    pub on_pointer_down: Option<Rc<dyn Fn(crate::input::PointerEvent)>>,
    pub on_pointer_move: Option<Rc<dyn Fn(crate::input::PointerEvent)>>,
    pub on_pointer_up: Option<Rc<dyn Fn(crate::input::PointerEvent)>>,
    pub on_pointer_cancel: Option<Rc<dyn Fn(crate::input::PointerEvent)>>,
    pub on_pointer_enter: Option<Rc<dyn Fn(crate::input::PointerEvent)>>,
    pub on_pointer_leave: Option<Rc<dyn Fn(crate::input::PointerEvent)>>,
    pub z_index: f32,
    pub disabled: bool,
    pub on_text_change: Option<Rc<dyn Fn(String)>>,
    pub on_text_submit: Option<Rc<dyn Fn(String)>>,
    /// If this hit region belongs to a TextField, this persistent key is used
    /// for looking up platform-managed TextFieldState. Falls back to `id` if None.
    pub tf_state_key: Option<u64>,

    /// True if this hit region corresponds to a multiline text input (TextArea).
    pub tf_multiline: bool,

    /// Unclipped top-left of the TextField *content* box (padding-inset).
    /// Used for pointer->grapheme mapping so parent scroll clipping of `rect`
    /// does not shift selection into the top of the content.
    /// `None` for non-textfields.
    pub tf_content_origin: Option<(f32, f32)>,

    /// When false, the field rejects edits and is not focusable
    pub tf_enabled: bool,

    /// When true, selection/focus/copy are allowed but mutations are rejected
    pub tf_read_only: bool,

    /// Controlled text snapshot for this field (last compose).
    pub tf_value: String,

    /// Font size for this text field in [`Sp`](crate::units::Sp)
    /// (for hit-test / caret mapping). `Sp::ZERO` means use `TF_FONT_SP` default.
    pub tf_font_size: crate::units::Sp,

    // internal
    pub on_drag_start: Option<Rc<dyn Fn(crate::dnd::DragStart) -> Option<crate::dnd::DragPayload>>>,
    pub on_drag_end: Option<Rc<dyn Fn(crate::dnd::DragEnd)>>,
    pub on_drag_enter: Option<Rc<dyn Fn(crate::dnd::DragOver)>>,
    pub on_drag_over: Option<Rc<dyn Fn(crate::dnd::DragOver)>>,
    pub on_drag_leave: Option<Rc<dyn Fn(crate::dnd::DragOver)>>,
    pub on_drop: Option<Rc<dyn Fn(crate::dnd::DropEvent) -> bool>>,
    /// Copied onto the drag session when a drag starts from this region.
    pub drag_preview: Option<crate::dnd::DragPreview>,

    pub on_action: Option<Rc<dyn Fn(crate::shortcuts::Action) -> bool>>,

    /// Called when a key event is received while this element is focused.
    /// Return `true` to consume the event.
    pub on_key_event: Option<Rc<dyn Fn(crate::input::KeyEvent) -> bool>>,
    /// Called before `on_key_event`. Return `true` to consume before normal dispatch.
    pub on_preview_key_event: Option<Rc<dyn Fn(crate::input::KeyEvent) -> bool>>,

    /// Cursor hint for desktop/web.
    pub cursor: Option<crate::CursorIcon>,

    /// If `Some(group_id)`, this hit region belongs to a focus group with the
    /// given id. Tab navigation will cycle within the group instead of moving
    /// to elements outside it. Set automatically by the layout engine when the
    /// element is a descendant of a node with `focus_group: true`.
    pub focus_group_id: Option<u64>,

    /// IME keyboard hints, populated for text-field hit regions so the
    /// platform runner can configure the OS keyboard / IME on focus.
    pub keyboard_type: crate::text::KeyboardType,
    pub capitalization: crate::text::KeyboardCapitalization,
    pub ime_action: crate::text::ImeAction,
    /// Whether auto-correct is enabled. `None` = follow platform default;
    /// password keyboards always resolve to `false` in the layout engine.
    pub auto_correct: Option<bool>,

    /// Shared interaction source auto-wired by the layout engine
    /// (press/hover/focus/drag). Used by keyboard activation and focus
    /// transitions so they stay in parity with pointer input.
    /// `None` when the component does not need one (no indication/state colors).
    pub interaction_source: Option<crate::modifier::InteractionSource>,
}

impl HitRegion {
    /// Seed a HitRegion with all the modifier's event handlers + dnd + cursor.
    /// Call‑sites should only override the fields that differ (on_click, focusable, etc.)
    /// via struct‑update syntax: `HitRegion { focusable: true, ..from_modifier(..) }`.
    pub fn from_modifier(id: u64, rect: Rect, m: &crate::modifier::Modifier) -> Self {
        Self {
            id,
            rect,
            z_index: m.z_index,
            on_click: m.on_click.clone(),
            on_double_click: m.on_double_click.clone(),
            on_long_click: m.on_long_click.clone(),
            on_pointer_down: m.on_pointer_down.clone(),
            on_pointer_move: m.on_pointer_move.clone(),
            on_pointer_up: m.on_pointer_up.clone(),
            on_pointer_cancel: m.on_pointer_cancel.clone(),
            on_pointer_enter: m.on_pointer_enter.clone(),
            on_pointer_leave: m.on_pointer_leave.clone(),
            on_action: m.on_action.clone(),
            on_key_event: m.on_key_event.clone(),
            on_preview_key_event: m.on_preview_key_event.clone(),
            cursor: m.cursor.clone(),
            on_drag_start: m.on_drag_start.clone(),
            on_drag_end: m.on_drag_end.clone(),
            on_drag_enter: m.on_drag_enter.clone(),
            on_drag_over: m.on_drag_over.clone(),
            on_drag_leave: m.on_drag_leave.clone(),
            on_scroll: m.on_scroll.clone(),
            on_drop: m.on_drop.clone(),
            drag_preview: m.drag_preview.clone(),
            disabled: m.disabled,
            tf_enabled: true,
            tf_read_only: false,
            ..Default::default()
        }
    }
}

/// Flattened semantics node produced by `layout_and_paint`.
///
/// This is the source of truth for accessibility backends: it contains the
/// resolved screen rect, role, label, and focus/enabled state.
///
/// The platform runner should convert this into OS‑specific accessibility trees (when implemented)
/// (AT‑SPI on Linux, TalkBack on Android, etc.).
#[derive(Clone)]
pub struct SemNode {
    /// Stable id, shared with the associated `HitRegion` / `ViewId`.
    pub id: u64,

    /// `None` means direct child of the window root.
    pub parent: Option<u64>,

    pub role: Role,
    pub label: Option<String>,
    pub rect: Rect,
    pub focused: bool,
    pub enabled: bool,
    /// Marks this node as a collection of selectable children (e.g., Tabs).
    pub selectable_group: bool,
    pub checked: Option<bool>,
    pub selected: Option<bool>,
    pub value: Option<String>,
}

impl Default for SemNode {
    fn default() -> Self {
        Self {
            id: 0,
            parent: None,
            role: Role::default(),
            label: None,
            rect: Rect::default(),
            focused: false,
            enabled: true,
            selectable_group: false,
            checked: None,
            selected: None,
            value: None,
        }
    }
}

pub struct Scheduler {
    next_id: u64,
    /// Per-scope unique IDs, assigned lazily when a scope first executes.
    /// Keyed by the scope key string from `scope!`.
    scope_key_to_id: FxHashMap<String, u32>,
    next_scope_id: u32,
    /// Stack of active scope keys. `id()` allocates from the innermost scope
    /// so nested `scope!` bodies get stable packed IDs and the outer scope
    /// resumes correctly after the inner exits (previously `exit_scope` reset
    /// to `None`, leaking outer IDs into the global sequence).
    current_scope: Vec<String>,
    /// Per-scope local ID counters. Reset to 0 when a scope re-executes.
    scope_local_counters: FxHashMap<String, u32>,
    pub focused: Option<u64>,
    pub size: (u32, u32),
    /// Last known mouse pointer position in physical px, updated on
    /// mouse move/press/release without passing through focus dispatch.
    pub pointer_pos_px: Option<(f32, f32)>,
    /// Polled physical keys currently down, layout-independent
    /// positions (see [`PhysicalKey`]). The platform runner maintains
    /// this from raw `KeyboardInput` events without passing through
    /// focus dispatch; games reconcile their event-staged held sets
    /// against it every frame (GML `keyboard_check` parity). Cleared
    /// on window focus loss (no key-ups arrive across an alt-tab).
    pub held_keys: HashSet<PhysicalKey>,
    /// Window focus as of the last platform event. `false` drops every
    /// held key on the game side.
    pub window_focused: bool,
    /// Live touch contacts in physical px: `(touch id, x, y)` per
    /// finger currently down. Written by the platform runners from
    /// raw `WindowEvent::Touch` (Started/Moved/Ended-Cancelled), read
    /// by games through `feed_polled`-style staging snapshots
    /// (GML `device_mouse_x_to_gui(i)` parity: stable per-finger slot
    /// ids, positions sampled every tick while held).
    pub touch_points: Vec<(u64, f32, f32)>,
    /// Polled mouse-button levels, same source as `held_keys`
    /// (GML `mouse_check_button` parity; repairs a missed button-up
    /// when the release lands outside the window).
    pub mouse_primary: bool,
    pub mouse_secondary: bool,
    pub mouse_middle: bool,
    /// App-requested cursor override. When `Some`, the platform
    /// applies it instead of the hover-derived icon: games hide the
    /// OS pointer here (`CursorIcon::Hidden`) while drawing their own
    /// crosshair, GML `window_set_cursor(cr_none)` parity. `None`
    /// restores hover behavior. Set during composition (any view can
    /// write it; last write per frame wins), consumed by the runner
    /// after `frame()`.
    pub cursor_override: Option<CursorIcon>,
}

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

impl Scheduler {
    pub fn new() -> Self {
        Self {
            next_id: 1,
            scope_key_to_id: FxHashMap::default(),
            next_scope_id: 1,
            current_scope: Vec::new(),
            scope_local_counters: FxHashMap::default(),
            focused: None,
            size: (1280, 800),
            pointer_pos_px: None,
            held_keys: HashSet::new(),
            window_focused: true,
            touch_points: Vec::new(),
            mouse_primary: false,
            mouse_secondary: false,
            mouse_middle: false,
            cursor_override: None,
        }
    }

    /// Enter a named scope. Subsequent `id()` calls within this scope
    /// will allocate from the scope's local counter, producing packed
    /// `(scope_id << 32) | local_id` values that are stable across sibling
    /// recompositions. Nested scopes push; `exit_scope` pops.
    pub fn enter_scope(&mut self, key: &str) {
        if !self.current_scope.iter().any(|k| k == key) {
            self.scope_local_counters.insert(key.to_string(), 0);
        }
        self.current_scope.push(key.to_string());
        self.get_or_create_scope_id(key);
    }

    /// Exit the innermost scope. No-op if the stack is empty or the top does
    /// not match (defensive: never corrupt an outer scope).
    pub fn exit_scope(&mut self) {
        self.current_scope.pop();
    }

    /// RAII scope entry: pops on drop, so a panicking scope body cannot leave
    /// the scheduler stuck in the wrong scope (which previously leaked outer
    /// IDs into the global sequence).
    pub fn scope_guard<'a>(&'a mut self, key: &str) -> SchedulerScopeGuard<'a> {
        self.enter_scope(key);
        SchedulerScopeGuard { sched: self }
    }

    /// Panic-safe scope entry that does NOT hold a borrow: the guarded body
    /// (including nested `scope!`) can keep using the `Scheduler`. Used by
    /// the `scope!` macro.
    pub fn scope_guard_raw(&mut self, key: &str) -> SchedulerScopeGuardRaw {
        let ptr = self as *mut Scheduler;
        unsafe { SchedulerScopeGuardRaw::enter(ptr, key) }
    }

    fn get_or_create_scope_id(&mut self, key: &str) -> u32 {
        if let Some(&id) = self.scope_key_to_id.get(key) {
            id
        } else {
            let id = self.next_scope_id;
            self.next_scope_id += 1;
            self.scope_key_to_id.insert(key.to_string(), id);
            id
        }
    }

    pub fn id(&mut self) -> u64 {
        if let Some(key) = self.current_scope.last().cloned() {
            let scope_id = self.scope_key_to_id.get(&key).copied().unwrap_or(0);
            let local = self.scope_local_counters.get_mut(&key).unwrap();
            let id = *local;
            *local += 1;
            (scope_id as u64) << 32 | id as u64
        } else {
            // Global sequential ID (for non-scoped views)
            let id = self.next_id;
            self.next_id += 1;
            id
        }
    }

    pub fn id_count(&self) -> u64 {
        self.next_id - 1
    }

    /// True while the named physical key is in the polled snapshot.
    pub fn is_held(&self, key: PhysicalKey) -> bool {
        self.held_keys.contains(&key)
    }

    /// Snapshot the current ID counter (before executing a scope body) so the
    /// delta can be computed after the body returns.
    pub fn snapshot_id(&self) -> u64 {
        self.next_id
    }

    /// Advance the ID counter by `count` without assigning IDs.
    /// Used by the scope! macro to reserve IDs for a cached scope subtree.
    pub fn advance_id(&mut self, count: u32) {
        self.next_id += count as u64;
    }

    /// Number of IDs assigned since `prev_id` (the value returned by
    /// `snapshot_id()` before executing a scope body).
    pub fn ids_used_since(&self, prev_id: u64) -> u32 {
        (self.next_id - prev_id) as u32
    }
}

/// RAII guard from [`Scheduler::scope_guard`]. Pops the scope on drop.
pub struct SchedulerScopeGuard<'a> {
    sched: &'a mut Scheduler,
}

impl Drop for SchedulerScopeGuard<'_> {
    fn drop(&mut self) {
        self.sched.exit_scope();
    }
}

/// Panic-safe scope guard that does NOT hold a borrow across the body.
///
/// The `scope!` macro uses this (not [`SchedulerScopeGuard`]) so the guarded
/// body — including nested `scope!` invocations — can keep using the
/// `Scheduler` normally. At drop time (normal or unwind) no other borrows of
/// the scheduler are live, since the body has ended.
pub struct SchedulerScopeGuardRaw {
    sched: *mut Scheduler,
}

impl SchedulerScopeGuardRaw {
    /// # Safety
    /// `sched` must point to a valid `Scheduler` for the guard's lifetime,
    /// and the scheduler must not be used while the guard is being dropped
    /// (guaranteed when the guard outlives the body it protects).
    pub unsafe fn enter(sched: *mut Scheduler, key: &str) -> Self {
        unsafe {
            (*sched).enter_scope(key);
        }
        Self { sched }
    }
}

impl Drop for SchedulerScopeGuardRaw {
    fn drop(&mut self) {
        unsafe {
            (*self.sched).exit_scope();
        }
    }
}

impl Scheduler {
    pub fn repose<F>(
        &mut self,
        mut build_root: F,
        layout_paint: impl Fn(&View, (u32, u32)) -> (Scene, Vec<HitRegion>, Vec<SemNode>),
    ) -> Frame
    where
        F: FnMut(&mut Scheduler) -> View,
    {
        let guard = ComposeGuard::begin();
        let root = guard.scope.run(|| build_root(self));
        let (scene, hits, sem) = layout_paint(&root, self.size);

        let focus_chain: Vec<u64> = hits.iter().filter(|h| h.focusable).map(|h| h.id).collect();

        Frame {
            scene,
            hit_regions: hits,
            semantics_nodes: sem,
            focus_chain,
        }
    }
}

/// Test helper: full composer reset. Production shutdown should call
/// `shutdown_composition`.
#[cfg(test)]
pub fn clear_composer() {
    shutdown_composition();
}

#[cfg(test)]
mod focus_trap_tests {
    use super::*;

    fn region(id: u64, x: f32, group: Option<u64>) -> HitRegion {
        HitRegion {
            id,
            rect: Rect {
                x,
                y: 0.0,
                w: 10.0,
                h: 10.0,
            },
            focus_group_id: group,
            ..Default::default()
        }
    }

    #[test]
    fn arrows_stay_inside_group() {
        // Dialog buttons 2,3 in group 9; background button 4 outside;
        // outsider 1 sits left of button 2 and would win unconstrained.
        let chain = vec![1, 2, 3, 4];
        let regions = vec![
            region(1, 0.0, None),
            region(2, 20.0, Some(9)),
            region(3, 40.0, Some(9)),
            region(4, 60.0, None),
        ];
        assert_eq!(
            spatial_focus_next(&chain, &regions, Some(2), FocusDirection::Left),
            None,
            "outsider 1 is left of 2 but outside the group: trapped"
        );
        assert_eq!(
            spatial_focus_next(&chain, &regions, Some(2), FocusDirection::Right),
            Some(3)
        );
        assert_eq!(
            spatial_focus_next(&chain, &regions, Some(3), FocusDirection::Left),
            Some(2)
        );
        assert_eq!(
            spatial_focus_next(&chain, &regions, Some(1), FocusDirection::Right),
            Some(2),
            "ungrouped focus still sees the full chain"
        );
    }

    #[test]
    fn tab_cycles_inside_group() {
        let chain = vec![1, 2, 3, 4];
        let regions = vec![
            region(1, 0.0, None),
            region(2, 20.0, Some(9)),
            region(3, 40.0, Some(9)),
            region(4, 60.0, None),
        ];
        let mut fm = FocusManager::new(chain, Some(2));
        fm.hit_regions = regions;
        assert_eq!(fm.move_tab(false), Some(3));
        assert_eq!(fm.move_tab(false), Some(2));
        assert_eq!(fm.move_tab(true), Some(3));
    }

    #[test]
    fn tab_from_outside_can_enter_group() {
        let chain = vec![1, 2, 3, 4];
        let regions = vec![
            region(1, 0.0, None),
            region(2, 20.0, Some(9)),
            region(3, 40.0, Some(9)),
            region(4, 60.0, None),
        ];
        let mut fm = FocusManager::new(chain, Some(1));
        fm.hit_regions = regions;
        assert_eq!(fm.move_tab(false), Some(2));
        let mut fm = FocusManager::new(vec![1, 2, 3, 4], Some(1));
        fm.hit_regions = vec![
            region(1, 0.0, None),
            region(2, 20.0, Some(9)),
            region(3, 40.0, Some(9)),
            region(4, 60.0, None),
        ];
        assert_eq!(fm.move_tab(true), Some(4));
    }

    #[test]
    fn empty_group_never_moves() {
        let chain = vec![1, 4];
        let regions = vec![region(1, 0.0, None), region(4, 60.0, None)];
        let mut fm = FocusManager::new(chain, Some(1));
        fm.hit_regions = regions.clone();
        assert_eq!(fm.move_tab(false), Some(4));
        let chain = vec![1, 2, 4];
        let regions = vec![
            region(1, 0.0, None),
            region(2, 20.0, Some(77)),
            region(4, 60.0, None),
        ];
        let mut fm = FocusManager::new(chain, Some(2));
        fm.hit_regions = regions;
        assert_eq!(fm.move_tab(false), Some(2));
        assert_eq!(
            spatial_focus_next(&fm.chain, &fm.hit_regions, Some(2), FocusDirection::Right),
            None
        );
    }
}