fret_ui/tree/

commands.rs

use super::*;
use crate::widget::{CommandAvailability, CommandAvailabilityCx};
use fret_runtime::CommandScope;
use std::sync::Arc;

impl<H: UiHost> UiTree<H> {
    pub(crate) fn defer_declarative_window_snapshot_commit(&mut self, root: NodeId) {
        self.pending_declarative_window_snapshot_roots
            .retain(|pending| self.nodes.contains_key(*pending));
        self.pending_declarative_window_snapshot_roots.insert(root);
    }

    pub(crate) fn clear_declarative_window_snapshot_commit(&mut self, root: NodeId) {
        self.pending_declarative_window_snapshot_roots.remove(&root);
    }

    pub(in crate::tree) fn revalidate_focus_for_dispatch_snapshot(
        &mut self,
        frame_id: fret_runtime::FrameId,
        active_focus_layers: &[NodeId],
        barrier_root: Option<NodeId>,
        reason: &'static str,
    ) {
        let dispatch_snapshot = self.build_dispatch_snapshot_for_layer_roots(
            frame_id,
            active_focus_layers,
            barrier_root,
        );
        if self
            .focus
            .is_some_and(|node| dispatch_snapshot.pre.get(node).is_none())
        {
            self.set_focus_unchecked(None, reason);
        }
    }

    pub(in crate::tree) fn revalidate_pending_shortcut_for_current_routing_context(
        &mut self,
        app: &mut H,
        barrier_root: Option<NodeId>,
    ) {
        if self.replaying_pending_shortcut || self.pending_shortcut.keystrokes.is_empty() {
            return;
        }

        // `focus` / `barrier_root` are only proxies for the shortcut-routing context. Root
        // replacement and other retained-tree repairs can change the authoritative key-context
        // stack without changing either proxy (for example, when no node is focused). Re-check
        // the current key-context stack before continuing a multi-stroke sequence.
        let current_key_contexts = self.shortcut_key_context_stack(app, barrier_root);
        if (self.pending_shortcut.focus.is_some() && self.pending_shortcut.focus != self.focus)
            || self.pending_shortcut.barrier_root != barrier_root
            || self.pending_shortcut.key_contexts.as_slice() != current_key_contexts.as_slice()
        {
            self.clear_pending_shortcut(app);
        }
    }

    pub(in crate::tree) fn current_window_input_context(
        &self,
        app: &mut H,
        ui_has_modal: bool,
        focus_is_text_input: bool,
    ) -> InputContext {
        let caps = app
            .global::<PlatformCapabilities>()
            .cloned()
            .unwrap_or_default();
        let mut input_ctx = InputContext {
            platform: Platform::current(),
            caps,
            ui_has_modal,
            window_arbitration: self
                .window
                .map(|_| self.window_input_arbitration_snapshot()),
            focus_is_text_input,
            text_boundary_mode: fret_runtime::TextBoundaryMode::UnicodeWord,
            edit_can_undo: true,
            edit_can_redo: true,
            router_can_back: false,
            router_can_forward: false,
            dispatch_phase: InputDispatchPhase::Bubble,
        };
        if let Some(window) = self.window {
            if let Some(mode) = app
                .global::<fret_runtime::WindowTextBoundaryModeService>()
                .and_then(|svc| svc.mode(window))
            {
                input_ctx.text_boundary_mode = mode;
            }
            if let Some(availability) = app
                .global::<fret_runtime::WindowCommandAvailabilityService>()
                .and_then(|svc| svc.snapshot(window))
                .copied()
            {
                input_ctx.edit_can_undo = availability.edit_can_undo;
                input_ctx.edit_can_redo = availability.edit_can_redo;
                input_ctx.router_can_back = availability.router_can_back;
                input_ctx.router_can_forward = availability.router_can_forward;
            }
        }
        if let Some(mode) = self.focus_text_boundary_mode_override() {
            input_ctx.text_boundary_mode = mode;
        }
        input_ctx
    }

    pub(in crate::tree) fn publish_window_input_context_snapshot(
        &self,
        app: &mut H,
        input_ctx: &InputContext,
    ) {
        let Some(window) = self.window else {
            return;
        };
        let needs_update = app
            .global::<fret_runtime::WindowInputContextService>()
            .and_then(|svc| svc.snapshot(window))
            .is_none_or(|prev| prev != input_ctx);
        if needs_update {
            app.with_global_mut(
                fret_runtime::WindowInputContextService::default,
                |svc, _app| {
                    svc.set_snapshot(window, input_ctx.clone());
                },
            );
        }
    }

    pub(in crate::tree) fn publish_window_input_context_snapshot_untracked(
        &self,
        app: &mut H,
        input_ctx: &InputContext,
        only_if_changed: bool,
    ) {
        let Some(window) = self.window else {
            return;
        };
        if only_if_changed {
            let needs_update = app
                .global::<fret_runtime::WindowInputContextService>()
                .and_then(|svc| svc.snapshot(window))
                .is_none_or(|prev| prev != input_ctx);
            if !needs_update {
                return;
            }
        }
        app.with_global_mut_untracked(
            fret_runtime::WindowInputContextService::default,
            |svc, _app| {
                svc.set_snapshot(window, input_ctx.clone());
            },
        );
    }

    pub(in crate::tree) fn publish_window_key_context_stack_snapshot(
        &self,
        app: &mut H,
        key_contexts: Vec<Arc<str>>,
    ) {
        let Some(window) = self.window else {
            return;
        };
        let needs_update = app
            .global::<fret_runtime::WindowKeyContextStackService>()
            .and_then(|svc| svc.snapshot(window))
            .is_none_or(|prev| prev != key_contexts.as_slice());
        if needs_update {
            app.with_global_mut(
                fret_runtime::WindowKeyContextStackService::default,
                |svc, _app| {
                    svc.set_snapshot(window, key_contexts);
                },
            );
        }
    }

    pub(in crate::tree) fn publish_post_dispatch_runtime_snapshots_for_event(
        &mut self,
        app: &mut H,
        event: &Event,
    ) {
        let focus_is_text_input = self.focus_is_text_input(app);
        self.set_ime_allowed(app, focus_is_text_input);

        let (_active_layers, barrier_root) = self.active_input_layers();
        if matches!(event, Event::Pointer(fret_core::PointerEvent::Move { .. })) {
            let input_ctx =
                self.current_window_input_context(app, barrier_root.is_some(), focus_is_text_input);
            self.publish_window_input_context_snapshot_untracked(app, &input_ctx, false);
        } else {
            self.publish_window_runtime_snapshots(app);
        }
    }

    /// Publishes authoritative window-level runtime snapshots for the tree's current retained
    /// state.
    ///
    /// Raw `UiTree` mutation APIs (`set_root`, `set_focus`, overlay/layer mutation, subtree
    /// removal, and similar helpers) only update retained tree state. Cross-surface consumers that
    /// read `WindowInputContextService`, `WindowKeyContextStackService`,
    /// `PendingShortcutOverlayState`, or
    /// `WindowCommandActionAvailabilityService` become authoritative only after this publish step
    /// or another full snapshot commit boundary such as declarative rebuild or non-pointer input
    /// dispatch. Paint-only boundaries refresh `WindowInputContextService`, but they do not
    /// republish the full key-context / command-availability snapshot set.
    ///
    /// Layout-time raw focus/layer mutations are the one exception: they automatically schedule a
    /// post-layout refine so final layout boundaries can republish authoritative snapshots without
    /// forcing policy code to publish from inside `layout()`.
    ///
    /// Call this after imperative tree mutations when later same-frame consumers must observe the
    /// new authoritative window state immediately.
    pub fn publish_window_runtime_snapshots(&mut self, app: &mut H) {
        self.pending_declarative_window_snapshot_roots
            .retain(|pending| self.nodes.contains_key(*pending));
        self.resolve_pending_focus_target_if_needed(app);
        let focused_element_before_revalidate = self.window.and_then(|window| {
            self.focus.and_then(|focused| {
                crate::elements::with_window_state(app, window, |state| {
                    state.element_for_node(focused)
                })
            })
        });
        let (_active_input_layers, input_barrier_root) = self.active_input_layers();
        let (active_focus_layers, focus_barrier_root) = self.active_focus_layers();
        let barrier_root = focus_barrier_root.or(input_barrier_root);

        let focus_before_revalidate = self.focus;
        self.revalidate_focus_for_dispatch_snapshot(
            app.frame_id(),
            active_focus_layers.as_slice(),
            barrier_root,
            "commands: focus missing from dispatch snapshot",
        );
        if focus_before_revalidate.is_some()
            && self.focus.is_none()
            && let Some(window) = self.window
            && let Some(element) = focused_element_before_revalidate
            && crate::elements::element_identity_is_live_in_current_frame(app, window, element)
        {
            // Declarative overlay/content roots can attach before final layout makes them part of
            // the authoritative dispatch snapshot. Preserve the element identity as a deferred
            // target so the final-layout snapshot refine can recover focus instead of dropping it
            // for the rest of the frame.
            self.pending_focus_target = Some(element);
            self.request_post_layout_window_runtime_snapshot_refine();
        }

        self.revalidate_pending_shortcut_for_current_routing_context(app, barrier_root);

        let focus_is_text_input = self.focus_is_text_input(app);
        let input_ctx = self.current_window_input_context(
            app,
            input_barrier_root.is_some(),
            focus_is_text_input,
        );

        self.publish_window_input_context_snapshot(app, &input_ctx);
        self.publish_window_command_action_availability_snapshot(app, &input_ctx);
        self.refresh_pending_shortcut_overlay_state_if_needed(app, &input_ctx);
    }

    pub(in crate::tree) fn request_post_layout_window_runtime_snapshot_refine(&mut self) {
        self.pending_post_layout_window_runtime_snapshot_refine = true;
    }

    pub(in crate::tree) fn request_post_layout_window_runtime_snapshot_refine_if_layout_active(
        &mut self,
    ) {
        if self.layout_call_depth > 0 {
            self.request_post_layout_window_runtime_snapshot_refine();
        }
    }

    /// Finalize a declarative rebuild that mounted a detached root and only later attached it to
    /// the retained tree.
    ///
    /// `render_dismissible_root_with_hooks(...)` can rebuild an overlay/portal root before the
    /// caller attaches that root to a layer or parent. In that case the helper defers the window
    /// snapshot commit until the root is actually attached. Call this after `push_overlay_root`,
    /// `set_children`, or another attach operation that makes the returned root authoritative for
    /// same-frame window-level consumers.
    ///
    /// This is intentionally narrower than `publish_window_runtime_snapshots(...)`: raw imperative
    /// tree mutation still requires an explicit commit, while declarative detached-root authoring
    /// can finish its pending commit once attachment is complete.
    pub fn commit_pending_declarative_window_runtime_snapshots(
        &mut self,
        app: &mut H,
        root: NodeId,
    ) -> bool {
        self.pending_declarative_window_snapshot_roots
            .retain(|pending| self.nodes.contains_key(*pending));
        if !self
            .pending_declarative_window_snapshot_roots
            .contains(&root)
        {
            return false;
        }

        let attached = self.node_layer(root).is_some() || self.node_parent(root).is_some();
        if !attached {
            return false;
        }

        self.pending_declarative_window_snapshot_roots.remove(&root);
        self.publish_window_runtime_snapshots(app);
        true
    }

    fn focus_menu_bar_command_availability(&self, app: &mut H) -> CommandAvailability {
        let Some(window) = self.window else {
            return CommandAvailability::NotHandled;
        };
        let present = app
            .global::<fret_runtime::WindowMenuBarFocusService>()
            .is_some_and(|svc| svc.present(window));
        if present {
            CommandAvailability::Available
        } else {
            CommandAvailability::NotHandled
        }
    }

    #[stacksafe::stacksafe]
    pub fn is_command_available(&mut self, app: &mut H, command: &CommandId) -> bool {
        self.command_availability(app, command) == CommandAvailability::Available
    }

    /// GPUI naming parity: "is this action available along the dispatch path?"
    ///
    /// Note: Fret models "actions" as `CommandId` today (especially for widget-scoped commands).
    #[stacksafe::stacksafe]
    pub fn is_action_available(&mut self, app: &mut H, command: &CommandId) -> bool {
        self.is_command_available(app, command)
    }

    /// GPUI naming parity for availability queries.
    #[stacksafe::stacksafe]
    pub fn action_availability(&mut self, app: &mut H, command: &CommandId) -> CommandAvailability {
        self.command_availability(app, command)
    }

    #[stacksafe::stacksafe]
    pub fn command_availability(
        &mut self,
        app: &mut H,
        command: &CommandId,
    ) -> CommandAvailability {
        if command.as_str() == "focus.menu_bar" {
            return self.focus_menu_bar_command_availability(app);
        }

        let Some(base_root) = self
            .base_layer
            .and_then(|id| self.layers.get(id).map(|l| l.root))
        else {
            return CommandAvailability::NotHandled;
        };

        let (_active_input_layers, input_barrier_root) = self.active_input_layers();
        let (active_focus_layers, focus_barrier_root) = self.active_focus_layers();
        let barrier_root = focus_barrier_root.or(input_barrier_root);
        let dispatch_snapshot = self.build_dispatch_snapshot_for_layer_roots(
            app.frame_id(),
            active_focus_layers.as_slice(),
            barrier_root,
        );
        let caps = app
            .global::<PlatformCapabilities>()
            .cloned()
            .unwrap_or_default();
        let mut input_ctx: InputContext = InputContext {
            platform: Platform::current(),
            caps,
            ui_has_modal: input_barrier_root.is_some(),
            window_arbitration: None,
            focus_is_text_input: self.focus_is_text_input(app),
            text_boundary_mode: fret_runtime::TextBoundaryMode::UnicodeWord,
            edit_can_undo: true,
            edit_can_redo: true,
            router_can_back: false,
            router_can_forward: false,
            dispatch_phase: InputDispatchPhase::Bubble,
        };
        if let Some(window) = self.window {
            if let Some(mode) = app
                .global::<fret_runtime::WindowTextBoundaryModeService>()
                .and_then(|svc| svc.mode(window))
            {
                input_ctx.text_boundary_mode = mode;
            }
            if let Some(availability) = app
                .global::<fret_runtime::WindowCommandAvailabilityService>()
                .and_then(|svc| svc.snapshot(window))
                .copied()
            {
                input_ctx.edit_can_undo = availability.edit_can_undo;
                input_ctx.edit_can_redo = availability.edit_can_redo;
                input_ctx.router_can_back = availability.router_can_back;
                input_ctx.router_can_forward = availability.router_can_forward;
            }
            input_ctx.window_arbitration = Some(self.window_input_arbitration_snapshot());
        }

        if self
            .focus
            .is_some_and(|n| dispatch_snapshot.pre.get(n).is_none())
        {
            self.set_focus_unchecked(None, "commands: focus missing from dispatch snapshot");
        }

        let default_root = barrier_root.unwrap_or(base_root);
        let start = self.focus.unwrap_or(default_root);
        let mut availability = self.command_availability_from_node(app, &input_ctx, start, command);
        // When focus lives in a non-default layer (e.g. a non-modal overlay), we still want
        // widget-scoped command availability to fall back to the default root so global shortcuts
        // and menus remain usable.
        if availability == CommandAvailability::NotHandled && start != default_root {
            availability =
                self.command_availability_from_node(app, &input_ctx, default_root, command);
        }

        if availability == CommandAvailability::NotHandled
            && matches!(command.as_str(), "focus.next" | "focus.previous")
        {
            return self.focus_traversal_command_availability(
                app,
                app.frame_id(),
                &dispatch_snapshot,
                barrier_root,
            );
        }

        availability
    }

    fn focus_traversal_command_availability(
        &mut self,
        app: &mut H,
        frame_id: fret_runtime::FrameId,
        dispatch_snapshot: &UiDispatchSnapshot,
        barrier_root: Option<NodeId>,
    ) -> CommandAvailability {
        self.focus_traversal_command_availability_for_snapshot(
            app,
            frame_id,
            dispatch_snapshot,
            barrier_root,
        )
        .0
    }

    fn focus_traversal_command_availability_for_snapshot(
        &mut self,
        app: &mut H,
        frame_id: fret_runtime::FrameId,
        dispatch_snapshot: &UiDispatchSnapshot,
        scope_root: Option<NodeId>,
    ) -> (CommandAvailability, bool) {
        let (focusables, needs_layout_refine) = self.focus_traversal_candidates_for_snapshot(
            app,
            frame_id,
            dispatch_snapshot,
            scope_root,
        );

        (
            if focusables.is_empty() {
                CommandAvailability::NotHandled
            } else {
                CommandAvailability::Available
            },
            needs_layout_refine && !focusables.is_empty(),
        )
    }

    fn focus_traversal_candidates_for_snapshot(
        &mut self,
        app: &mut H,
        frame_id: fret_runtime::FrameId,
        dispatch_snapshot: &UiDispatchSnapshot,
        scope_root: Option<NodeId>,
    ) -> (Vec<NodeId>, bool) {
        let scope_root = scope_root.or(dispatch_snapshot.barrier_root).or_else(|| {
            self.base_layer
                .and_then(|id| self.layers.get(id).map(|l| l.root))
        });
        let Some(scope_root) = scope_root else {
            return (Vec::new(), false);
        };

        let mut focusables: Vec<NodeId> = Vec::new();
        let needs_layout_refine = self.last_layout_frame_id != Some(frame_id)
            || self.node_subtree_layout_dirty(scope_root);
        if needs_layout_refine {
            for &root in &dispatch_snapshot.active_layer_roots {
                self.collect_focusables_structural(app, root, dispatch_snapshot, &mut focusables);
            }
        } else {
            let scope_bounds = self
                .nodes
                .get(scope_root)
                .map(|n| n.bounds)
                .unwrap_or_default();
            for &root in &dispatch_snapshot.active_layer_roots {
                self.collect_focusables(root, dispatch_snapshot, scope_bounds, &mut focusables);
            }
        }

        (focusables, needs_layout_refine)
    }

    fn collect_focusables_structural(
        &self,
        app: &mut H,
        node: NodeId,
        dispatch_snapshot: &UiDispatchSnapshot,
        out: &mut Vec<NodeId>,
    ) {
        if dispatch_snapshot.pre.get(node).is_none() {
            return;
        }

        let Some(n) = self.nodes.get(node) else {
            return;
        };

        let (is_focusable, traverse_children) =
            self.structural_focus_traversal_state_for_node(app, node);
        if is_focusable {
            out.push(node);
        }

        if traverse_children {
            for &child in &n.children {
                self.collect_focusables_structural(app, child, dispatch_snapshot, out);
            }
        }
    }

    fn structural_focus_traversal_state_for_node(&self, app: &mut H, node: NodeId) -> (bool, bool) {
        if let Some(window) = self.window
            && let Some((is_focusable, traverse_children)) =
                crate::declarative::frame::with_element_record_for_node(
                    app,
                    window,
                    node,
                    |record| match &record.instance {
                        crate::declarative::frame::ElementInstance::TextInput(_)
                        | crate::declarative::frame::ElementInstance::TextArea(_)
                        | crate::declarative::frame::ElementInstance::TextInputRegion(_) => {
                            (true, true)
                        }
                        crate::declarative::frame::ElementInstance::SelectableText(_) => {
                            (true, true)
                        }
                        crate::declarative::frame::ElementInstance::Pressable(props) => {
                            (props.enabled && props.focusable, props.enabled)
                        }
                        crate::declarative::frame::ElementInstance::Semantics(props) => {
                            (props.focusable && !props.disabled && !props.hidden, true)
                        }
                        crate::declarative::frame::ElementInstance::InteractivityGate(props) => {
                            (false, props.present && props.interactive)
                        }
                        crate::declarative::frame::ElementInstance::FocusTraversalGate(props) => {
                            (false, props.traverse)
                        }
                        crate::declarative::frame::ElementInstance::Spinner(_) => (false, false),
                        _ => (false, true),
                    },
                )
        {
            return (is_focusable, traverse_children);
        }

        let Some(n) = self.nodes.get(node) else {
            return (false, true);
        };
        let prepaint =
            (!self.inspection_active && !n.invalidation.hit_test && !n.invalidation.layout)
                .then_some(n.prepaint_hit_test)
                .flatten();
        (
            prepaint
                .as_ref()
                .map(|p| p.is_focusable)
                .unwrap_or_else(|| n.widget.as_ref().is_some_and(|w| w.is_focusable())),
            prepaint
                .as_ref()
                .map(|p| p.focus_traversal_children)
                .unwrap_or_else(|| {
                    n.widget
                        .as_ref()
                        .map(|w| w.focus_traversal_children())
                        .unwrap_or(true)
                }),
        )
    }

    #[stacksafe::stacksafe]
    fn command_availability_from_node(
        &mut self,
        app: &mut H,
        input_ctx: &InputContext,
        start: NodeId,
        command: &CommandId,
    ) -> CommandAvailability {
        let mut node_id = start;
        loop {
            let (availability, parent) = self.with_widget_mut(node_id, |widget, tree| {
                let parent = tree.nodes.get(node_id).and_then(|n| n.parent);
                let window = tree.window;
                let focus = tree.focus;
                let mut cx = CommandAvailabilityCx {
                    app,
                    tree: &*tree,
                    node: node_id,
                    window,
                    input_ctx: input_ctx.clone(),
                    focus,
                };
                (widget.command_availability(&mut cx, command), parent)
            });

            match availability {
                CommandAvailability::Available | CommandAvailability::Blocked => {
                    return availability;
                }
                CommandAvailability::NotHandled => {}
            }

            node_id = match parent {
                Some(parent) => parent,
                None => break,
            };
        }

        CommandAvailability::NotHandled
    }

    /// Publish a per-window action availability snapshot for widget-scoped commands.
    ///
    /// This is a data-only integration seam for runner/platform and UI-kit layers (menus, command
    /// palette, shortcut help). Most apps should prefer publishing a filtered snapshot (e.g. only
    /// menu/palette command sets) at the app-driver layer.
    ///
    /// Notes:
    /// - This retained-runtime helper publishes a conservative baseline: for each widget-scoped
    ///   command in the registry, `NotHandled` is treated as "unavailable" (`false`) so
    ///   cross-surface gating behaves consistently.
    pub fn publish_window_command_action_availability_snapshot(
        &mut self,
        app: &mut H,
        input_ctx: &InputContext,
    ) {
        let Some(window) = self.window else {
            return;
        };

        let Some(base_root) = self
            .base_layer
            .and_then(|id| self.layers.get(id).map(|l| l.root))
        else {
            return;
        };
        let (_active_input_layers, input_barrier_root) = self.active_input_layers();
        let (active_focus_layers, focus_barrier_root) = self.active_focus_layers();
        let barrier_root = focus_barrier_root.or(input_barrier_root);
        let dispatch_snapshot = self.build_dispatch_snapshot_for_layer_roots(
            app.frame_id(),
            active_focus_layers.as_slice(),
            barrier_root,
        );
        self.revalidate_focus_for_dispatch_snapshot(
            app.frame_id(),
            active_focus_layers.as_slice(),
            barrier_root,
            "commands: focus missing from dispatch snapshot",
        );

        let default_root = barrier_root.unwrap_or(base_root);
        let focus = self.focus;
        let focus_in_default_root = focus.is_some_and(|n| self.is_descendant(default_root, n));
        let start = focus.unwrap_or(default_root);
        let next_key_contexts = self.shortcut_key_context_stack(app, barrier_root);
        let mut focus_traversal_snapshot: Option<(CommandAvailability, bool)> = None;

        let mut snapshot: HashMap<CommandId, bool> = HashMap::new();
        let widget_commands: Vec<CommandId> = app
            .commands()
            .iter()
            .filter_map(|(id, meta)| (meta.scope == CommandScope::Widget).then_some(id.clone()))
            .collect();

        for id in widget_commands {
            if id.as_str() == "focus.menu_bar" {
                let present = app
                    .global::<fret_runtime::WindowMenuBarFocusService>()
                    .is_some_and(|svc| svc.present(window));
                snapshot.insert(id, present);
                continue;
            }

            let mut availability = self.command_availability_from_node(app, input_ctx, start, &id);
            if availability == CommandAvailability::NotHandled
                && focus.is_some()
                && !focus_in_default_root
                && start != default_root
            {
                availability =
                    self.command_availability_from_node(app, input_ctx, default_root, &id);
            }
            if availability == CommandAvailability::NotHandled
                && matches!(id.as_str(), "focus.next" | "focus.previous")
            {
                let (focus_traversal_availability, needs_layout_refine) = *focus_traversal_snapshot
                    .get_or_insert_with(|| {
                        self.focus_traversal_command_availability_for_snapshot(
                            app,
                            app.frame_id(),
                            &dispatch_snapshot,
                            barrier_root,
                        )
                    });
                availability = focus_traversal_availability;
                if needs_layout_refine {
                    self.pending_post_layout_window_runtime_snapshot_refine = true;
                }
            }
            if availability == CommandAvailability::NotHandled && id.as_str() == "focus.menu_bar" {
                let present = app
                    .global::<fret_runtime::WindowMenuBarFocusService>()
                    .is_some_and(|svc| svc.present(window));
                snapshot.insert(id, present);
                continue;
            }
            match availability {
                CommandAvailability::Available => {
                    snapshot.insert(id, true);
                }
                CommandAvailability::Blocked => {
                    snapshot.insert(id, false);
                }
                CommandAvailability::NotHandled => {
                    // For widget-scoped commands, “not handled anywhere on the dispatch path”
                    // means “not available” (disabled) for cross-surface gating (menus, palettes,
                    // shortcuts).
                    snapshot.insert(id, false);
                }
            }
        }

        self.publish_window_key_context_stack_snapshot(app, next_key_contexts);

        let needs_update = app
            .global::<fret_runtime::WindowCommandActionAvailabilityService>()
            .and_then(|svc| svc.snapshot(window))
            .is_none_or(|prev| prev != &snapshot);
        if needs_update {
            app.with_global_mut(
                fret_runtime::WindowCommandActionAvailabilityService::default,
                |svc, _app| {
                    svc.set_snapshot(window, snapshot);
                },
            );
        }
    }

    pub(in crate::tree) fn refine_pending_window_runtime_snapshots_after_layout(
        &mut self,
        app: &mut H,
    ) {
        if !std::mem::take(&mut self.pending_post_layout_window_runtime_snapshot_refine) {
            return;
        }
        self.publish_window_runtime_snapshots(app);
    }

    #[stacksafe::stacksafe]
    pub fn dispatch_command(
        &mut self,
        app: &mut H,
        services: &mut dyn UiServices,
        command: &CommandId,
    ) -> bool {
        let Some(base_root) = self
            .base_layer
            .and_then(|id| self.layers.get(id).map(|l| l.root))
        else {
            return false;
        };

        let (_active_input_layers, input_barrier_root) = self.active_input_layers();
        let (active_focus_layers, focus_barrier_root) = self.active_focus_layers();
        let barrier_root = focus_barrier_root.or(input_barrier_root);
        let dispatch_snapshot = self.build_dispatch_snapshot_for_layer_roots(
            app.frame_id(),
            active_focus_layers.as_slice(),
            barrier_root,
        );
        let caps = app
            .global::<PlatformCapabilities>()
            .cloned()
            .unwrap_or_default();
        let mut input_ctx = InputContext {
            platform: Platform::current(),
            caps,
            ui_has_modal: input_barrier_root.is_some(),
            window_arbitration: None,
            focus_is_text_input: self.focus_is_text_input(app),
            text_boundary_mode: fret_runtime::TextBoundaryMode::UnicodeWord,
            edit_can_undo: true,
            edit_can_redo: true,
            router_can_back: false,
            router_can_forward: false,
            dispatch_phase: InputDispatchPhase::Bubble,
        };
        if let Some(window) = self.window {
            if let Some(mode) = app
                .global::<fret_runtime::WindowTextBoundaryModeService>()
                .and_then(|svc| svc.mode(window))
            {
                input_ctx.text_boundary_mode = mode;
            }
            if let Some(availability) = app
                .global::<fret_runtime::WindowCommandAvailabilityService>()
                .and_then(|svc| svc.snapshot(window))
                .copied()
            {
                input_ctx.edit_can_undo = availability.edit_can_undo;
                input_ctx.edit_can_redo = availability.edit_can_redo;
                input_ctx.router_can_back = availability.router_can_back;
                input_ctx.router_can_forward = availability.router_can_forward;
            }

            let window_arbitration = self.window_input_arbitration_snapshot();
            input_ctx.window_arbitration = Some(window_arbitration);

            let needs_update = app
                .global::<fret_runtime::WindowInputContextService>()
                .and_then(|svc| svc.snapshot(window))
                .is_none_or(|prev| prev != &input_ctx);
            if needs_update {
                app.with_global_mut(
                    fret_runtime::WindowInputContextService::default,
                    |svc, _app| {
                        svc.set_snapshot(window, input_ctx.clone());
                    },
                );
            }
        }
        let is_focus_traversal_command =
            matches!(command.as_str(), "focus.next" | "focus.previous");

        if self
            .focus
            .is_some_and(|n| dispatch_snapshot.pre.get(n).is_none())
        {
            self.set_focus_unchecked(None, "commands: focus missing from dispatch snapshot");
        }
        self.revalidate_pending_shortcut_for_current_routing_context(app, barrier_root);

        let default_root = barrier_root.unwrap_or(base_root);
        let focus = self.focus;

        let source = if let Some(window) = self.window {
            app.with_global_mut(
                fret_runtime::WindowPendingCommandDispatchSourceService::default,
                |svc, app| {
                    svc.consume(window, app.tick_id(), command)
                        .unwrap_or_else(fret_runtime::CommandDispatchSourceV1::programmatic)
                },
            )
        } else {
            fret_runtime::CommandDispatchSourceV1::programmatic()
        };

        let source_node = source.element.and_then(|element| {
            self.resolve_live_attached_node_for_element(
                app,
                self.window,
                crate::GlobalElementId(element),
            )
        });

        let start = source_node.or(focus).unwrap_or(default_root);
        let start_in_default_root =
            start == default_root || self.is_descendant(default_root, start);

        let mut bubble_from = |start: NodeId| -> (bool, bool, bool, Option<NodeId>) {
            let mut node_id = start;
            let mut handled = false;
            let mut needs_redraw = false;
            let mut stopped = false;
            let mut handled_by_node: Option<NodeId> = None;

            loop {
                let (
                    did_handle,
                    invalidations,
                    requested_focus,
                    notify_requested,
                    notify_requested_location,
                    stop_bubbling,
                    parent,
                ) = self.with_widget_mut(node_id, |widget, tree| {
                    let parent = tree.nodes.get(node_id).and_then(|n| n.parent);
                    let window = tree.window;
                    let focus = tree.focus;
                    let mut cx = CommandCx {
                        app,
                        services: &mut *services,
                        tree,
                        node: node_id,
                        window,
                        input_ctx: input_ctx.clone(),
                        focus,
                        invalidations: Vec::new(),
                        requested_focus: None,
                        notify_requested: false,
                        notify_requested_location: None,
                        stop_propagation: false,
                    };
                    let did_handle = widget.command(&mut cx, command);
                    (
                        did_handle,
                        cx.invalidations,
                        cx.requested_focus,
                        cx.notify_requested,
                        cx.notify_requested_location,
                        cx.stop_propagation,
                        parent,
                    )
                });

                if did_handle {
                    handled = true;
                    handled_by_node = handled_by_node.or(Some(node_id));
                }

                if !invalidations.is_empty() || requested_focus.is_some() || notify_requested {
                    needs_redraw = true;
                }

                for (id, inv) in invalidations {
                    self.mark_invalidation(id, inv);
                }

                if notify_requested {
                    self.debug_record_notify_request(
                        app.frame_id(),
                        node_id,
                        notify_requested_location,
                    );
                    self.mark_invalidation_with_source(
                        node_id,
                        Invalidation::Paint,
                        UiDebugInvalidationSource::Notify,
                    );
                    needs_redraw = true;
                }

                if let Some(focus) = requested_focus {
                    let (active_roots, barrier_root) = self.active_input_layers();
                    let snapshot = self.build_dispatch_snapshot_for_layer_roots(
                        app.frame_id(),
                        active_roots.as_slice(),
                        barrier_root,
                    );
                    if self.focus_request_is_allowed(
                        app,
                        self.window,
                        &active_roots,
                        focus,
                        Some(&snapshot),
                    ) {
                        if let Some(prev) = self.focus {
                            self.mark_invalidation(prev, Invalidation::Paint);
                        }
                        self.focus = Some(focus);
                        self.mark_invalidation(focus, Invalidation::Paint);
                    }
                }

                if did_handle {
                    break;
                }
                if stop_bubbling {
                    stopped = true;
                    break;
                }

                node_id = match parent {
                    Some(parent) => parent,
                    None => break,
                };
            }

            (handled, needs_redraw, stopped, handled_by_node)
        };

        let (mut handled, mut needs_redraw, mut stopped, mut handled_by_node) = bubble_from(start);
        let mut used_default_root_fallback = false;
        if !handled && !stopped && start != default_root && !start_in_default_root {
            used_default_root_fallback = true;
            let (handled2, needs_redraw2, stopped2, handled_by_node2) = bubble_from(default_root);
            handled = handled || handled2;
            needs_redraw = needs_redraw || needs_redraw2;
            stopped = stopped || stopped2;
            handled_by_node = handled_by_node.or(handled_by_node2);
        }

        if !handled && !stopped && is_focus_traversal_command {
            handled = self.dispatch_focus_traversal(
                app,
                command,
                active_focus_layers.as_slice(),
                barrier_root,
            );
            needs_redraw = true;
        }

        if needs_redraw {
            self.request_redraw_coalesced(app);
        }

        // Publish a post-dispatch snapshot so runner-level integration surfaces (e.g. OS menubars)
        // see the latest focus/modal state without waiting for the next paint pass.
        if let Some(window) = self.window {
            let (_active_layers, input_barrier_root) = self.active_input_layers();
            let (_active_focus_layers, focus_barrier_root) = self.active_focus_layers();
            let barrier_root = focus_barrier_root.or(input_barrier_root);
            self.revalidate_pending_shortcut_for_current_routing_context(app, barrier_root);
            let caps = app
                .global::<PlatformCapabilities>()
                .cloned()
                .unwrap_or_default();
            let mut input_ctx = InputContext {
                platform: Platform::current(),
                caps,
                ui_has_modal: input_barrier_root.is_some(),
                window_arbitration: None,
                focus_is_text_input: self.focus_is_text_input(app),
                text_boundary_mode: fret_runtime::TextBoundaryMode::UnicodeWord,
                edit_can_undo: true,
                edit_can_redo: true,
                router_can_back: false,
                router_can_forward: false,
                dispatch_phase: InputDispatchPhase::Bubble,
            };
            if let Some(mode) = app
                .global::<fret_runtime::WindowTextBoundaryModeService>()
                .and_then(|svc| svc.mode(window))
            {
                input_ctx.text_boundary_mode = mode;
            }
            if let Some(availability) = app
                .global::<fret_runtime::WindowCommandAvailabilityService>()
                .and_then(|svc| svc.snapshot(window))
                .copied()
            {
                input_ctx.edit_can_undo = availability.edit_can_undo;
                input_ctx.edit_can_redo = availability.edit_can_redo;
                input_ctx.router_can_back = availability.router_can_back;
                input_ctx.router_can_forward = availability.router_can_forward;
            }

            let window_arbitration = self.window_input_arbitration_snapshot();
            input_ctx.window_arbitration = Some(window_arbitration);

            let needs_update = app
                .global::<fret_runtime::WindowInputContextService>()
                .and_then(|svc| svc.snapshot(window))
                .is_none_or(|prev| prev != &input_ctx);
            if needs_update {
                app.with_global_mut(
                    fret_runtime::WindowInputContextService::default,
                    |svc, _app| {
                        svc.set_snapshot(window, input_ctx.clone());
                    },
                );
            }

            self.publish_window_command_action_availability_snapshot(app, &input_ctx);
            self.refresh_pending_shortcut_overlay_state_if_needed(app, &input_ctx);
        }

        if let Some(window) = self.window {
            let handled_by_element = handled_by_node
                .and_then(|node| self.node_element(node))
                .map(|id| id.0);
            let started_from_focus = focus.is_some();

            app.with_global_mut(
                fret_runtime::WindowCommandDispatchDiagnosticsStore::default,
                |store, app| {
                    let handled_by_scope = if handled {
                        Some(fret_runtime::CommandScope::Widget)
                    } else {
                        None
                    };
                    store.record(fret_runtime::CommandDispatchDecisionV1 {
                        seq: 0,
                        frame_id: app.frame_id(),
                        tick_id: app.tick_id(),
                        window,
                        command: command.clone(),
                        source,
                        handled,
                        handled_by_element,
                        handled_by_scope,
                        handled_by_driver: false,
                        stopped,
                        started_from_focus,
                        used_default_root_fallback,
                    });
                },
            );
        }

        handled
    }

    fn dispatch_focus_traversal(
        &mut self,
        app: &mut H,
        command: &CommandId,
        active_focus_layers: &[NodeId],
        scope_root: Option<NodeId>,
    ) -> bool {
        let direction = match command.as_str() {
            "focus.next" => Some(true),
            "focus.previous" => Some(false),
            _ => None,
        };
        let Some(forward) = direction else {
            return false;
        };

        self.focus_traverse_in_roots(app, active_focus_layers, forward, scope_root)
    }

    /// Focus traversal mechanism used by both the runtime default and component-owned focus scopes.
    ///
    /// Notes:
    /// - `roots` are treated as the authoritative traversal roots for this dispatch path.
    /// - `scope_root` gates authoritative geometry clipping when layout is current.
    /// - This is intentionally conservative until we formalize a scroll-into-view contract (ADR 0068).
    pub fn focus_traverse_in_roots(
        &mut self,
        app: &mut H,
        roots: &[NodeId],
        forward: bool,
        scope_root: Option<NodeId>,
    ) -> bool {
        let dispatch_snapshot =
            self.build_dispatch_snapshot_for_layer_roots(app.frame_id(), roots, scope_root);
        let (focusables, _) = self.focus_traversal_candidates_for_snapshot(
            app,
            app.frame_id(),
            &dispatch_snapshot,
            scope_root,
        );
        if focusables.is_empty() {
            return true;
        }

        let next = match self
            .focus
            .and_then(|f| focusables.iter().position(|n| *n == f))
        {
            Some(idx) => {
                if forward {
                    focusables[(idx + 1) % focusables.len()]
                } else {
                    focusables[(idx + focusables.len() - 1) % focusables.len()]
                }
            }
            None => {
                if forward {
                    focusables[0]
                } else {
                    focusables[focusables.len() - 1]
                }
            }
        };

        if self.focus != Some(next) {
            if let Some(prev) = self.focus {
                self.mark_invalidation(prev, Invalidation::Paint);
            }
            self.focus = Some(next);
            self.mark_invalidation(next, Invalidation::Paint);
            self.scroll_node_into_view(app, next);
        }
        self.request_redraw_coalesced(app);
        true
    }
    pub fn scroll_node_into_view(&mut self, app: &mut H, target: NodeId) -> bool {
        let Some(target_bounds) = self.nodes.get(target).map(|n| n.bounds) else {
            return false;
        };

        // Only scroll *ancestors* of the target into view.
        //
        // If the target itself is scrollable, attempting to scroll it “into view” via itself can
        // incorrectly mutate its offset (e.g. resetting a virtual list to top when it receives
        // focus).
        let mut node = self.nodes.get(target).and_then(|n| n.parent);
        let mut any_scrolled = false;
        let mut descendant_bounds = target_bounds;
        while let Some(id) = node {
            let parent = self.nodes.get(id).and_then(|n| n.parent);
            node = parent;

            let Some(bounds) = self.nodes.get(id).map(|n| n.bounds) else {
                continue;
            };

            let Some(widget) = self.nodes.get(id).and_then(|n| n.widget.as_ref()) else {
                continue;
            };
            if !widget.can_scroll_descendant_into_view() {
                continue;
            }

            let result = self.with_widget_mut(id, |widget, tree| {
                let mut cx = crate::widget::ScrollIntoViewCx {
                    app,
                    node: id,
                    window: tree.window,
                    bounds,
                };
                widget.scroll_descendant_into_view(&mut cx, descendant_bounds)
            });

            if let crate::widget::ScrollIntoViewResult::Handled {
                did_scroll,
                propagated_bounds,
            } = result
            {
                if did_scroll {
                    any_scrolled = true;
                    self.mark_invalidation(id, Invalidation::HitTest);
                    if self.focus == Some(target)
                        && self
                            .nodes
                            .get(target)
                            .and_then(|n| n.widget.as_ref())
                            .is_some_and(|w| w.is_text_input())
                    {
                        self.mark_invalidation(target, Invalidation::Paint);
                    }
                    self.request_redraw_coalesced(app);
                }
                // Once an ancestor handles the request, outer ancestors should align that
                // ancestor's effective viewport rather than the original deep target bounds.
                descendant_bounds = propagated_bounds.unwrap_or(bounds);
                continue;
            }
        }

        any_scrolled
    }

    pub fn scroll_by(&mut self, app: &mut H, target: NodeId, delta: Point) -> bool {
        let Some(bounds) = self.nodes.get(target).map(|n| n.bounds) else {
            return false;
        };

        let result = self.with_widget_mut(target, |widget, tree| {
            let mut cx = crate::widget::ScrollByCx {
                app,
                node: target,
                window: tree.window,
                bounds,
            };
            widget.scroll_by(&mut cx, delta)
        });

        match result {
            crate::widget::ScrollByResult::NotHandled => false,
            crate::widget::ScrollByResult::Handled { did_scroll } => {
                if did_scroll {
                    self.mark_invalidation(target, Invalidation::HitTestOnly);
                    self.request_redraw_coalesced(app);
                }
                did_scroll
            }
        }
    }
}