fission_core/

runtime.rs

use crate::action::{Action, ActionEnvelope, ActionId, GlobalState};
use crate::async_runtime::ServiceStopPayload;
use crate::effect::{
    ActionInput, Effect, EffectEnvelope, RuntimeEffect, ScrollAlignment, ScrollAxis,
    ScrollBehavior, ScrollIntoViewRequest,
};
use crate::env::{RuntimeState, VideoStatus};
use crate::registry::{
    ActionRegistry, ResourcePolicy, RuntimeResourceDeclaration, RuntimeResourceKind, TimerResource,
    VideoRegistration,
};
use crate::ui::custom_render::downcast_render_object;
use crate::{BoxedReducer, EffectCallbackRegistry};
use crate::{
    Clipboard, Clock, CurrentTime, ImeHandler, InputEvent, KeyCode, KeyEvent, PointerButton,
    PointerEvent, ResourceExecutionContext,
};
use anyhow::{anyhow, Context, Result};
use fission_diagnostics::prelude as diag;
use fission_ir::{CoreIR, FlexDirection, FocusPolicy, LayoutOp, Op, WidgetId};
use fission_layout::{LayoutPoint, LayoutRect, LayoutSize, LayoutSnapshot, TextMeasurer};
use glam::{Mat4, Vec4};
use serde_json;
use std::any::TypeId;
use std::collections::{HashMap, HashSet};
use std::sync::Arc;

#[derive(Debug, Default, Clone)]
pub struct TickResult {
    pub changed_motions: Vec<(WidgetId, crate::MotionPropertyId)>,
    /// Number of timer resource actions dispatched during this tick.
    ///
    /// Shells use this to rebuild after timer reducers mutate application state.
    pub resource_actions_dispatched: usize,
}

#[derive(Debug, Clone)]
enum ActiveResourceKind {
    Job,
    Service {
        service_name: String,
        slot_key: String,
    },
    Timer {
        interval_ms: u64,
        payload: Vec<u8>,
        on_tick: Option<ActionEnvelope>,
        next_fire_at: CurrentTime,
    },
}

#[derive(Debug, Clone)]
struct ActiveResource {
    generation: u64,
    deps: Option<Vec<u8>>,
    policy: ResourcePolicy,
    kind: ActiveResourceKind,
}

#[derive(Debug, Clone)]
struct PendingScrollIntoView {
    request: ScrollIntoViewRequest,
    retries_remaining: u8,
}

#[derive(Debug, Clone, Copy)]
struct FocusBarrierFrame {
    id: WidgetId,
    restore_target: Option<WidgetId>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ScrollIntoViewOutcome {
    Applied { changed: bool },
    Retry,
    Ignored,
}

/// The core runtime that owns application state, reducers, and the effect queue.
///
/// `Runtime` is the single entry point for the action/reducer pipeline. Platform
/// shells create one `Runtime`, register their `GlobalState`, build the widget tree
/// each frame, absorb the resulting [`ActionRegistry`], and call
/// [`Runtime::handle_input`] to process user events.
///
/// # Lifecycle
///
/// ```text
/// 1. runtime = Runtime::default()
///        .with_measurer(measurer)
///        .with_clipboard(clipboard);
/// 2. runtime.add_global_state(Box::new(MyState::default()))?;
/// 3. loop {
///        let mut ctx = BuildCtx::new();
///        let tree = fission_core::build::enter(&mut ctx, &view, || MyRoot.into());
///        runtime.clear_reducers();
///        runtime.absorb_registry(ctx.registry);
///        // lower tree -> IR -> layout -> render
///        runtime.handle_input(event, &ir, &layout)?;
///        runtime.tick(dt)?;
///    }
/// ```
///
/// # Example
///
/// ```rust,ignore
/// let mut runtime = Runtime::default();
/// runtime.add_global_state(Box::new(Counter { count: 0 }))?;
/// runtime.tick(16)?;
/// ```
pub struct Runtime {
    /// Per-frame reducers, cleared and re-populated every frame via
    /// [`absorb_registry`](Runtime::absorb_registry).
    pub(crate) reducers: HashMap<ActionId, Vec<BoxedReducer>>,
    /// Persistent reducers that survive [`clear_reducers`](Runtime::clear_reducers)
    /// calls, installed once at app startup.
    pub(crate) persistent_reducers: HashMap<ActionId, Vec<BoxedReducer>>,
    /// One-shot reducers bound by reducers to async effect completions.
    effect_callbacks: Arc<EffectCallbackRegistry>,
    /// Type-indexed application state store.
    pub app_states: HashMap<TypeId, Box<dyn GlobalState>>,
    /// Mutable runtime state (interaction, scroll, text editing, motions).
    pub runtime_state: RuntimeState,
    /// Platform-provided text measurer for layout.
    pub measurer: Option<Arc<dyn TextMeasurer>>,
    /// Platform-provided clipboard backend.
    pub clipboard_backend: Option<Arc<dyn Clipboard>>,
    /// Platform-provided IME (Input Method Editor) handler.
    pub ime_handler: Option<Arc<dyn ImeHandler>>,
    /// Text-editing conventions for the host that owns this runtime.
    pub editing_convention: crate::input::TextEditingConvention,
    /// Effects emitted by reducers, awaiting platform execution.
    pub pending_effects: Vec<EffectEnvelope>,
    /// Post-layout scroll requests that need computed geometry before applying.
    pending_scroll_into_view: Vec<PendingScrollIntoView>,
    /// Shell navigation commands waiting for the host adapter.
    pending_navigation: Vec<crate::NavigationCommand>,
    /// Selection commands waiting for a lowered tree to resolve their members.
    pending_selection_regions: Vec<(WidgetId, crate::SelectionRegionCommand)>,
    pending_text_editing: Vec<(WidgetId, crate::TextEditingCommand)>,
    pending_text_scroll: Vec<(WidgetId, crate::TextScrollCommand)>,
    pending_text_form_validation: Vec<String>,
    /// Active focus barriers and the targets restored as each barrier closes.
    focus_barriers: Vec<FocusBarrierFrame>,
    /// Monotonically increasing counter for deterministic request id generation.
    pub next_req_id: u64,
    /// Declarative runtime resources that currently exist.
    active_resources: HashMap<String, ActiveResource>,
    /// Monotonically increasing generation counter for runtime resources.
    next_resource_generation: u64,
}

impl Default for Runtime {
    fn default() -> Self {
        let mut runtime = Self {
            reducers: HashMap::new(),
            persistent_reducers: HashMap::new(),
            effect_callbacks: Arc::new(EffectCallbackRegistry::new()),
            app_states: HashMap::new(),
            runtime_state: RuntimeState::default(),
            measurer: None,
            clipboard_backend: None,
            ime_handler: None,
            editing_convention: crate::input::TextEditingConvention::default(),
            pending_effects: Vec::new(),
            pending_scroll_into_view: Vec::new(),
            pending_navigation: Vec::new(),
            pending_selection_regions: Vec::new(),
            pending_text_editing: Vec::new(),
            pending_text_scroll: Vec::new(),
            pending_text_form_validation: Vec::new(),
            focus_barriers: Vec::new(),
            next_req_id: 0,
            active_resources: HashMap::new(),
            next_resource_generation: 1,
        };

        runtime
            .add_global_state(Box::new(runtime.runtime_state.local_widget_state.clone()))
            .expect("Failed to add local widget state store");

        runtime
            .add_global_state(Box::new(Clock::default()))
            .expect("Failed to add Clock state");

        runtime.register_base_reducers();

        runtime
    }
}

impl Runtime {
    pub fn with_measurer(mut self, measurer: Arc<dyn TextMeasurer>) -> Self {
        self.measurer = Some(measurer);
        self
    }

    pub fn with_clipboard(mut self, backend: Arc<dyn Clipboard>) -> Self {
        self.clipboard_backend = Some(backend);
        self
    }

    pub fn with_ime_handler(mut self, handler: Arc<dyn ImeHandler>) -> Self {
        self.ime_handler = Some(handler);
        self
    }

    /// Reconciles keyboard focus with the focus barriers in a newly lowered IR.
    ///
    /// New barriers capture focus, nested barriers retain a restoration chain,
    /// and closing barriers restores the most recent valid target.
    pub fn reconcile_focus(&mut self, ir: &CoreIR) -> Result<bool> {
        use crate::hit_test::{
            focus_barriers_in_tree_order, get_all_focusable_nodes, is_descendant_or_self,
            is_enabled_focus_node, preferred_focus_node_in_scope,
        };

        let active_barriers = focus_barriers_in_tree_order(ir);
        let common_prefix = self
            .focus_barriers
            .iter()
            .map(|frame| frame.id)
            .zip(active_barriers.iter().copied())
            .take_while(|(tracked, active)| tracked == active)
            .count();
        let popped_any = self.focus_barriers.len() > common_prefix;
        let mut restore_target = None;
        while self.focus_barriers.len() > common_prefix {
            restore_target = self
                .focus_barriers
                .pop()
                .and_then(|frame| frame.restore_target);
        }

        for (index, barrier_id) in active_barriers
            .iter()
            .copied()
            .enumerate()
            .skip(common_prefix)
        {
            let restore = if index == 0 {
                restore_target
                    .filter(|id| is_enabled_focus_node(ir, *id))
                    .or_else(|| {
                        self.runtime_state
                            .interaction
                            .focused
                            .filter(|id| is_enabled_focus_node(ir, *id))
                    })
            } else {
                let parent_barrier_id = active_barriers[index - 1];
                self.runtime_state
                    .interaction
                    .focused
                    .filter(|id| {
                        is_enabled_focus_node(ir, *id)
                            && is_descendant_or_self(ir, *id, parent_barrier_id)
                            && !is_descendant_or_self(ir, *id, barrier_id)
                    })
                    .or_else(|| preferred_focus_node_in_scope(ir, parent_barrier_id))
            };
            self.focus_barriers.push(FocusBarrierFrame {
                id: barrier_id,
                restore_target: restore,
            });
        }

        let current = self.runtime_state.interaction.focused;
        let next = if let Some(barrier_id) = active_barriers.last().copied() {
            current
                .filter(|id| {
                    is_enabled_focus_node(ir, *id) && is_descendant_or_self(ir, *id, barrier_id)
                })
                .or_else(|| {
                    restore_target.filter(|id| {
                        is_enabled_focus_node(ir, *id) && is_descendant_or_self(ir, *id, barrier_id)
                    })
                })
                .or_else(|| preferred_focus_node_in_scope(ir, barrier_id))
        } else if popped_any {
            restore_target
                .filter(|id| is_enabled_focus_node(ir, *id))
                .or_else(|| {
                    let nodes = get_all_focusable_nodes(ir);
                    nodes
                        .iter()
                        .copied()
                        .find(|id| {
                            matches!(
                                ir.nodes.get(id).map(|node| &node.op),
                                Some(Op::Semantics(semantics)) if semantics.autofocus
                            )
                        })
                        .or_else(|| nodes.first().copied())
                })
        } else {
            current.filter(|id| is_enabled_focus_node(ir, *id))
        };

        if current == next {
            return Ok(false);
        }

        self.set_focused_widget(ir, next, crate::TextEditSource::Programmatic)
    }

    pub fn caret_from_point_in_text(
        &self,
        value: &str,
        font_size: f32,
        viewport_x: f32,
        viewport_w: f32,
        content_w: f32,
        scroll_offset: f32,
        point_x: f32,
    ) -> usize {
        crate::input::text::caret_from_point_in_text(
            self.measurer.as_ref(),
            value,
            font_size,
            viewport_x,
            viewport_w,
            content_w,
            scroll_offset,
            point_x,
        )
    }

    // Helper for manual reducer registration (internal use)
    pub fn register_reducer<S: GlobalState + 'static>(
        &mut self,
        action_id: ActionId,
        reducer_fn: crate::action::Reducer<S>,
    ) -> Result<()> {
        let state_type_id = TypeId::of::<S>();

        // Wrap legacy 3-arg reducer into 5-arg BoxedReducer
        let boxed_reducer: BoxedReducer = Box::new(
            move |app_states: &mut HashMap<TypeId, Box<dyn GlobalState>>,
                  action: &ActionEnvelope,
                  target: WidgetId,
                  _effects: &mut Vec<EffectEnvelope>,
                  _input: &ActionInput,
                  _callback_registry|
                  -> Result<()> {
                if let Some(state_box) = app_states.get_mut(&state_type_id) {
                    let concrete_state = state_box.downcast_mut::<S>().ok_or_else(|| {
                        anyhow!("Failed to downcast GlobalState to concrete type for reducer")
                    })?;
                    reducer_fn(concrete_state, action, target.into())
                } else {
                    anyhow::bail!("Target GlobalState for reducer not found in runtime.");
                }
            },
        );

        self.reducers
            .entry(action_id)
            .or_default()
            .push(boxed_reducer);
        Ok(())
    }

    pub fn register_base_reducers(&mut self) {
        use crate::{AdvanceTo, Tick, ADVANCE_TO_ACTION_ID, TICK_ACTION_ID};

        self.register_reducer::<Clock>(
            *TICK_ACTION_ID,
            |state: &mut Clock, action: &ActionEnvelope, _target| {
                let tick_action: Tick = serde_json::from_slice(&action.payload)
                    .map_err(|e| anyhow!("Failed to deserialize Tick: {}", e))?;
                state.advance_by(tick_action.dt)
            },
        )
        .expect("Failed to register Tick reducer");

        self.register_reducer::<Clock>(
            *ADVANCE_TO_ACTION_ID,
            |state: &mut Clock, action: &ActionEnvelope, _target| {
                let advance_action: AdvanceTo = serde_json::from_slice(&action.payload)
                    .map_err(|e| anyhow!("Failed to deserialize AdvanceTo: {}", e))?;
                state.set_to(advance_action.time)
            },
        )
        .expect("Failed to register AdvanceTo reducer");
    }

    pub fn clear_reducers(&mut self) {
        self.reducers.clear();
        self.register_base_reducers();
    }

    pub fn absorb_registry<S: GlobalState>(&mut self, registry: ActionRegistry<S>) {
        let new_reducers = registry.into_runtime_reducers();
        for (id, mut list) in new_reducers {
            self.reducers.entry(id).or_default().append(&mut list);
        }
    }

    /// Registers reducers that should survive `clear_reducers()` calls.
    ///
    /// This is intended for app-level "global" handlers (e.g. system effects) that
    /// are installed once at app startup, while per-frame widget handlers are
    /// regenerated every frame via `BuildCtx` and `absorb_registry`.
    pub fn absorb_persistent_registry<S: GlobalState>(&mut self, registry: ActionRegistry<S>) {
        let new_reducers = registry.into_runtime_reducers();
        for (id, mut list) in new_reducers {
            self.persistent_reducers
                .entry(id)
                .or_default()
                .append(&mut list);
        }
    }

    pub fn clock(&self) -> &Clock {
        self.get_global_state::<Clock>()
            .expect("Clock state must always be present")
    }

    pub fn get_global_state<S: GlobalState + 'static>(&self) -> Option<&S> {
        self.app_states
            .get(&TypeId::of::<S>())
            .and_then(|s_box| s_box.downcast_ref::<S>())
    }

    pub fn get_global_state_mut<S: GlobalState + 'static>(&mut self) -> Option<&mut S> {
        self.app_states
            .get_mut(&TypeId::of::<S>())
            .and_then(|s_box| s_box.downcast_mut::<S>())
    }

    pub fn add_global_state<S: GlobalState + 'static>(&mut self, state: Box<S>) -> Result<()> {
        let type_id = TypeId::of::<S>();
        if self.app_states.insert(type_id, state).is_some() {
            anyhow::bail!("Global state of this type already registered.");
        }
        Ok(())
    }

    pub fn with_global_state<S: GlobalState + 'static>(mut self, state: S) -> Self {
        self.app_states.insert(TypeId::of::<S>(), Box::new(state));
        self
    }

    #[doc(hidden)]
    pub fn get_app_state<S: GlobalState + 'static>(&self) -> Option<&S> {
        self.get_global_state::<S>()
    }

    #[doc(hidden)]
    pub fn get_app_state_mut<S: GlobalState + 'static>(&mut self) -> Option<&mut S> {
        self.get_global_state_mut::<S>()
    }

    #[doc(hidden)]
    pub fn add_app_state<S: GlobalState + 'static>(&mut self, state: Box<S>) -> Result<()> {
        self.add_global_state(state)
    }

    pub fn dispatch(&mut self, action: ActionEnvelope, target: WidgetId) -> Result<()> {
        self.dispatch_with_input(action, target, &ActionInput::None)
    }

    fn enqueue_effect(&mut self, mut envelope: EffectEnvelope) {
        envelope.req_id = self.next_req_id;
        self.next_req_id += 1;
        self.pending_effects.push(envelope);
    }

    /// Rejects every queued host effect and its one-shot completion callbacks.
    ///
    /// This is only for shells that intentionally do not execute any effects
    /// produced by a dispatch. Executing or retaining an effect after calling
    /// this method would make its completion callback unavailable.
    ///
    /// Returns the total number of discarded effect envelopes and callbacks.
    #[doc(hidden)]
    pub fn discard_pending_effects(&mut self) -> usize {
        let discarded = self.pending_effects.len() + self.effect_callbacks.clear();
        self.pending_effects.clear();
        discarded
    }

    pub fn dispatch_with_input(
        &mut self,
        action: ActionEnvelope,
        target: WidgetId,
        input: &ActionInput,
    ) -> Result<()> {
        self.dispatch_node_with_input(action, target.into(), input)
    }

    fn dispatch_node(&mut self, action: ActionEnvelope, target: WidgetId) -> Result<()> {
        self.dispatch_node_with_input(action, target, &ActionInput::None)
    }

    fn dispatch_node_with_input(
        &mut self,
        action: ActionEnvelope,
        target: WidgetId,
        input: &ActionInput,
    ) -> Result<()> {
        let action_id = action.id;
        let result = self.try_dispatch_node_with_input(action, target, input);
        if let Err(error) = &result {
            crate::registry::emit_action_dispatch_failure(action_id, target, error);
        }
        result
    }

    fn try_dispatch_node_with_input(
        &mut self,
        action: ActionEnvelope,
        target: WidgetId,
        input: &ActionInput,
    ) -> Result<()> {
        diag::emit(
            diag::DiagCategory::Input,
            diag::DiagLevel::Debug,
            diag::DiagEventKind::InputEvent {
                kind: "dispatch_start".into(),
                target: Some(target.as_u128()),
                position: None,
            },
        );

        if action.id == crate::NavigationRequested::static_id() {
            let request: crate::NavigationRequested = serde_json::from_slice(&action.payload)
                .context("failed to decode built-in navigation request")?;
            self.pending_navigation.push(request.command);
            return Ok(());
        }

        // Delegate video actions to media module
        if crate::media::handle_video_action(&mut self.runtime_state.video, &action)? {
            return Ok(());
        }

        let action = if let Some(resolution) =
            crate::scoped_action_handlers::dispatch_scoped_action_handler(&action, target, input)?
        {
            match resolution {
                crate::scoped_action_handlers::ScopedActionResolution::Handled => return Ok(()),
                crate::scoped_action_handlers::ScopedActionResolution::Forward(forwarded) => {
                    if crate::media::handle_video_action(&mut self.runtime_state.video, &forwarded)?
                    {
                        return Ok(());
                    }
                    forwarded
                }
            }
        } else {
            action
        };

        let action_id = action.id;

        // Collect effects from this dispatch (both persistent and per-frame reducers).
        let mut effects = Vec::new();
        let callback_registry = self.effect_callbacks.clone();

        let mut callback_reducers = callback_registry.take(action_id);
        for reducer_wrapper in callback_reducers.iter_mut() {
            reducer_wrapper(
                &mut self.app_states,
                &action,
                target,
                &mut effects,
                input,
                &callback_registry,
            )?;
        }

        if let Some(reducers) = self.persistent_reducers.get_mut(&action_id) {
            diag::emit(
                diag::DiagCategory::Input,
                diag::DiagLevel::Debug,
                diag::DiagEventKind::InputEvent {
                    kind: format!("persistent_reducers:{}", reducers.len()),
                    target: Some(target.as_u128()),
                    position: None,
                },
            );

            let mut temp_reducers: Vec<BoxedReducer> = reducers.drain(..).collect();
            let dispatch_result = temp_reducers.iter_mut().try_for_each(|reducer_wrapper| {
                reducer_wrapper(
                    &mut self.app_states,
                    &action,
                    target,
                    &mut effects,
                    input,
                    &callback_registry,
                )
            });
            reducers.extend(temp_reducers);
            dispatch_result?;
        }

        if let Some(reducers) = self.reducers.get_mut(&action_id) {
            diag::emit(
                diag::DiagCategory::Input,
                diag::DiagLevel::Debug,
                diag::DiagEventKind::InputEvent {
                    kind: format!("reducers:{}", reducers.len()),
                    target: Some(target.as_u128()),
                    position: None,
                },
            );

            let mut temp_reducers: Vec<BoxedReducer> = reducers.drain(..).collect();
            let dispatch_result = temp_reducers.iter_mut().try_for_each(|reducer_wrapper| {
                reducer_wrapper(
                    &mut self.app_states,
                    &action,
                    target,
                    &mut effects,
                    input,
                    &callback_registry,
                )
            });
            reducers.extend(temp_reducers);
            dispatch_result?;
        }

        for envelope in effects {
            self.enqueue_effect(envelope);
        }

        diag::emit(
            diag::DiagCategory::Input,
            diag::DiagLevel::Debug,
            diag::DiagEventKind::InputEvent {
                kind: "dispatch_end".into(),
                target: Some(target.as_u128()),
                position: None,
            },
        );
        Ok(())
    }

    pub fn tick(&mut self, dt: CurrentTime) -> Result<TickResult> {
        use crate::Tick;
        let action = Tick { dt };
        let envelope: ActionEnvelope = action.into();
        self.dispatch_node(envelope, WidgetId::derived(0, &[0]))?;

        let resource_actions_dispatched = self.tick_resource_timers()?;

        let current_time = self.clock().current_time();
        let changed_motions =
            crate::motion::tick_motion(&mut self.runtime_state.motion, current_time);
        Ok(TickResult {
            changed_motions,
            resource_actions_dispatched,
        })
    }

    fn tick_resource_timers(&mut self) -> Result<usize> {
        let now = self.clock().current_time();
        let mut ticks = Vec::new();

        for resource in self.active_resources.values_mut() {
            if let ActiveResourceKind::Timer {
                interval_ms,
                payload,
                on_tick,
                next_fire_at,
            } = &mut resource.kind
            {
                let Some(action) = on_tick.clone() else {
                    continue;
                };

                let interval_ms = (*interval_ms).max(1);
                while now >= *next_fire_at {
                    ticks.push((action.clone(), payload.clone()));
                    *next_fire_at = next_fire_at.saturating_add(interval_ms);
                }
            }
        }

        let dispatched = ticks.len();
        for (action, payload) in ticks {
            self.dispatch_node_with_input(
                action,
                WidgetId::derived(0, &[0]),
                &ActionInput::TimerTick { payload },
            )?;
        }

        Ok(dispatched)
    }

    pub fn sync_motion_declarations(
        &mut self,
        declarations: &[crate::MotionDeclaration],
        layout: Option<&LayoutSnapshot>,
    ) -> Vec<(WidgetId, crate::MotionPropertyId)> {
        let current_time = self.clock().current_time();
        let snapshot = self.runtime_state.clone();
        let result = crate::motion::sync_motion_declarations(
            &mut self.runtime_state.motion,
            declarations,
            &snapshot,
            layout,
            current_time,
        );
        result.changed
    }

    pub fn sync_video_nodes(&mut self, registrations: &[VideoRegistration]) {
        let mut seen: HashSet<WidgetId> = HashSet::new();

        for reg in registrations {
            seen.insert(reg.node_id);
            let entry = self
                .runtime_state
                .video
                .states
                .entry(reg.node_id)
                .or_insert_with(crate::env::VideoState::default);
            entry.asset_source = reg.source.clone();
            entry.looped = reg.loop_playback;
            entry.audio = reg.audio.clone();
            if reg.autoplay && entry.status == VideoStatus::Stopped {
                entry.status = VideoStatus::Playing;
            }
        }

        self.runtime_state
            .video
            .states
            .retain(|node_id, _| seen.contains(node_id));
    }

    pub fn sync_web_nodes(&mut self, registrations: &[crate::registry::WebRegistration]) {
        let mut seen: HashSet<WidgetId> = HashSet::new();

        for reg in registrations {
            seen.insert(reg.node_id);
            let entry = self
                .runtime_state
                .web
                .states
                .entry(reg.node_id)
                .or_insert_with(crate::env::WebState::default);

            // Only update URL if it changes to avoid reload loops
            if entry.url != reg.url {
                entry.url = reg.url.clone();
                entry.loading = true; // Assume loading starts
            }
            entry.user_agent = reg.user_agent.clone();
        }

        self.runtime_state
            .web
            .states
            .retain(|node_id, _| seen.contains(node_id));
    }

    /// Queues a runtime effect that must be resolved by the core runtime.
    ///
    /// Shells call this for effects that require runtime-owned state or a
    /// post-layout pass instead of a host capability executor.
    pub fn queue_runtime_effect(&mut self, effect: RuntimeEffect) -> bool {
        match effect {
            RuntimeEffect::ScrollIntoView(request) => {
                self.queue_scroll_into_view(request);
                true
            }
            RuntimeEffect::Navigate(command) => {
                self.pending_navigation.push(command);
                true
            }
            RuntimeEffect::SelectionRegion { region_id, command } => {
                self.pending_selection_regions.push((region_id, command));
                true
            }
            RuntimeEffect::TextEditing { input_id, command } => {
                self.pending_text_editing.push((input_id, command));
                true
            }
            RuntimeEffect::TextScroll { input_id, command } => {
                self.pending_text_scroll.push((input_id, command));
                true
            }
            RuntimeEffect::TextFormValidation { form_id } => {
                self.pending_text_form_validation.push(form_id);
                true
            }
            RuntimeEffect::Cancel { .. } | RuntimeEffect::ReleaseResource { .. } => false,
        }
    }

    /// Takes navigation commands queued since the previous shell turn.
    #[doc(hidden)]
    pub fn take_pending_navigation(&mut self) -> Vec<crate::NavigationCommand> {
        std::mem::take(&mut self.pending_navigation)
    }

    /// Queues a post-layout request to reveal a widget in a scroll container.
    pub fn queue_scroll_into_view(&mut self, request: ScrollIntoViewRequest) {
        self.pending_scroll_into_view.push(PendingScrollIntoView {
            request,
            retries_remaining: 1,
        });
    }

    fn drain_post_layout_effects(&mut self) {
        let pending = std::mem::take(&mut self.pending_effects);

        for env in pending {
            let EffectEnvelope {
                req_id,
                effect,
                on_ok,
                on_err,
                service_bindings,
                resource,
            } = env;

            match effect {
                Effect::Runtime(RuntimeEffect::ScrollIntoView(request)) => {
                    self.queue_scroll_into_view(request);
                }
                Effect::Runtime(RuntimeEffect::SelectionRegion { region_id, command }) => {
                    self.pending_selection_regions.push((region_id, command));
                }
                Effect::Runtime(RuntimeEffect::TextEditing { input_id, command }) => {
                    self.pending_text_editing.push((input_id, command));
                }
                Effect::Runtime(RuntimeEffect::TextScroll { input_id, command }) => {
                    self.pending_text_scroll.push((input_id, command));
                }
                Effect::Runtime(RuntimeEffect::TextFormValidation { form_id }) => {
                    self.pending_text_form_validation.push(form_id);
                }
                retained => self.pending_effects.push(EffectEnvelope {
                    req_id,
                    effect: retained,
                    on_ok,
                    on_err,
                    service_bindings,
                    resource,
                }),
            }
        }
    }

    fn apply_pending_scroll_into_view(&mut self, ir: &CoreIR, layout: &LayoutSnapshot) -> bool {
        self.drain_post_layout_effects();

        let mut needs_follow_up_frame = false;
        let pending = std::mem::take(&mut self.pending_scroll_into_view);

        for mut pending_request in pending {
            match self.apply_scroll_into_view(&pending_request.request, ir, layout) {
                ScrollIntoViewOutcome::Applied { changed } => {
                    needs_follow_up_frame |= changed;
                }
                ScrollIntoViewOutcome::Retry if pending_request.retries_remaining > 0 => {
                    pending_request.retries_remaining -= 1;
                    self.pending_scroll_into_view.push(pending_request);
                    needs_follow_up_frame = true;
                }
                ScrollIntoViewOutcome::Retry | ScrollIntoViewOutcome::Ignored => {}
            }
        }

        needs_follow_up_frame
    }

    fn apply_scroll_into_view(
        &mut self,
        request: &ScrollIntoViewRequest,
        ir: &CoreIR,
        layout: &LayoutSnapshot,
    ) -> ScrollIntoViewOutcome {
        let Some(target_geom) = layout.get_node_geometry(request.target) else {
            Self::emit_scroll_into_view_diag("missing_target", request, None);
            return ScrollIntoViewOutcome::Retry;
        };

        let Some(container_id) = self.resolve_scroll_container(request, ir, layout) else {
            Self::emit_scroll_into_view_diag("missing_container", request, None);
            return ScrollIntoViewOutcome::Retry;
        };

        if !Self::is_descendant_or_self(ir, request.target, container_id) {
            Self::emit_scroll_into_view_diag("target_not_descendant", request, Some(container_id));
            return ScrollIntoViewOutcome::Ignored;
        }

        let Some(container_geom) = layout.get_node_geometry(container_id) else {
            Self::emit_scroll_into_view_diag(
                "missing_container_layout",
                request,
                Some(container_id),
            );
            return ScrollIntoViewOutcome::Retry;
        };

        let Some(direction) = Self::scroll_direction(ir, container_id) else {
            Self::emit_scroll_into_view_diag("not_scroll_container", request, Some(container_id));
            return ScrollIntoViewOutcome::Ignored;
        };

        if !Self::axis_matches(request.axis, direction) {
            Self::emit_scroll_into_view_diag("axis_mismatch", request, Some(container_id));
            return ScrollIntoViewOutcome::Ignored;
        }

        if matches!(request.behavior, ScrollBehavior::Smooth) {
            Self::emit_scroll_into_view_diag(
                "smooth_resolved_as_instant",
                request,
                Some(container_id),
            );
        }

        let current_offset = self.runtime_state.scroll.get_offset(container_id);
        let new_offset = match direction {
            FlexDirection::Column => Self::compute_scroll_offset(
                current_offset,
                target_geom.rect.y() - container_geom.rect.y(),
                target_geom.rect.height(),
                container_geom.rect.height(),
                container_geom.content_size.height,
                request.padding[2],
                request.padding[3],
                request.alignment,
                request.if_needed,
            ),
            FlexDirection::Row => Self::compute_scroll_offset(
                current_offset,
                target_geom.rect.x() - container_geom.rect.x(),
                target_geom.rect.width(),
                container_geom.rect.width(),
                container_geom.content_size.width,
                request.padding[0],
                request.padding[1],
                request.alignment,
                request.if_needed,
            ),
        };

        if (new_offset - current_offset).abs() > f32::EPSILON {
            self.runtime_state
                .scroll
                .set_offset(container_id, new_offset);
            ScrollIntoViewOutcome::Applied { changed: true }
        } else {
            ScrollIntoViewOutcome::Applied { changed: false }
        }
    }

    fn resolve_scroll_container(
        &self,
        request: &ScrollIntoViewRequest,
        ir: &CoreIR,
        layout: &LayoutSnapshot,
    ) -> Option<WidgetId> {
        if let Some(container) = request.container {
            return ir
                .nodes
                .contains_key(&container)
                .then_some(container)
                .filter(|id| layout.get_node_geometry(*id).is_some());
        }

        let mut current = ir.nodes.get(&request.target)?.parent;
        while let Some(node_id) = current {
            if let Some(direction) = Self::scroll_direction(ir, node_id) {
                if Self::axis_matches(request.axis, direction)
                    && layout.get_node_geometry(node_id).is_some()
                {
                    return Some(node_id);
                }
            }
            current = ir.nodes.get(&node_id).and_then(|node| node.parent);
        }

        None
    }

    fn scroll_direction(ir: &CoreIR, node_id: WidgetId) -> Option<FlexDirection> {
        match ir.nodes.get(&node_id).map(|node| &node.op) {
            Some(Op::Layout(LayoutOp::Scroll { direction, .. })) => Some(*direction),
            _ => None,
        }
    }

    fn axis_matches(axis: ScrollAxis, direction: FlexDirection) -> bool {
        matches!(
            (axis, direction),
            (ScrollAxis::Both, _)
                | (ScrollAxis::Vertical, FlexDirection::Column)
                | (ScrollAxis::Horizontal, FlexDirection::Row)
        )
    }

    fn is_descendant_or_self(ir: &CoreIR, target: WidgetId, ancestor: WidgetId) -> bool {
        let mut current = Some(target);
        while let Some(node_id) = current {
            if node_id == ancestor {
                return true;
            }
            current = ir.nodes.get(&node_id).and_then(|node| node.parent);
        }
        false
    }

    fn compute_scroll_offset(
        current_offset: f32,
        target_content_start: f32,
        target_size: f32,
        viewport_size: f32,
        content_size: f32,
        padding_start: f32,
        padding_end: f32,
        alignment: ScrollAlignment,
        if_needed: bool,
    ) -> f32 {
        let current_offset = Self::finite_or_zero(current_offset).max(0.0);
        let viewport_size = Self::finite_or_zero(viewport_size).max(0.0);
        let content_size = Self::finite_or_zero(content_size).max(0.0);
        let target_size = Self::finite_or_zero(target_size).max(0.0);
        let padding_start = Self::finite_or_zero(padding_start).max(0.0);
        let padding_end = Self::finite_or_zero(padding_end).max(0.0);
        let max_offset = (content_size - viewport_size).max(0.0);

        if viewport_size <= f32::EPSILON || max_offset <= f32::EPSILON {
            return 0.0;
        }

        let target_start = Self::finite_or_zero(target_content_start);
        let target_end = target_start + target_size;
        let reveal_start = target_start - padding_start;
        let reveal_end = target_end + padding_end;
        let viewport_start = current_offset;
        let viewport_end = current_offset + viewport_size;

        if if_needed && reveal_start >= viewport_start && reveal_end <= viewport_end {
            return current_offset.min(max_offset);
        }

        let desired = match alignment {
            ScrollAlignment::Start => reveal_start,
            ScrollAlignment::Center => {
                let padded_viewport = (viewport_size - padding_start - padding_end).max(0.0);
                target_start - padding_start - (padded_viewport - target_size) * 0.5
            }
            ScrollAlignment::End => reveal_end - viewport_size,
            ScrollAlignment::Nearest => {
                if reveal_end - reveal_start > viewport_size {
                    reveal_start
                } else if reveal_start < viewport_start {
                    reveal_start
                } else if reveal_end > viewport_end {
                    reveal_end - viewport_size
                } else {
                    current_offset
                }
            }
            ScrollAlignment::Fraction(fraction) => {
                let fraction = Self::finite_or_zero(fraction).clamp(0.0, 1.0);
                let padded_viewport = (viewport_size - padding_start - padding_end).max(0.0);
                target_start - padding_start - (padded_viewport - target_size) * fraction
            }
        };

        Self::finite_or_zero(desired).clamp(0.0, max_offset)
    }

    fn finite_or_zero(value: f32) -> f32 {
        if value.is_finite() {
            value
        } else {
            0.0
        }
    }

    fn emit_scroll_into_view_diag(
        kind: &'static str,
        request: &ScrollIntoViewRequest,
        container: Option<WidgetId>,
    ) {
        diag::emit(
            diag::DiagCategory::Input,
            diag::DiagLevel::Debug,
            diag::DiagEventKind::InputEvent {
                kind: format!(
                    "scroll_into_view:{kind}:target={:?}:container={:?}",
                    request.target,
                    container.or(request.container)
                ),
                target: Some(request.target.as_u128()),
                position: None,
            },
        );
    }

    /// Reconciles runtime-owned widget state against the current lowered tree.
    ///
    /// Shells must call this after replacing the IR and before computing layout
    /// so an unmounted widget's state cannot affect the replacement tree's
    /// first frame.
    pub fn reconcile_ir(&mut self, ir: &CoreIR) {
        self.runtime_state.viewport.reconcile(ir);
        crate::selection::reconcile_selection_state(&mut self.runtime_state.selectable_text, ir);
        let active_scroll_nodes: HashSet<WidgetId> = ir
            .nodes
            .iter()
            .filter_map(|(id, node)| match node.op {
                Op::Layout(LayoutOp::Scroll { .. }) => Some(*id),
                _ => None,
            })
            .collect();
        self.runtime_state
            .scroll
            .retain_active(&active_scroll_nodes);
        if self
            .runtime_state
            .gesture
            .scrollbar_drag
            .is_some_and(|drag| !active_scroll_nodes.contains(&drag.node_id))
        {
            self.runtime_state.gesture.scrollbar_drag = None;
        }
    }

    /// Runs runtime work that depends on a freshly computed layout snapshot.
    ///
    /// Returns `true` when the hook changed runtime state and the shell should
    /// schedule another frame.
    pub fn post_layout_hook(&mut self, ir: &CoreIR, layout: &LayoutSnapshot) -> bool {
        // Preserve correct behavior for direct Runtime embedders that have not
        // yet adopted the pre-layout reconciliation hook. Production shells
        // call `reconcile_ir` before layout, making this pass idempotent.
        self.reconcile_ir(ir);
        let mut needs_follow_up_frame = self.apply_pending_scroll_into_view(ir, layout);
        needs_follow_up_frame |= self.apply_pending_selection_regions(ir);
        needs_follow_up_frame |= self.apply_pending_text_editing(ir, layout);
        needs_follow_up_frame |= self.apply_pending_text_scroll(ir, layout);
        needs_follow_up_frame |= self.apply_pending_text_form_validation(ir);
        let current_time = self.clock().current_time();
        needs_follow_up_frame |=
            self.runtime_state
                .viewport
                .advance_inertia(ir, layout, current_time);

        let mut current_heroes = HashMap::new();

        for (id, node) in &ir.nodes {
            if let Op::Semantics(s) = &node.op {
                if let Some(tag) = &s.hero_tag {
                    if let Some(geom) = layout.get_node_geometry(*id) {
                        current_heroes.insert(tag.clone(), (*id, geom.rect));
                    }
                }
            }
        }

        // Detection logic for future flight motions
        for (tag, (_new_id, new_rect)) in &current_heroes {
            if let Some((_old_id, old_rect)) = self.runtime_state.hero.positions.get(tag) {
                if *new_rect != *old_rect {
                    // Logic to spawn overlay flight ghost would go here
                    diag::emit(
                        diag::DiagCategory::Layout,
                        diag::DiagLevel::Debug,
                        diag::DiagEventKind::AnchorPlacement {
                            widget: 0,
                            node: 0,
                            rect_x: old_rect.origin.x,
                            rect_y: old_rect.origin.y,
                            rect_w: old_rect.size.width,
                            rect_h: old_rect.size.height,
                            place_left: new_rect.origin.x,
                            place_top: new_rect.origin.y,
                            note: Some(format!("Hero flight: {}", tag)),
                        },
                    );
                }
            }
        }

        self.runtime_state.hero.positions = current_heroes;
        needs_follow_up_frame
    }

    fn apply_pending_selection_regions(&mut self, ir: &CoreIR) -> bool {
        let pending = std::mem::take(&mut self.pending_selection_regions);
        let mut changed = false;
        for (region_id, command) in pending {
            changed |= crate::selection::apply_region_command(
                &mut self.runtime_state.selectable_text,
                ir,
                region_id,
                command,
            )
            .is_ok();
        }
        changed
    }

    fn apply_pending_text_form_validation(&mut self, ir: &CoreIR) -> bool {
        let pending = std::mem::take(&mut self.pending_text_form_validation);
        let mut dispatched = false;
        for form_id in pending {
            let fields = ir
                .nodes
                .iter()
                .filter_map(|(id, node)| match &node.op {
                    Op::Semantics(semantics)
                        if semantics.role == fission_ir::Role::TextInput
                            && semantics.text_form_id.as_deref() == Some(form_id.as_str()) =>
                    {
                        Some((*id, semantics.clone()))
                    }
                    _ => None,
                })
                .collect::<Vec<_>>();
            for (id, semantics) in fields {
                let Some(entry) = semantics
                    .actions
                    .entries
                    .iter()
                    .find(|entry| entry.trigger == fission_ir::ActionTrigger::Validation)
                else {
                    continue;
                };
                let value = self.text_input_value(ir, id);
                let mut update = crate::UpdateTextInput::from_values(
                    id,
                    value.clone(),
                    value,
                    crate::TextEditSource::Programmatic,
                    crate::TextEditPhase::Validated,
                );
                update.validation_state = Some(semantics.validation_state);
                update.validation_message = semantics.validation_message.clone();
                let input = crate::input::scoped_action_input(
                    ir,
                    id,
                    crate::ActionInput::TextChanged(update),
                );
                let envelope = crate::ActionEnvelope {
                    id: crate::ActionId::from_u128(entry.action_id),
                    payload: entry.payload_data.clone().unwrap_or_else(|| {
                        serde_json::to_vec(&()).expect("unit action payload must serialize")
                    }),
                };
                if let Err(error) = self.dispatch_with_input(envelope, id, &input) {
                    diag::emit(
                        diag::DiagCategory::Input,
                        diag::DiagLevel::Warn,
                        diag::DiagEventKind::InputEvent {
                            kind: format!("text_form_validation:{error}"),
                            target: Some(id.as_u128()),
                            position: None,
                        },
                    );
                } else {
                    dispatched = true;
                }
            }
        }
        dispatched
    }

    fn apply_pending_text_editing(&mut self, ir: &CoreIR, layout: &LayoutSnapshot) -> bool {
        let pending = std::mem::take(&mut self.pending_text_editing);
        let mut changed = false;
        for (input_id, command) in pending {
            let result = match command {
                crate::TextEditingCommand::Focus => {
                    self.set_focused_widget(ir, Some(input_id), crate::TextEditSource::Programmatic)
                }
                crate::TextEditingCommand::Unfocus => {
                    if self.runtime_state.interaction.focused == Some(input_id) {
                        self.set_focused_widget(ir, None, crate::TextEditSource::Programmatic)
                    } else {
                        Ok(false)
                    }
                }
                crate::TextEditingCommand::SelectAll => {
                    let value = self.text_input_value(ir, input_id);
                    let end = crate::TextPosition::at_end(&value.text);
                    self.apply_text_edit_command_to(
                        ir,
                        layout,
                        input_id,
                        crate::TextEditCommand::SetSelection {
                            selection: crate::TextSelection {
                                base: crate::TextPosition::START,
                                extent: end,
                                affinity: crate::TextAffinity::Downstream,
                            },
                            source: crate::TextEditSource::Programmatic,
                        },
                    )
                }
                crate::TextEditingCommand::SetSelection(selection) => self
                    .apply_text_edit_command_to(
                        ir,
                        layout,
                        input_id,
                        crate::TextEditCommand::SetSelection {
                            selection,
                            source: crate::TextEditSource::Programmatic,
                        },
                    ),
                crate::TextEditingCommand::SetValue(value) => self.apply_text_edit_command_to(
                    ir,
                    layout,
                    input_id,
                    crate::TextEditCommand::SetValue {
                        value,
                        source: crate::TextEditSource::Programmatic,
                        phase: crate::TextValuePhase::Committed,
                    },
                ),
            };
            match result {
                Ok(applied) => changed |= applied,
                Err(error) => diag::emit(
                    diag::DiagCategory::Input,
                    diag::DiagLevel::Warn,
                    diag::DiagEventKind::InputEvent {
                        kind: format!("text_editing_controller:{error}"),
                        target: Some(input_id.as_u128()),
                        position: None,
                    },
                ),
            }
        }
        changed
    }

    /// Applies a complete edit to a specific text input through the same
    /// transaction, formatter, action, scrolling, and IME path as user input.
    #[doc(hidden)]
    pub fn apply_text_edit_command_to(
        &mut self,
        ir: &CoreIR,
        layout: &LayoutSnapshot,
        input_id: WidgetId,
        command: crate::TextEditCommand,
    ) -> Result<bool> {
        use crate::input::text::TextInputController;
        use crate::input::ControllerContext;

        let previous_text_state = self.runtime_state.text_edit.get(input_id).cloned();
        let current_time = self.clock().current_time();
        let (handled, dispatched_actions) = {
            let mut context = ControllerContext {
                ir,
                layout,
                text_edit: &mut self.runtime_state.text_edit,
                selectable_text: &mut self.runtime_state.selectable_text,
                context_menu: &mut self.runtime_state.context_menu,
                interaction: &mut self.runtime_state.interaction,
                scroll: &mut self.runtime_state.scroll,
                viewport: &self.runtime_state.viewport,
                gesture: &mut self.runtime_state.gesture,
                editing_convention: self.editing_convention,
                current_time,
                clipboard: self.clipboard_backend.as_ref(),
                measurer: self.measurer.as_ref(),
                dispatched_actions: Vec::new(),
            };
            let handled =
                TextInputController.handle_text_edit_command_for(&mut context, input_id, command);
            (handled, context.dispatched_actions)
        };
        if let Err(error) = self.dispatch_input_actions(dispatched_actions) {
            if let Some(previous) = previous_text_state {
                self.runtime_state
                    .text_edit
                    .states
                    .insert(input_id, previous);
            } else {
                self.runtime_state.text_edit.states.remove(&input_id);
            }
            return Err(error);
        }
        if self.runtime_state.interaction.focused == Some(input_id) {
            self.update_focused_ime_state(ir, layout);
        }
        Ok(handled)
    }

    fn apply_pending_text_scroll(&mut self, ir: &CoreIR, layout: &LayoutSnapshot) -> bool {
        let pending = std::mem::take(&mut self.pending_text_scroll);
        let mut changed = false;
        for (input_id, command) in pending {
            changed |= crate::TextScrollController::new(input_id)
                .apply(&mut self.runtime_state, ir, layout, command)
                .is_ok();
        }
        changed
    }

    pub fn handle_input(
        &mut self,
        event: InputEvent,
        ir: &CoreIR,
        layout: &LayoutSnapshot,
    ) -> Result<()> {
        use crate::hit_test::{
            find_neighbor_focus_node, find_next_focus_node, hit_test_with_viewports, FocusDirection,
        };
        use crate::input::gesture::GestureController;
        use crate::input::hover::HoverController;
        use crate::input::selectable_text::SelectableTextController;
        use crate::input::slider::SliderController;
        use crate::input::text::TextInputController;
        use crate::input::{ControllerContext, InputController};
        use crate::scrollbar::scrollbar_hit_test;
        use crate::ui::custom_render::downcast_render_object;

        self.reconcile_focus(ir)?;
        let input_time = self.clock().current_time();

        if self.runtime_state.interaction.focused.is_none() {
            if let Some(autofocus_id) = Self::find_autofocus_node(ir) {
                self.set_focused_widget(
                    ir,
                    Some(autofocus_id),
                    crate::TextEditSource::Programmatic,
                )?;
            }
        }

        if matches!(event, InputEvent::Pointer(_)) {
            let dispatched_actions = {
                let mut ctx = ControllerContext {
                    ir,
                    layout,
                    text_edit: &mut self.runtime_state.text_edit,
                    selectable_text: &mut self.runtime_state.selectable_text,
                    context_menu: &mut self.runtime_state.context_menu,
                    interaction: &mut self.runtime_state.interaction,
                    scroll: &mut self.runtime_state.scroll,
                    viewport: &self.runtime_state.viewport,
                    gesture: &mut self.runtime_state.gesture,
                    editing_convention: self.editing_convention,
                    current_time: input_time,
                    clipboard: self.clipboard_backend.as_ref(),
                    measurer: self.measurer.as_ref(),
                    dispatched_actions: Vec::new(),
                };
                let mut hover_controller = HoverController;
                let _ = hover_controller.handle_event(&mut ctx, &event);
                ctx.dispatched_actions
            };
            self.dispatch_input_actions(dispatched_actions)?;
        }

        // --- Custom render object event handling (runs first) ----------------
        // For pointer events we hit-test, then walk up from the hit node to
        // check whether any ancestor carries a custom render object.  The
        // first one that returns `handled = true` short-circuits the entire
        // standard controller chain.
        let pointer_targets_scrollbar = match &event {
            InputEvent::Pointer(PointerEvent::Down { point, button, .. })
                if matches!(button, PointerButton::Primary) =>
            {
                scrollbar_hit_test(ir, layout, &self.runtime_state.scroll, *point).is_some()
            }
            InputEvent::Pointer(PointerEvent::Move { .. })
            | InputEvent::Pointer(PointerEvent::Up { .. }) => {
                self.runtime_state.gesture.scrollbar_drag.is_some()
            }
            InputEvent::Pointer(PointerEvent::Scroll { point, .. }) => {
                scrollbar_hit_test(ir, layout, &self.runtime_state.scroll, *point).is_some()
            }
            _ => false,
        };

        if !pointer_targets_scrollbar {
            if let Some(point) = Self::event_point(&event) {
                if let Some(hit_node_id) = hit_test_with_viewports(
                    ir,
                    layout,
                    &self.runtime_state.scroll,
                    &self.runtime_state.viewport,
                    point,
                ) {
                    // Find the custom render object for this click.  Walk up from the
                    // hit node first; if not found, check all registered render objects
                    // by rect containment (the hit may be on a wrapper node above the
                    // InternalRenderNode's lowered subtree).
                    let mut target_ro: Option<(WidgetId, &fission_ir::AnyRenderObject)> = None;
                    {
                        let mut walk = Some(hit_node_id);
                        while let Some(nid) = walk {
                            if let Some(ro) = ir.custom_render_objects.get(&nid) {
                                target_ro = Some((nid, ro));
                                break;
                            }
                            walk = ir.nodes.get(&nid).and_then(|n| n.parent);
                        }
                    }
                    if target_ro.is_none() {
                        for (ro_nid, ro) in &ir.custom_render_objects {
                            if let Some(rect) = layout.get_node_rect(*ro_nid) {
                                if rect.contains(point) {
                                    target_ro = Some((*ro_nid, ro));
                                    break;
                                }
                            }
                        }
                    }

                    if let Some((nid, any_ro)) = target_ro {
                        if let Some(render_obj) = downcast_render_object(any_ro) {
                            let mut node_rect = layout
                                .get_node_rect(nid)
                                .unwrap_or(LayoutRect::new(0.0, 0.0, 0.0, 0.0));
                            // Adjust node_rect by ancestor scroll offsets so it reflects
                            // the VISUAL position, matching the screen-coordinate click.
                            {
                                let mut walk = ir.nodes.get(&nid).and_then(|n| n.parent);
                                while let Some(pid) = walk {
                                    if let Some(pnode) = ir.nodes.get(&pid) {
                                        if let fission_ir::Op::Layout(
                                            fission_ir::LayoutOp::Scroll { direction, .. },
                                        ) = &pnode.op
                                        {
                                            let off = self.runtime_state.scroll.get_offset(pid);
                                            match direction {
                                                fission_ir::FlexDirection::Row => {
                                                    node_rect.origin.x -= off
                                                }
                                                fission_ir::FlexDirection::Column => {
                                                    node_rect.origin.y -= off
                                                }
                                            }
                                        }
                                        walk = pnode.parent;
                                    } else {
                                        break;
                                    }
                                }
                            }
                            let result = render_obj.handle_event(nid, &event, node_rect);
                            if result.handled {
                                // Set focus to this node so keyboard events route here
                                if matches!(
                                    event,
                                    InputEvent::Pointer(PointerEvent::Down {
                                        button: PointerButton::Primary,
                                        ..
                                    })
                                ) {
                                    self.set_focused_widget(
                                        ir,
                                        Some(nid),
                                        crate::TextEditSource::Pointer,
                                    )?;
                                    if let Some(ime_handler) = &self.ime_handler {
                                        let accepts_text = render_obj.accepts_text_input();
                                        ime_handler.set_ime_allowed(accepts_text);
                                        if accepts_text {
                                            if let Some(rect) =
                                                render_obj.ime_cursor_area(node_rect)
                                            {
                                                ime_handler.set_ime_cursor_area(rect);
                                            }
                                        }
                                    }
                                }
                                // Dispatch any actions the render object produced.
                                for (target, envelope) in result.actions {
                                    self.dispatch_node(envelope, target)?;
                                }
                                self.update_focused_ime_state(ir, layout);
                                return Ok(());
                            }
                        }
                    }
                }
            }
        }

        // --- Keyboard events → focused node's custom render object -----------
        // Keyboard events have no point, so we route them to the focused node
        // (if any) and walk up its ancestor chain looking for a custom render
        // object.  This allows custom editor nodes to handle arrow keys,
        // typing, etc. before the framework's default focus-navigation logic.
        if matches!(
            event,
            InputEvent::Keyboard(_)
                | InputEvent::Ime(_)
                | InputEvent::Editing(_)
                | InputEvent::TextEdit(_)
        ) {
            if let Some(focused_id) = self.runtime_state.interaction.focused {
                let mut walk_id = Some(focused_id);
                while let Some(nid) = walk_id {
                    if let Some(any_ro) = ir.custom_render_objects.get(&nid) {
                        if let Some(render_obj) = downcast_render_object(any_ro) {
                            let node_rect = layout
                                .get_node_rect(nid)
                                .unwrap_or(LayoutRect::new(0.0, 0.0, 0.0, 0.0));
                            let result = render_obj.handle_event(nid, &event, node_rect);
                            if result.handled {
                                for (target, envelope) in result.actions {
                                    self.dispatch_node(envelope, target)?;
                                }
                                self.update_focused_ime_state(ir, layout);
                                return Ok(());
                            }
                        }
                    }
                    walk_id = ir.nodes.get(&nid).and_then(|n| n.parent);
                }
            }
        }

        let (viewport_handled, viewport_actions) = {
            let current_time = self.clock().current_time();
            let mut ctx = crate::input::viewport::ViewportControllerContext {
                ir,
                layout,
                scroll: &self.runtime_state.scroll,
                viewport: &mut self.runtime_state.viewport,
                gesture: &mut self.runtime_state.gesture,
                current_time,
                dispatched_actions: Vec::new(),
            };
            let mut controller = crate::input::viewport::ViewportController;
            let handled = controller.handle_event(&mut ctx, &event);
            (handled, ctx.dispatched_actions)
        };
        self.dispatch_input_actions(viewport_actions)?;
        if viewport_handled {
            if matches!(
                event,
                InputEvent::Pointer(PointerEvent::Up { .. } | PointerEvent::Cancel { .. })
            ) {
                self.runtime_state.interaction.pressed.clear();
                self.runtime_state.interaction.last_down_point = None;
            }
            self.update_focused_ime_state(ir, layout);
            return Ok(());
        }

        let mut pointer_select_all_target = None;

        // Establish pointer focus before the standard controllers run. Text
        // editing, selection, and gesture controllers can then observe one
        // authoritative focus transition instead of each partially recreating
        // focus/blur behavior.
        if let InputEvent::Pointer(PointerEvent::Down {
            point,
            button: PointerButton::Primary,
            ..
        }) = &event
        {
            let mut candidate = hit_test_with_viewports(
                ir,
                layout,
                &self.runtime_state.scroll,
                &self.runtime_state.viewport,
                *point,
            );
            let mut preserve_current = false;
            let mut next = None;
            while let Some(node_id) = candidate {
                let Some(node) = ir.nodes.get(&node_id) else {
                    break;
                };
                if let Op::Semantics(semantics) = &node.op {
                    if semantics.focusable {
                        if semantics.focus_policy == FocusPolicy::PreserveCurrentOnPointer {
                            preserve_current = true;
                        } else {
                            next = Some(node_id);
                        }
                        break;
                    }
                }
                candidate = node.parent;
            }
            if !preserve_current {
                let changed = self.set_focused_widget(ir, next, crate::TextEditSource::Pointer)?;
                if changed
                    && next.is_some_and(|id| {
                        ir.custom_render_objects
                            .get(&id)
                            .and_then(
                                crate::ui::widgets::text_input::downcast_text_input_runtime_config,
                            )
                            .is_some_and(|config| config.select_all_on_focus)
                    })
                {
                    pointer_select_all_target = next;
                }
            }
        }

        let (handled, dispatched_actions) = {
            let mut ctx = ControllerContext {
                ir,
                layout,
                text_edit: &mut self.runtime_state.text_edit,
                selectable_text: &mut self.runtime_state.selectable_text,
                context_menu: &mut self.runtime_state.context_menu,
                interaction: &mut self.runtime_state.interaction,
                scroll: &mut self.runtime_state.scroll,
                viewport: &self.runtime_state.viewport,
                gesture: &mut self.runtime_state.gesture,
                editing_convention: self.editing_convention,
                current_time: input_time,
                clipboard: self.clipboard_backend.as_ref(),
                measurer: self.measurer.as_ref(),
                dispatched_actions: Vec::new(),
            };

            let mut hover_controller = HoverController;
            let _ = hover_controller.handle_event(&mut ctx, &event);

            let mut selectable_text_controller = SelectableTextController;
            let handled = if selectable_text_controller.handle_event(&mut ctx, &event) {
                true
            } else {
                let mut gesture_controller = GestureController;
                if gesture_controller.handle_event(&mut ctx, &event) {
                    true
                } else {
                    let text_handled = if pointer_select_all_target.is_some() {
                        true
                    } else {
                        let mut text_controller = TextInputController;
                        text_controller.handle_event(&mut ctx, &event)
                    };
                    if text_handled {
                        true
                    } else {
                        let mut slider_controller = SliderController;
                        slider_controller.handle_event(&mut ctx, &event)
                    }
                }
            };
            (handled, ctx.dispatched_actions)
        };

        self.dispatch_input_actions(dispatched_actions)?;

        if handled {
            if matches!(
                event,
                InputEvent::Pointer(PointerEvent::Up { .. } | PointerEvent::Cancel { .. })
            ) {
                self.runtime_state.interaction.pressed.clear();
                self.runtime_state.interaction.last_down_point = None;
            }
            self.update_focused_ime_state(ir, layout);
            return Ok(());
        }

        match event {
            InputEvent::Pointer(PointerEvent::Scroll { point, delta, .. }) => {
                let trace_scroll =
                    std::env::var("FISSION_SCROLL_TRACE").ok().as_deref() == Some("1");
                if trace_scroll {
                    eprintln!(
                        "[scroll-trace] event point=({:.1},{:.1}) delta=({:.1},{:.1})",
                        point.x, point.y, delta.x, delta.y
                    );
                }
                let hit_node_id = scrollbar_hit_test(ir, layout, &self.runtime_state.scroll, point)
                    .map(|hit| hit.geometry.node_id)
                    .or_else(|| {
                        hit_test_with_viewports(
                            ir,
                            layout,
                            &self.runtime_state.scroll,
                            &self.runtime_state.viewport,
                            point,
                        )
                    });
                if let Some(hit_node_id) = hit_node_id {
                    if trace_scroll {
                        eprintln!("[scroll-trace] hit_node={}", hit_node_id.as_u128());
                    }
                    let mut current_id = Some(hit_node_id);
                    while let Some(node_id) = current_id {
                        if let Some(node) = ir.nodes.get(&node_id) {
                            if let Op::Layout(LayoutOp::Scroll { direction, .. }) = &node.op {
                                if crate::ui::widgets::text_input::text_input_scroll_physics_for_node(
                                    ir, node_id,
                                ) == Some(crate::ui::widgets::text_input::TextScrollPhysics::NeverScrollable)
                                {
                                    current_id = node.parent;
                                    continue;
                                }
                                let current_offset = self.runtime_state.scroll.get_offset(node_id);
                                let delta_val = match direction {
                                    FlexDirection::Row => delta.x,
                                    FlexDirection::Column => delta.y,
                                };
                                let mut new_offset = current_offset + delta_val;

                                let mut max_offset = 0.0f32;
                                let mut viewport_w = 0.0f32;
                                let mut viewport_h = 0.0f32;
                                let mut content_w = 0.0f32;
                                let mut content_h = 0.0f32;
                                if let Some(geom) = layout.get_node_geometry(node_id) {
                                    viewport_w = geom.rect.width();
                                    viewport_h = geom.rect.height();
                                    content_w = geom.content_size.width;
                                    content_h = geom.content_size.height;
                                    max_offset = if matches!(direction, FlexDirection::Row) {
                                        (geom.content_size.width - geom.rect.width()).max(0.0)
                                    } else {
                                        (geom.content_size.height - geom.rect.height()).max(0.0)
                                    };
                                    new_offset = new_offset.clamp(0.0, max_offset);
                                }

                                if trace_scroll {
                                    eprintln!(
                                        "[scroll-trace] scroll_node={} axis={} offset={:.1}->{:.1} max={:.1} viewport=({:.1},{:.1}) content=({:.1},{:.1})",
                                        node_id.as_u128(),
                                        match direction { FlexDirection::Row => "x", FlexDirection::Column => "y" },
                                        current_offset,
                                        new_offset,
                                        max_offset,
                                        viewport_w,
                                        viewport_h,
                                        content_w,
                                        content_h
                                    );
                                }

                                {
                                    use fission_diagnostics::prelude as diag;
                                    diag::emit(
                                        diag::DiagCategory::Input,
                                        diag::DiagLevel::Debug,
                                        diag::DiagEventKind::ScrollUpdate {
                                            node: node_id.as_u128(),
                                            axis: match direction {
                                                FlexDirection::Row => "x".into(),
                                                FlexDirection::Column => "y".into(),
                                            },
                                            point_x: point.x,
                                            point_y: point.y,
                                            delta: delta_val,
                                            old_offset: current_offset,
                                            new_offset,
                                            max_offset,
                                            viewport_w,
                                            viewport_h,
                                            content_w,
                                            content_h,
                                        },
                                    );
                                }

                                self.runtime_state.scroll.set_offset(node_id, new_offset);
                                // If scroll actually changed, consume the event.
                                // If it didn't (clamped to same value, e.g. max_offset==0),
                                // propagate to parent scroll nodes.
                                if (new_offset - current_offset).abs() > 0.001 {
                                    break;
                                }
                                // Fall through to parent
                            }
                            current_id = node.parent;
                        } else {
                            break;
                        }
                    }
                } else if trace_scroll {
                    eprintln!("[scroll-trace] hit_test: no node");
                }
            }
            InputEvent::Keyboard(KeyEvent::Down {
                key_code,
                modifiers,
            }) => match key_code {
                KeyCode::Tab => {
                    let reverse = (modifiers & 1) != 0;
                    let old_focus = self.runtime_state.interaction.focused;
                    let next =
                        find_next_focus_node(ir, self.runtime_state.interaction.focused, reverse);
                    if next != old_focus {
                        self.set_focused_widget(ir, next, crate::TextEditSource::Keyboard)?;
                    }
                }
                KeyCode::Up | KeyCode::Down | KeyCode::Left | KeyCode::Right => {
                    let reverse = matches!(key_code, KeyCode::Up | KeyCode::Left);
                    let old_focus = self.runtime_state.interaction.focused;
                    let next = if let Some(focused) = old_focus {
                        let dir = match key_code {
                            KeyCode::Up => FocusDirection::Up,
                            KeyCode::Down => FocusDirection::Down,
                            KeyCode::Left => FocusDirection::Left,
                            KeyCode::Right => FocusDirection::Right,
                            _ => unreachable!(),
                        };
                        find_neighbor_focus_node(ir, layout, focused, dir)
                            .or_else(|| find_next_focus_node(ir, Some(focused), reverse))
                    } else {
                        find_next_focus_node(ir, None, reverse)
                    };
                    if next != old_focus {
                        self.set_focused_widget(ir, next, crate::TextEditSource::Keyboard)?;
                    }
                }
                KeyCode::Enter | KeyCode::Space => {
                    if let Some(focused_id) = self.runtime_state.interaction.focused {
                        let mut current_id = Some(focused_id);
                        while let Some(node_id) = current_id {
                            if let Some(node) = ir.nodes.get(&node_id) {
                                if let Op::Semantics(semantics) = &node.op {
                                    let action_entry = semantics
                                        .actions
                                        .entries
                                        .iter()
                                        .find(|entry| {
                                            entry.trigger
                                                == fission_ir::semantics::ActionTrigger::Default
                                        })
                                        .and_then(|entry| {
                                            entry.payload_data.as_ref().map(|payload| {
                                                ActionEnvelope {
                                                    id: ActionId::from_u128(entry.action_id),
                                                    payload: payload.clone(),
                                                }
                                            })
                                        });
                                    let hyperlink = semantics.hyperlink.clone();
                                    if action_entry.is_some() || hyperlink.is_some() {
                                        let input = crate::input::scoped_action_input(
                                            ir,
                                            node_id,
                                            ActionInput::None,
                                        );
                                        let navigation_already_bound =
                                            action_entry.as_ref().is_some_and(|entry| {
                                                entry.id == crate::NavigationRequested::static_id()
                                            });
                                        if let Some(envelope) = action_entry {
                                            self.dispatch_node_with_input(
                                                envelope, node_id, &input,
                                            )?;
                                        }
                                        if let Some(hyperlink) =
                                            hyperlink.filter(|_| !navigation_already_bound)
                                        {
                                            self.dispatch_node_with_input(
                                                crate::NavigationRequested::new(
                                                    crate::NavigationCommand::Open(hyperlink),
                                                )
                                                .into(),
                                                node_id,
                                                &input,
                                            )?;
                                        }
                                        return Ok(());
                                    }
                                }
                                current_id = node.parent;
                            } else {
                                break;
                            }
                        }
                    }
                }
                _ => {}
            },
            InputEvent::Pointer(PointerEvent::Down {
                point,
                button: PointerButton::Primary,
                ..
            }) => {
                if let Some(hit_node_id) = hit_test_with_viewports(
                    ir,
                    layout,
                    &self.runtime_state.scroll,
                    &self.runtime_state.viewport,
                    point,
                ) {
                    diag::emit(
                        diag::DiagCategory::Input,
                        diag::DiagLevel::Debug,
                        diag::DiagEventKind::InputEvent {
                            kind: "pointer_down_hit".into(),
                            target: Some(hit_node_id.as_u128()),
                            position: Some((point.x, point.y)),
                        },
                    );
                    let mut focus_candidate = Some(hit_node_id);
                    while let Some(node_id) = focus_candidate {
                        if let Some(node) = ir.nodes.get(&node_id) {
                            if let Op::Semantics(s) = &node.op {
                                if s.focusable {
                                    if s.focus_policy == FocusPolicy::PreserveCurrentOnPointer {
                                        break;
                                    }
                                    self.set_focused_widget(
                                        ir,
                                        Some(node_id),
                                        crate::TextEditSource::Pointer,
                                    )?;
                                    break;
                                }
                            }
                            focus_candidate = node.parent;
                        } else {
                            break;
                        }
                    }
                    if focus_candidate.is_none() {
                        self.set_focused_widget(ir, None, crate::TextEditSource::Pointer)?;
                    }

                    let mut current_pressed_id = Some(hit_node_id);
                    while let Some(node_id) = current_pressed_id {
                        self.runtime_state.interaction.set_pressed(node_id, true);
                        if let Some(node) = ir.nodes.get(&node_id) {
                            current_pressed_id = node.parent;
                        } else {
                            break;
                        }
                    }
                    self.runtime_state.interaction.last_down_point = Some(point);

                    if let Some(focused_id) = self.runtime_state.interaction.focused {
                        if let Some(node) = ir.nodes.get(&focused_id) {
                            if let Op::Semantics(s) = &node.op {
                                if s.role == fission_ir::semantics::Role::TextInput {
                                    if let Some(ime_handler) = &self.ime_handler {
                                        ime_handler.set_ime_cursor_area(LayoutRect::new(
                                            point.x, point.y, 2.0, 16.0,
                                        ));
                                    }
                                }
                            }
                        }
                    }
                } else {
                    self.set_focused_widget(ir, None, crate::TextEditSource::Pointer)?;
                }
            }
            InputEvent::Pointer(PointerEvent::Up {
                point,
                button: PointerButton::Primary,
                ..
            }) => {
                self.runtime_state.interaction.pressed.clear();
                let had_primary_down = self
                    .runtime_state
                    .interaction
                    .last_down_point
                    .take()
                    .is_some();
                if had_primary_down {
                    if let Some(hit_node_id) = hit_test_with_viewports(
                        ir,
                        layout,
                        &self.runtime_state.scroll,
                        &self.runtime_state.viewport,
                        point,
                    ) {
                        let mut current_id = Some(hit_node_id);
                        while let Some(node_id) = current_id {
                            if let Some(node) = ir.nodes.get(&node_id) {
                                if let Op::Semantics(semantics) = &node.op {
                                    if semantics.role == fission_ir::semantics::Role::TextInput {
                                        // No action
                                    } else if let Some(action_entry) =
                                        semantics.actions.entries.iter().find(|entry| {
                                            entry.trigger
                                                == fission_ir::semantics::ActionTrigger::Default
                                        })
                                    {
                                        if let Some(payload) = &action_entry.payload_data {
                                            let envelope = ActionEnvelope {
                                                id: ActionId::from_u128(action_entry.action_id),
                                                payload: payload.clone(),
                                            };
                                            diag::emit(
                                                diag::DiagCategory::Input,
                                                diag::DiagLevel::Debug,
                                                diag::DiagEventKind::InputEvent {
                                                    kind: "pointer_up_dispatch".into(),
                                                    target: Some(node_id.as_u128()),
                                                    position: Some((point.x, point.y)),
                                                },
                                            );
                                            let input = crate::input::scoped_action_input(
                                                ir,
                                                node_id,
                                                ActionInput::None,
                                            );
                                            return self.dispatch_node_with_input(
                                                envelope, node_id, &input,
                                            );
                                        }
                                    }
                                }
                                current_id = node.parent;
                            } else {
                                break;
                            }
                        }
                    }
                }
            }
            _ => {}
        }
        self.update_focused_ime_state(ir, layout);
        Ok(())
    }

    pub fn clear_hover_state(&mut self, ir: &CoreIR, point: Option<LayoutPoint>) -> Result<bool> {
        use crate::input::hover::HoverController;
        use crate::input::ControllerContext;

        let input_time = self.clock().current_time();
        let dispatched_actions = {
            let layout = &LayoutSnapshot::new(LayoutSize::ZERO);
            let mut ctx = ControllerContext {
                ir,
                layout,
                text_edit: &mut self.runtime_state.text_edit,
                selectable_text: &mut self.runtime_state.selectable_text,
                context_menu: &mut self.runtime_state.context_menu,
                interaction: &mut self.runtime_state.interaction,
                scroll: &mut self.runtime_state.scroll,
                viewport: &self.runtime_state.viewport,
                gesture: &mut self.runtime_state.gesture,
                editing_convention: self.editing_convention,
                current_time: input_time,
                clipboard: self.clipboard_backend.as_ref(),
                measurer: self.measurer.as_ref(),
                dispatched_actions: Vec::new(),
            };
            let changed = HoverController::clear(&mut ctx, point);
            (changed, ctx.dispatched_actions)
        };
        self.dispatch_input_actions(dispatched_actions.1)?;
        Ok(dispatched_actions.0)
    }

    fn dispatch_input_actions(
        &mut self,
        dispatched_actions: Vec<(WidgetId, ActionEnvelope, ActionInput)>,
    ) -> Result<()> {
        for (target, action, input) in dispatched_actions {
            self.dispatch_node_with_input(action, target, &input)?;
        }
        Ok(())
    }

    #[doc(hidden)]
    pub fn update_focused_ime_state(&mut self, ir: &CoreIR, layout: &LayoutSnapshot) {
        let Some(ime_handler) = self.ime_handler.clone() else {
            return;
        };
        let Some(focused_id) = self.runtime_state.interaction.focused else {
            ime_handler.set_ime_allowed(false);
            return;
        };

        let mut walk = Some(focused_id);
        while let Some(node_id) = walk {
            if let Some(any_ro) = ir.custom_render_objects.get(&node_id) {
                if let Some(render_obj) = crate::ui::custom_render::downcast_render_object(any_ro) {
                    let accepts_text = render_obj.accepts_text_input();
                    ime_handler.set_ime_allowed(accepts_text);
                    if accepts_text {
                        let rect =
                            Self::visual_node_rect(ir, layout, &self.runtime_state.scroll, node_id)
                                .unwrap_or(LayoutRect::new(0.0, 0.0, 0.0, 0.0));
                        if let Some(cursor_area) = render_obj.ime_cursor_area(rect) {
                            ime_handler.set_ime_cursor_area(cursor_area);
                        }
                    }
                    return;
                }
            }
            walk = ir.nodes.get(&node_id).and_then(|node| node.parent);
        }

        let accepts_text = ir
            .nodes
            .get(&focused_id)
            .and_then(|node| match &node.op {
                Op::Semantics(semantics) => {
                    Some(semantics.role == fission_ir::semantics::Role::TextInput)
                }
                _ => None,
            })
            .unwrap_or(false);
        ime_handler.set_ime_allowed(accepts_text);

        if accepts_text {
            let editing_value = self
                .runtime_state
                .text_edit
                .get(focused_id)
                .map(crate::env::TextEditState::editing_value)
                .or_else(|| {
                    let semantics = ir.nodes.get(&focused_id).and_then(|node| match &node.op {
                        Op::Semantics(semantics) => Some(semantics),
                        _ => None,
                    })?;
                    let text = semantics.value.clone().unwrap_or_default();
                    let (anchor, caret) =
                        semantics.text_selection.unwrap_or((text.len(), text.len()));
                    let selection = crate::TextSelection::new(
                        &text,
                        anchor,
                        caret,
                        crate::TextAffinity::Downstream,
                    )
                    .unwrap_or_else(|_| {
                        crate::TextSelection::collapsed(crate::TextPosition::at_end(&text))
                    });
                    Some(crate::TextEditingValue {
                        text,
                        selection,
                        composing: None,
                    })
                });
            if let Some(editing_value) = editing_value.as_ref() {
                ime_handler.set_editing_value(editing_value);
            }

            let input_time = self.clock().current_time();
            let cursor_area = {
                let mut ctx = crate::input::ControllerContext {
                    ir,
                    layout,
                    text_edit: &mut self.runtime_state.text_edit,
                    selectable_text: &mut self.runtime_state.selectable_text,
                    context_menu: &mut self.runtime_state.context_menu,
                    interaction: &mut self.runtime_state.interaction,
                    scroll: &mut self.runtime_state.scroll,
                    viewport: &self.runtime_state.viewport,
                    gesture: &mut self.runtime_state.gesture,
                    editing_convention: self.editing_convention,
                    current_time: input_time,
                    clipboard: self.clipboard_backend.as_ref(),
                    measurer: self.measurer.as_ref(),
                    dispatched_actions: Vec::new(),
                };
                crate::input::text::TextInputController::ime_cursor_area(&mut ctx, focused_id)
            };
            if let Some(cursor_area) = cursor_area {
                ime_handler.set_ime_cursor_area(cursor_area);
            }
        }
    }

    fn visual_node_rect(
        ir: &CoreIR,
        layout: &LayoutSnapshot,
        scroll: &crate::env::ScrollStateMap,
        node_id: WidgetId,
    ) -> Option<LayoutRect> {
        let mut rect = layout.get_node_rect(node_id)?;
        let mut walk = ir.nodes.get(&node_id).and_then(|node| node.parent);
        while let Some(parent_id) = walk {
            let Some(parent) = ir.nodes.get(&parent_id) else {
                break;
            };
            if let Op::Layout(LayoutOp::Scroll { direction, .. }) = &parent.op {
                let offset = scroll.get_offset(parent_id);
                match direction {
                    FlexDirection::Row => rect.origin.x -= offset,
                    FlexDirection::Column => rect.origin.y -= offset,
                }
            }
            walk = parent.parent;
        }
        Some(rect)
    }

    fn clear_text_pending_on_blur(
        &mut self,
        old_focus: Option<WidgetId>,
        new_focus: Option<WidgetId>,
    ) {
        if old_focus == new_focus {
            return;
        }
        if let Some(old_id) = old_focus {
            if let Some(st) = self.runtime_state.text_edit.states.get_mut(&old_id) {
                st.pending_model_sync = false;
                st.clear_preedit();
            }
        }
    }

    fn text_input_value(&self, ir: &CoreIR, id: WidgetId) -> crate::TextEditingValue {
        self.runtime_state
            .text_edit
            .get(id)
            .map(|state| state.editing_value())
            .unwrap_or_else(|| {
                let text = ir
                    .nodes
                    .get(&id)
                    .and_then(|node| match &node.op {
                        Op::Semantics(semantics) => semantics.value.clone(),
                        _ => None,
                    })
                    .unwrap_or_default();
                crate::TextEditingValue::from_text(text)
            })
    }

    fn dispatch_text_session_action(
        &mut self,
        ir: &CoreIR,
        id: WidgetId,
        trigger: fission_ir::semantics::ActionTrigger,
        source: crate::TextEditSource,
        phase: crate::TextEditPhase,
    ) -> Result<()> {
        let Some(semantics) = ir.nodes.get(&id).and_then(|node| match &node.op {
            Op::Semantics(semantics)
                if semantics.role == fission_ir::semantics::Role::TextInput =>
            {
                Some(semantics)
            }
            _ => None,
        }) else {
            return Ok(());
        };
        let value = self.text_input_value(ir, id);
        if let Some((envelope, input)) = crate::input::prepare_scoped_text_session_action(
            ir, semantics, id, trigger, value, source, phase,
        ) {
            self.dispatch_node_with_input(envelope, id, &input)?;
        }
        Ok(())
    }

    /// Applies one focus transition and all of its text-session side effects.
    ///
    /// Shell accessibility adapters and runtime focus navigation use this
    /// boundary so focus/blur actions, select-all-on-focus, and IME lifetime do
    /// not diverge by input source.
    #[doc(hidden)]
    pub fn set_focused_widget(
        &mut self,
        ir: &CoreIR,
        next: Option<WidgetId>,
        source: crate::TextEditSource,
    ) -> Result<bool> {
        let current = self.runtime_state.interaction.focused;
        if current == next {
            return Ok(false);
        }

        self.clear_text_pending_on_blur(current, next);
        self.dispatch_custom_blur_actions(ir, current)?;
        if let Some(old_id) = current {
            if source == crate::TextEditSource::Pointer {
                self.dispatch_text_session_action(
                    ir,
                    old_id,
                    fission_ir::semantics::ActionTrigger::TapOutside,
                    source,
                    crate::TextEditPhase::TapOutside,
                )?;
            }
            self.dispatch_text_session_action(
                ir,
                old_id,
                fission_ir::semantics::ActionTrigger::Blur,
                source,
                crate::TextEditPhase::Blurred,
            )?;
        }

        self.runtime_state.interaction.set_focused(next);
        if let Some(new_id) = next {
            let select_all = ir
                .custom_render_objects
                .get(&new_id)
                .and_then(crate::ui::widgets::text_input::downcast_text_input_runtime_config)
                .is_some_and(|config| config.select_all_on_focus);
            if select_all {
                self.pending_text_editing
                    .push((new_id, crate::TextEditingCommand::SelectAll));
            }
        }

        if let Some(ime_handler) = &self.ime_handler {
            let accepts_text = next.is_some_and(|id| {
                matches!(
                    ir.nodes.get(&id).map(|node| &node.op),
                    Some(Op::Semantics(semantics))
                        if semantics.role == fission_ir::semantics::Role::TextInput
                            && !semantics.disabled
                            && !semantics.read_only
                ) || ir
                    .custom_render_objects
                    .get(&id)
                    .and_then(downcast_render_object)
                    .is_some_and(|render_object| render_object.accepts_text_input())
            });
            ime_handler.set_ime_allowed(accepts_text);
        }

        if let Some(new_id) = next {
            self.dispatch_text_session_action(
                ir,
                new_id,
                fission_ir::semantics::ActionTrigger::Focus,
                source,
                crate::TextEditPhase::Focused,
            )?;
        }
        Ok(true)
    }

    fn dispatch_custom_blur_actions(
        &mut self,
        ir: &CoreIR,
        old_focus: Option<WidgetId>,
    ) -> Result<()> {
        if let Some(old_id) = old_focus {
            if let Some(any_ro) = ir.custom_render_objects.get(&old_id) {
                if let Some(render_obj) = crate::ui::custom_render::downcast_render_object(any_ro) {
                    if render_obj.accepts_text_input() {
                        if let Some(ime_handler) = &self.ime_handler {
                            ime_handler.set_ime_allowed(false);
                        }
                    }
                    for (target, envelope) in render_obj.blur_actions(old_id) {
                        self.dispatch_node(envelope, target)?;
                    }
                }
            }
        }
        Ok(())
    }

    pub fn hit_test(
        &self,
        point: LayoutPoint,
        ir: &CoreIR,
        snapshot: &LayoutSnapshot,
    ) -> Option<WidgetId> {
        if let Some(root) = ir.root {
            return self.hit_test_recursive(root, point, ir, snapshot);
        }
        None
    }

    fn hit_test_recursive(
        &self,
        node_id: WidgetId,
        point: LayoutPoint,
        ir: &CoreIR,
        snapshot: &LayoutSnapshot,
    ) -> Option<WidgetId> {
        if let Some(geom) = snapshot.nodes.get(&node_id) {
            if geom.rect.contains(point) {
                if let Some(node) = ir.nodes.get(&node_id) {
                    for child in node.children.iter().rev() {
                        let mut child_point = point;

                        if let Op::Layout(LayoutOp::Scroll { direction, .. }) = &node.op {
                            if !geom.rect.contains(point) {
                                continue;
                            }
                            let offset = self.runtime_state.scroll.get_offset(node_id);
                            match direction {
                                FlexDirection::Row => child_point.x += offset,
                                FlexDirection::Column => child_point.y += offset,
                            }
                        }

                        if let Op::Layout(LayoutOp::Transform { transform }) = &node.op {
                            let mat = Mat4::from_cols_array(transform);
                            // We need to transform the point relative to the node's origin?
                            // Layout coordinates are relative to the parent.
                            // In hit_test_recursive, `point` is relative to current `node_id`?
                            // No, `point` is relative to the `geom.rect.origin` of `node_id`?
                            // Let's check recursion.

                            // hit_test starts at root with absolute point.
                            // recursion: `child_point = point`.
                            // wait, `hit_test_recursive` doesn't subtract location?
                            // Ah, I see: `if geom.rect.contains(point)`.
                            // This implies `point` is ABSOLUTE.

                            // If `point` is absolute, and we want to transform into child local space:
                            // 1. Move point to node local space: `point - node_pos`.
                            // 2. Apply inverse transform.
                            // 3. (Implicitly) Move back or keep local?
                            // Recursive call expects absolute point?
                            // No, `hit_test_recursive` calls itself with `child_point`.
                            // If it expects absolute point, then `Transform` node doesn't work well with absolute recursion.

                            // Actually, my `hit_test_recursive` impl seems to assume absolute points for all nodes?
                            // `if geom.rect.contains(point)` confirms it.

                            // So if I have a Transform, I MUST return a point that looks "absolute" to the child
                            // but is logically transformed.
                            // Absolute child rect is NOT transformed by LayoutEngine.

                            // This means `geom.rect` for children of a Transform is WRONG if they are visually moved.
                            // BUT LayoutEngine doesn't know about Matrix4.
                            // So the children think they are at `(0,0)` relative to parent.

                            // To make hit test work:
                            // 1. Convert absolute `point` to `node_local_point`.
                            // 2. Apply inverse transform to `node_local_point` -> `transformed_local_point`.
                            // 3. Convert `transformed_local_point` back to absolute for children -> `transformed_absolute_point`.

                            let local_x = point.x - geom.rect.origin.x;
                            let local_y = point.y - geom.rect.origin.y;

                            let p = Vec4::new(local_x, local_y, 0.0, 1.0);
                            let inv = mat.inverse();
                            let transformed = inv * p;

                            child_point = LayoutPoint::new(
                                transformed.x + geom.rect.origin.x,
                                transformed.y + geom.rect.origin.y,
                            );
                        }

                        if let Some(hit) =
                            self.hit_test_recursive(*child, child_point, ir, snapshot)
                        {
                            return Some(hit);
                        }
                    }

                    match &node.op {
                        Op::Paint(_)
                        | Op::Layout(LayoutOp::Scroll { .. })
                        | Op::Layout(LayoutOp::Embed { .. }) => return Some(node_id),
                        _ => return None,
                    }
                }
                return None;
            }
        }
        None
    }

    /// Extract the pointer position from an input event, if applicable.
    ///
    /// Used by the custom-render-object event dispatch to perform a hit-test
    /// before delegating to render objects.  Returns `None` for keyboard and
    /// other non-positional events.
    fn event_point(event: &InputEvent) -> Option<LayoutPoint> {
        match event {
            InputEvent::Pointer(PointerEvent::Down { point, .. })
            | InputEvent::Pointer(PointerEvent::Up { point, .. })
            | InputEvent::Pointer(PointerEvent::Move { point, .. })
            | InputEvent::Pointer(PointerEvent::Cancel { point, .. })
            | InputEvent::Pointer(PointerEvent::Scroll { point, .. })
            | InputEvent::Pointer(PointerEvent::Magnify { point, .. }) => Some(*point),
            _ => None,
        }
    }

    fn find_autofocus_node(ir: &CoreIR) -> Option<WidgetId> {
        fn walk(ir: &CoreIR, node_id: WidgetId) -> Option<WidgetId> {
            let node = ir.nodes.get(&node_id)?;
            if let Op::Semantics(semantics) = &node.op {
                if semantics.autofocus && semantics.focusable && !semantics.disabled {
                    return Some(node_id);
                }
            }
            for child_id in &node.children {
                if let Some(found) = walk(ir, *child_id) {
                    return Some(found);
                }
            }
            None
        }

        ir.root.and_then(|root| walk(ir, root))
    }

    pub fn reconcile_resources(
        &mut self,
        declarations: Vec<RuntimeResourceDeclaration>,
    ) -> Result<()> {
        let now = self.clock().current_time();
        let mut existing = std::mem::take(&mut self.active_resources);
        let mut next = HashMap::new();

        for declaration in declarations {
            let key = declaration.key.clone();
            match existing.remove(&key) {
                Some(current)
                    if current.policy == declaration.policy
                        && current.deps == declaration.deps
                        && current.matches_kind(&declaration.kind) =>
                {
                    next.insert(key, current);
                }
                Some(current) if declaration.policy == ResourcePolicy::PreserveOnChange => {
                    next.insert(key, current);
                }
                Some(current) => {
                    self.stop_resource(&key, &current);
                    let replacement = self.start_resource(declaration, now);
                    next.insert(key, replacement);
                }
                None => {
                    let resource = self.start_resource(declaration, now);
                    next.insert(key, resource);
                }
            }
        }

        for (key, resource) in existing {
            self.stop_resource(&key, &resource);
        }

        self.active_resources = next;
        Ok(())
    }

    pub fn resource_generation(&self, key: &str) -> Option<u64> {
        self.active_resources
            .get(key)
            .map(|resource| resource.generation)
    }

    pub fn is_resource_current(&self, resource: &ResourceExecutionContext) -> bool {
        self.resource_generation(&resource.key) == Some(resource.generation)
    }

    fn start_resource(
        &mut self,
        declaration: RuntimeResourceDeclaration,
        now: CurrentTime,
    ) -> ActiveResource {
        let generation = self.next_resource_generation;
        self.next_resource_generation += 1;

        let context = ResourceExecutionContext {
            key: declaration.key.clone(),
            generation,
        };

        let kind = match declaration.kind {
            RuntimeResourceKind::Job(mut job) => {
                job.effect.resource = Some(context);
                self.enqueue_effect(job.effect);
                ActiveResourceKind::Job
            }
            RuntimeResourceKind::Service(mut service) => {
                service.effect.resource = Some(context);
                let (service_name, slot_key) = match &service.effect.effect {
                    crate::Effect::StartService(payload) => {
                        (payload.service_name.clone(), payload.slot_key.clone())
                    }
                    _ => unreachable!("service resource must lower to StartService"),
                };
                self.enqueue_effect(service.effect);
                ActiveResourceKind::Service {
                    service_name,
                    slot_key,
                }
            }
            RuntimeResourceKind::Timer(timer) => self.start_timer_resource(timer, now),
        };

        ActiveResource {
            generation,
            deps: declaration.deps,
            policy: declaration.policy,
            kind,
        }
    }

    fn start_timer_resource(&self, timer: TimerResource, now: CurrentTime) -> ActiveResourceKind {
        let interval_ms = timer.interval_ms.max(1);
        ActiveResourceKind::Timer {
            interval_ms,
            payload: timer.payload,
            on_tick: timer.on_tick,
            next_fire_at: if timer.immediate {
                now
            } else {
                now.saturating_add(interval_ms)
            },
        }
    }

    fn stop_resource(&mut self, key: &str, resource: &ActiveResource) {
        if let ActiveResourceKind::Service {
            service_name,
            slot_key,
        } = &resource.kind
        {
            self.enqueue_effect(EffectEnvelope {
                req_id: 0,
                effect: crate::Effect::StopService(ServiceStopPayload {
                    service_name: service_name.clone(),
                    slot_key: slot_key.clone(),
                }),
                on_ok: None,
                on_err: None,
                service_bindings: None,
                resource: Some(ResourceExecutionContext {
                    key: key.to_string(),
                    generation: resource.generation,
                }),
            });
        }
    }
}

impl ActiveResource {
    fn matches_kind(&self, kind: &RuntimeResourceKind) -> bool {
        matches!(
            (&self.kind, kind),
            (ActiveResourceKind::Job, RuntimeResourceKind::Job(_))
                | (
                    ActiveResourceKind::Timer { .. },
                    RuntimeResourceKind::Timer(_)
                )
                | (
                    ActiveResourceKind::Service { .. },
                    RuntimeResourceKind::Service(_)
                )
        )
    }
}