Skip to main content

uzor_framework/engine/
input.rs

1//! InputEngine: focus scopes, pointer capture, cook, hover / press / click,
2//! text and IME, caret blink (design §3.4).
3//!
4//! The one writer of per-window interaction state. Each window has one
5//! library [`InputCoordinator`] as its storage (registrations, hit index,
6//! [`TextFieldStore`], widget state), one
7//! library [`CookState`] for event-level cooking, the pointer accumulator
8//! the coordinator's next frame is fed from, the focus-scope stack, the
9//! pointer capture and the caret-blink phase. Pure and deterministic: every
10//! time-dependent op carries the host clock.
11//!
12//! ## Coordinator access
13//!
14//! State-mutating coordinator methods (`begin_frame`, `end_frame`,
15//! `set_focus`, `clear_focus`, `focus_next` / `focus_prev`,
16//! `grab_pointer` / `release_pointer`, `on_char`, `on_key`, `process_*`,
17//! `push_layer` / `pop_layer`, `set_cursor_pos`) live on
18//! [`CoordinatorDriver`](uzor::input::driver::CoordinatorDriver). This
19//! engine is the one writer; ban F7 keeps that trait out of every other
20//! framework module except `kernel/`. [`InputEngine::registrar`] hands
21//! compose a `&mut InputCoordinator` for registration and reads only.
22//! `focus_text_field` and `text_fields_mut` stay inherent (L-F1 does not
23//! move them).
24//!
25//! ## Pointer (routing, design §4.3)
26//!
27//! - [`InputOp::Pointer`] is step 1: the engine's `CookState` counts clicks
28//!   (single / double / triple within `DOUBLE_CLICK_WINDOW_S` and
29//!   `MULTI_CLICK_MAX_DIST_PX`) and arms drags past `DRAG_THRESHOLD_PX`,
30//!   and the answer says whether a [`Capture`] owns the event (step 2). A
31//!   capture bypasses every hit test until the button is released (or the
32//!   OS cancels the gesture); the release itself still goes to the owner.
33//! - [`InputOp::Deliver`] is step 5: an event nothing above claimed enters
34//!   the coordinator's next-frame input (press / release edges; positions
35//!   always follow the pointer). Claimed presses never reach content. A
36//!   text-field drag writes the store selection on the press and on each
37//!   armed move: paint reads that store before `end_frame`, which only
38//!   commits the range on release.
39//! - [`InputOp::BeginFrame`] feeds the accumulated input to the coordinator
40//!   with `InputState::time` stamped from the host clock, so the
41//!   coordinator's own cook (fed in `end_frame`) reports real
42//!   `double_clicked` / `triple_clicked`. [`InputOp::EndFrame`] evaluates
43//!   the frame's registrations into hover and this frame's clicks.
44//!
45//! ## Focus scopes (H2 §3)
46//!
47//! A stack of `{ owner, members, saved focus }`. Pushing saves and clears
48//! the current focus; while a scope is active, focus can only move to one
49//! of its members (`FocusOp::Set` outside is a no-op, Tab / Shift+Tab cycle
50//! the members registered this frame in list order); popping the active
51//! scope with `restore` puts the saved focus back (a saved text field
52//! keeps its engagement), without `restore` clears it. Popping a scope
53//! below the top hands its saved focus to the scope above it. A click
54//! that focuses a text field outside the active scope is reverted at
55//! `EndFrame`, so focus is always inside the active scope. With no scope,
56//! Tab cycles every focusable widget (the coordinator's global order).
57//!
58//! ## Text and IME
59//!
60//! Key step 1 ([`InputOp::Key`]): with a focused text field, its editing
61//! chords (characters, Backspace / Delete, arrows with Shift / Ctrl word
62//! movement, Home / End, Ctrl+A / C / X / V, Enter) are consumed before any
63//! keymap binding; Tab / Shift+Tab move focus. Everything else is passed on
64//! ([`InputEffect::KeyPassed`]); Escape is never consumed here, so an
65//! overlay can close on it (step 2). IME preedit goes to
66//! `TextFieldStore::preedit_set` (an overlay span, never in the buffer);
67//! commit to `ime_commit`. Copy / cut report [`InputEffect::CopyText`]
68//! (masked fields never copy); paste asks the host with
69//! [`InputEffect::NeedPaste`] under an engine-minted ticket (at or above
70//! [`INPUT_TICKET_BASE`]) and inserts the [`InputOp::Clipboard`] answer if
71//! the same field is still focused. The IME caret area and the IME-allowed
72//! flag are reported only when they change.
73//!
74//! ## Clipboard for custom widgets
75//!
76//! One widget-facing contract on every host. Paste: the platform gesture's
77//! text ([`InputOp::Paste`], from `InputEvent::Paste` — the web host's DOM
78//! `paste` event) goes to the focused text field, else to the app as
79//! `UnhandledInput::Paste` ([`InputEffect::Pasted`]). Ctrl/Cmd+V with no
80//! field focused reads under an engine ticket like a field paste; a native
81//! host answers from the clipboard crate, the web host leaves it to the
82//! paste event of the same gesture (no `readText` permission prompt, no
83//! second insert: the paste settles the read). Copy / cut: the focused
84//! custom widget sets its answer ahead with `ClipboardCmd::Offer`; Ctrl/Cmd+C
85//! or X with no field and no page selection copies it
86//! ([`InputEffect::CopyText`]) and still passes the key on. The web host
87//! also writes the offer in the DOM `copy` / `cut` event (same gesture).
88//! A focused `BlackboxPanel` owns Ctrl/Cmd+A (no page-text escalation).
89//!
90//! Manual check (web): focus a non-field custom widget, put text on the OS
91//! clipboard, press Ctrl+V — the app gets `UnhandledInput::Paste` with it;
92//! in a text field the text lands once. Offer "x", press Ctrl+C, paste
93//! elsewhere: "x".
94//!
95//! ## Caret blink
96//!
97//! While a text field is focused and engaged (the user clicked or typed
98//! into it) and the window has OS focus, the engine keeps one deadline
99//! armed at the next blink edge ([`InputEffect::CaretDeadline`]; the kernel
100//! arms `TimerOwner::CaretBlink { win }`). Visibility is the store's
101//! `cursor_visible(now_ms)` (500 ms phases) anchored at the last caret
102//! change: any edit, caret move, selection, preedit or focus change
103//! restarts the phase visible. At each edge ([`InputEngine::tick`]) the
104//! engine flips visibility and asks for a repaint of only that field
105//! ([`InputEffect::InvalidateField`] with the field's last drawn rect; the
106//! kernel maps it to the region containing it). Blur, loss of window
107//! focus, un-engagement or the field being unregistered disarms it.
108//!
109//! ## Plain-text selection (T2)
110//!
111//! One selection owner per window, held here: selectable plain text has no
112//! store (unlike text fields), so the app reports each selectable widget's
113//! content and line geometry every frame through
114//! [`InputEngine::update_selectable`] (the compose-phase door, mirroring
115//! `TextFieldStore::update_field`; not revisioned — the change is evaluated
116//! at [`InputOp::EndFrame`]). A widget not reported this frame stops being
117//! selectable and its selection drops. The owner state is a small
118//! `Vec<(WidgetId, TextSelection)>` — usually one entry; a panel / window
119//! Ctrl+A escalation selects several widgets at once.
120//!
121//! A press on a selectable widget records the char under the pointer as
122//! the drag anchor; no pointer capture is taken — the cook state tracks
123//! the press window-wide, exactly the mechanism text fields use, and
124//! `char_at_point` clamps out-of-rect positions to the line ends. While
125//! the press is armed (or its release just ended the drag) the selection
126//! extends anchor → current pointer char every frame, so the highlight is
127//! live during the drag. A release that was not a drag and lands on the
128//! same selectable widget is a click: the selection collapses / expands to
129//! word / line by the press sequence's click count (the engine's own
130//! `CookState`, not the coordinator's click reporting — a label registers
131//! `Sense::HOVER` + `select`, no `click` bit, and must not start
132//! swallowing clicks). A press anywhere else clears the selection.
133//! Escape and focus changes do not clear it (browser-like).
134//!
135//! Keys, no focused text field: Ctrl+C with a non-empty selection reports
136//! [`InputEffect::CopyText`] (the same conduction as a field copy — the
137//! kernel enqueues `WindowCommand::ClipboardWrite`); with nothing selected
138//! the key routes on. Ctrl+A selects all with escalation
139//! widget → panel → window: the panel step takes every selectable whose
140//! rect is inside the nearest ancestor registered as `Panel` /
141//! `BlackboxPanel` (via `widget_parent`), the window step every selectable
142//! in the window; multi-widget selections copy in reading order
143//! (top-left, newline-joined). The escalation level resets on any
144//! pointer-driven selection.
145//!
146//! Every selection change repaints through the existing
147//! [`InputEffect::InvalidateField`] with the widget's rect, and is
148//! revisioned (the map is observable through
149//! [`InputEngineView::selections`]).
150//!
151//! Out of scope (recorded for the owner): word-granularity drag after a
152//! double click, Shift+click extend, drag-and-drop of selected text.
153//!
154//! ## Revision
155//!
156//! Bumped exactly when observable state changes: the window set, focus,
157//! scopes, capture, hover, pressed, this frame's clicks, the focused
158//! field's caret (text, cursor, selection, preedit, engagement), caret
159//! visibility and the plain-text selections. Pointer positions, cook
160//! bookkeeping, IME bookkeeping and a pending paste are not revisioned
161//! (they never appear in the snapshot).
162
163use crate::types::vecmap::VecMap;
164use std::collections::HashMap;
165use std::fmt;
166
167use smallvec::SmallVec;
168use uzor::input::core::cook::CookState;
169use uzor::input::driver::CoordinatorDriver;
170use uzor::input::text::selection::{char_at_point, SelectionLine, TextSelection};
171use uzor::input::{
172    InputCoordinator, InputState, KeyCode, KeyPress, ModifierKeys, MouseButton, TextAction,
173    TextFieldStore, WidgetKind,
174};
175use uzor::{Rect, WidgetId};
176
177use crate::types::bus::{
178    ClipboardResult, ImeInput, KeyInput, KeyState, PointerInput, WheelDelta, WheelInput,
179};
180use crate::types::ids::{Revision, ScopeId, Seconds, Ticket, WindowId};
181use crate::types::intent::TextIntent;
182use crate::types::ops::{
183    Capture, CookedPointer, FocusOp, InputEffect, InputOp, PointerTarget, ScopeOwner,
184};
185use crate::types::snapshot::InputView;
186
187/// Effects of one InputEngine op or tick.
188pub type InputEffects = SmallVec<[InputEffect; 2]>;
189
190/// First clipboard ticket the engine mints for paste. App tickets stay
191/// below it, so a `ClipboardResult` at or above it belongs to this engine.
192pub const INPUT_TICKET_BASE: u64 = 1 << 63;
193
194/// One caret blink phase (visible or hidden), the store's 500 ms.
195// Caret blink cadence a host applies when painting text fields.
196#[allow(dead_code)]
197pub const CARET_BLINK_INTERVAL: Seconds = Seconds(0.5);
198
199const CARET_BLINK_MS: u64 = 500;
200
201/// Logical pixels per wheel line, for pixel-unit wheel deltas (the same
202/// factor the desktop input bridge uses); the coordinator counts lines.
203const WHEEL_PIXELS_PER_LINE: f64 = 20.0;
204
205// ---------------------------------------------------------------------------
206// Per-window state
207// ---------------------------------------------------------------------------
208
209/// Pointer input gathered between two frames; becomes the coordinator's
210/// `InputState` at `BeginFrame`.
211#[derive(Clone, Debug, Default)]
212struct PointerAccum {
213    pos: Option<(f64, f64)>,
214    prev_pos: Option<(f64, f64)>,
215    button_down: Option<MouseButton>,
216    clicked: Option<MouseButton>,
217    /// Secondary-button release not yet read by a frame (context menus).
218    context: Option<(f64, f64)>,
219    mods: ModifierKeys,
220    scroll: (f64, f64),
221    /// The scroll came (at least partly) as pixel deltas (trackpad / smooth wheel).
222    scroll_precise: bool,
223}
224
225/// The focus the engine restores when a scope closes.
226#[derive(Clone, Debug, PartialEq, Eq)]
227struct SavedFocus {
228    id: WidgetId,
229    /// The saved widget was an engaged text field.
230    engaged: bool,
231}
232
233#[derive(Clone, Debug)]
234struct FocusScope {
235    owner: ScopeOwner,
236    members: Vec<WidgetId>,
237    saved: Option<SavedFocus>,
238}
239
240/// Plain selectable text reported for one frame through the compose door
241/// [`InputEngine::update_selectable`].
242#[derive(Clone, Debug)]
243struct SelectableText {
244    text: String,
245    lines: Vec<SelectionLine>,
246}
247
248/// The compose-phase sink a hook reports its selectable plain text into (the `Widgets`
249/// face): the DOM's "every text node is selectable" made explicit — a widget reported here
250/// gets press-drag / double / triple-click selection and Ctrl+C copy from the input engine.
251#[derive(Clone, Debug, Default)]
252pub struct Selectables(HashMap<WidgetId, SelectableText>, HashMap<WidgetId, WidgetId>);
253
254impl Selectables {
255    /// Report one selectable text widget for this frame: its text and, per wrapped line,
256    /// the char range, origin and glyph boundaries (`SelectionLine`).
257    pub fn report(&mut self, widget: impl Into<WidgetId>, text: impl Into<String>, lines: Vec<SelectionLine>) {
258        self.0.insert(widget.into(), SelectableText { text: text.into(), lines });
259    }
260    /// A press / click on `member` (a hit region, e.g. one wrapped line or one
261    /// bubble) acts on the selectable `owner`: one selection spans many regions,
262    /// like a DOM selection dragged across several elements of one container.
263    pub fn alias(&mut self, member: impl Into<WidgetId>, owner: impl Into<WidgetId>) {
264        self.1.insert(member.into(), owner.into());
265    }
266    fn contains_key(&self, w: &WidgetId) -> bool {
267        self.0.contains_key(w)
268    }
269}
270
271/// A press that began on a selectable widget: the selection drag anchor.
272#[derive(Clone, Debug)]
273struct PressSel {
274    widget: WidgetId,
275    anchor: usize,
276}
277
278/// Where a Ctrl+A escalation stands for its widget.
279#[derive(Clone, Copy, Debug, PartialEq, Eq)]
280enum EscLevel {
281    /// Last select-all covered only the widget itself.
282    Widget,
283    /// … every selectable inside the nearest panel ancestor.
284    Panel,
285    /// … every selectable in the window.
286    Window,
287}
288
289/// Everything about the focused text field whose change restarts the
290/// blink phase (geometry is deliberately not part of it).
291#[derive(Clone, Debug, PartialEq, Eq)]
292struct CaretKey {
293    field: WidgetId,
294    engaged: bool,
295    text: String,
296    cursor: usize,
297    selection: Option<usize>,
298    preedit: String,
299    preedit_cursor: usize,
300}
301
302/// The engine's own focus record: the widget the view reports.
303#[derive(Clone, Debug, PartialEq, Eq)]
304struct Focused {
305    id: WidgetId,
306    /// Focused through the text store (a registered text field).
307    field: bool,
308}
309
310struct PerWindowInput {
311    coord: InputCoordinator,
312    /// Per-widget persistent typed state (scroll offsets, expand flags);
313    /// the compose-phase door for the app hook's `Widgets` face (design
314    /// §3.4 names it here; F3 had no consumer, F7 does).
315    states: uzor::app_context::StateRegistry,
316    cook: CookState,
317    pointer: PointerAccum,
318    capture: Option<Capture>,
319    scopes: Vec<FocusScope>,
320    focus: Option<Focused>,
321    hover: Option<WidgetId>,
322    pressed: Option<WidgetId>,
323    clicked: SmallVec<[(WidgetId, u8); 2]>,
324    os_focused: bool,
325    caret: Option<CaretKey>,
326    blink_anchor_ms: u64,
327    caret_visible: bool,
328    armed: Option<Seconds>,
329    ime_area: Option<Rect>,
330    ime_allowed: bool,
331    /// An engine-minted paste read in flight: the field it was for, or
332    /// `None` (no text field: the answer goes to the app as pasted text).
333    pending_paste: Option<(Ticket, Option<WidgetId>)>,
334    /// The app's copy offer (`ClipboardCmd::Offer`).
335    offer: Option<String>,
336    // Plain-text selection (T2). `selectables` is last completed frame's
337    // reported set (read by pointer ops); the compose door fills
338    // `reported` and EndFrame swaps them.
339    selectables: HashMap<WidgetId, SelectableText>,
340    /// Hit regions acting on a selectable (last completed frame's `Selectables::alias`).
341    sel_alias: HashMap<WidgetId, WidgetId>,
342    reported: Selectables,
343    selections: Vec<(WidgetId, TextSelection)>,
344    press_sel: Option<PressSel>,
345    drag_ended: bool,
346    escalation: Option<(WidgetId, EscLevel)>,
347    /// `:focus-visible` modality: a non-modifier key press turns it on, a
348    /// pointer press turns it off; programmatic focus keeps the current one.
349    focus_visible: bool,
350    /// Clicks from Enter / Space on a focused control, joined to the next
351    /// `EndFrame`'s clicks.
352    key_clicks: Vec<WidgetId>,
353    /// The control a Space press armed; its release activates it.
354    space_armed: Option<WidgetId>,
355}
356
357/// Which keys activate a focused widget of `kind`, as `(Enter, Space)`,
358/// matching the DOM: a `<button>` clicks on Enter press and Space release,
359/// a link on Enter only, a checkbox / radio / switch on Space only.
360fn activation(kind: Option<WidgetKind>) -> (bool, bool) {
361    use WidgetKind as K;
362    match kind {
363        Some(K::Link) => (true, false),
364        Some(K::Checkbox | K::Radio | K::Toggle) => (false, true),
365        Some(K::Button | K::CloseButton | K::ChromeTab | K::DropdownTrigger | K::Item | K::ColorSwatch | K::Custom) | None => (true, true),
366        Some(_) => (false, false),
367    }
368}
369
370impl PerWindowInput {
371    fn new() -> Self {
372        Self {
373            coord: InputCoordinator::new(),
374            states: uzor::app_context::StateRegistry::new(),
375            cook: CookState::default(),
376            pointer: PointerAccum::default(),
377            capture: None,
378            scopes: Vec::new(),
379            focus: None,
380            hover: None,
381            pressed: None,
382            clicked: SmallVec::new(),
383            // A window the host just created is assumed focused until the
384            // host says otherwise (not every host sends the initial echo).
385            os_focused: true,
386            caret: None,
387            blink_anchor_ms: 0,
388            caret_visible: false,
389            armed: None,
390            ime_area: None,
391            ime_allowed: false,
392            pending_paste: None,
393            offer: None,
394            selectables: HashMap::new(),
395            sel_alias: HashMap::new(),
396            reported: Selectables::default(),
397            selections: Vec::new(),
398            press_sel: None,
399            drag_ended: false,
400            escalation: None,
401            focus_visible: false,
402            key_clicks: Vec::new(),
403            space_armed: None,
404        }
405    }
406
407    // -- focus ----------------------------------------------------------------
408
409    /// `id` may take focus: no scope is active, or it is a member of the
410    /// active one.
411    fn allowed(&self, id: &WidgetId) -> bool {
412        self.scopes.last().is_none_or(|s| s.members.contains(id))
413    }
414
415    /// Focus `id` in the coordinator (text fields through the store, which
416    /// also syncs widget focus; anything else blurs the store). No guard.
417    fn focus_raw(&mut self, id: WidgetId) {
418        let field = self.coord.text_fields().has_field(&id);
419        if field {
420            self.coord.focus_text_field(&id);
421        } else {
422            self.coord.set_focus(id.clone());
423        }
424        self.focus = Some(Focused { id, field });
425    }
426
427    fn clear_raw(&mut self) -> bool {
428        let had = self.focus.is_some() || self.coord.text_fields().focused().is_some();
429        self.coord.clear_focus();
430        self.focus = None;
431        had
432    }
433
434    fn focused_id(&self) -> Option<&WidgetId> {
435        self.focus.as_ref().map(|f| &f.id)
436    }
437
438    /// Tab order candidates: the active scope's members registered this
439    /// frame, in list order, without negative-`tabindex` ones.
440    fn scoped_candidates(&self) -> Option<Vec<WidgetId>> {
441        let scope = self.scopes.last()?;
442        Some(
443            scope
444                .members
445                .iter()
446                .filter(|m| self.coord.widget_rect(m).is_some() && self.coord.tab_index(m) >= 0)
447                .cloned()
448                .collect(),
449        )
450    }
451
452    /// Tab / Shift+Tab. `None` = there was nothing to move to.
453    fn cycle(&mut self, forward: bool) -> Option<bool> {
454        let before = self.focus.clone();
455        match self.scoped_candidates() {
456            Some(list) => {
457                if list.is_empty() {
458                    return None;
459                }
460                let n = list.len();
461                let at = self
462                    .focused_id()
463                    .and_then(|f| list.iter().position(|m| m == f));
464                let next = match (at, forward) {
465                    (Some(i), true) => (i + 1) % n,
466                    (None, true) => 0,
467                    (Some(i), false) => (i + n - 1) % n,
468                    (None, false) => n - 1,
469                };
470                if self.focused_id() != Some(&list[next]) {
471                    self.focus_raw(list[next].clone());
472                }
473            }
474            None => {
475                if forward {
476                    self.coord.focus_next();
477                } else {
478                    self.coord.focus_prev();
479                }
480                let target = self.coord.focused_widget().cloned()?;
481                if self.focused_id() != Some(&target) || !self.store_matches_focus() {
482                    self.focus_raw(target);
483                }
484            }
485        }
486        Some(self.focus != before)
487    }
488
489    /// The text store's focus agrees with the engine's record.
490    fn store_matches_focus(&self) -> bool {
491        let store = self.coord.text_fields().focused();
492        match &self.focus {
493            Some(f) if f.field => store == Some(&f.id),
494            _ => store.is_none(),
495        }
496    }
497
498    fn focus_op(
499        &mut self,
500        win: WindowId,
501        op: FocusOp,
502        next_scope: &mut u64,
503        fx: &mut InputEffects,
504    ) -> bool {
505        match op {
506            FocusOp::Set(id) => {
507                if !self.allowed(&id) || self.focused_id() == Some(&id) {
508                    return false;
509                }
510                self.focus_raw(id);
511                true
512            }
513            FocusOp::Clear => self.clear_raw(),
514            FocusOp::Next => self.cycle(true).unwrap_or(false),
515            FocusOp::Prev => self.cycle(false).unwrap_or(false),
516            FocusOp::PushScope { owner, members } => {
517                if self.scopes.iter().any(|s| s.owner == owner) {
518                    return self.set_members(&owner, members);
519                }
520                let saved = self.focus.as_ref().map(|f| SavedFocus {
521                    engaged: f.field && self.coord.text_fields().is_engaged(&f.id),
522                    id: f.id.clone(),
523                });
524                self.clear_raw();
525                self.scopes.push(FocusScope {
526                    owner: owner.clone(),
527                    members,
528                    saved,
529                });
530                *next_scope += 1;
531                fx.push(InputEffect::ScopePushed {
532                    win,
533                    owner,
534                    scope: ScopeId(*next_scope),
535                });
536                true
537            }
538            FocusOp::SetMembers { owner, members } => self.set_members(&owner, members),
539            FocusOp::PopScope { owner, restore } => self.pop_scope(&owner, restore),
540        }
541    }
542
543    fn set_members(&mut self, owner: &ScopeOwner, members: Vec<WidgetId>) -> bool {
544        let Some(i) = self.scopes.iter().position(|s| &s.owner == owner) else {
545            return false;
546        };
547        if self.scopes[i].members == members {
548            return false;
549        }
550        self.scopes[i].members = members;
551        let active = i + 1 == self.scopes.len();
552        if active {
553            if let Some(f) = self.focused_id().cloned() {
554                if !self.allowed(&f) {
555                    self.clear_raw();
556                }
557            }
558        }
559        true
560    }
561
562    fn pop_scope(&mut self, owner: &ScopeOwner, restore: bool) -> bool {
563        let Some(i) = self.scopes.iter().position(|s| &s.owner == owner) else {
564            return false;
565        };
566        let scope = self.scopes.remove(i);
567        if i < self.scopes.len() {
568            // A scope below the top closed: the scope above saved a focus
569            // inside it, which is gone; it inherits the closed scope's.
570            self.scopes[i].saved = scope.saved;
571            return true;
572        }
573        self.clear_raw();
574        if let (true, Some(saved)) = (restore, scope.saved) {
575            if self.allowed(&saved.id) {
576                self.focus_raw(saved.id.clone());
577                if saved.engaged {
578                    self.coord.text_fields_mut().engage(&saved.id);
579                }
580            }
581        }
582        true
583    }
584
585    /// After `end_frame`: accept a click-focus into a text field, revert
586    /// one outside the active scope, and forget a field that disappeared.
587    fn reconcile_focus(&mut self) -> bool {
588        let store = self.coord.text_fields().focused().cloned();
589        match (store, self.focus.clone()) {
590            (Some(s), Some(f)) if f.field && s == f.id => false,
591            (Some(s), _) if self.allowed(&s) => {
592                self.coord.set_focus(s.clone());
593                self.focus = Some(Focused { id: s, field: true });
594                true
595            }
596            (Some(_), prev) => {
597                // Clicked into a field the active scope does not contain.
598                self.coord.text_fields_mut().blur();
599                if let Some(f) = prev.filter(|f| f.field) {
600                    let engaged = self.coord.text_fields().is_engaged(&f.id);
601                    self.coord.focus_text_field(&f.id);
602                    if engaged {
603                        self.coord.text_fields_mut().engage(&f.id);
604                    }
605                }
606                false
607            }
608            (None, Some(f)) if f.field => {
609                // The focused field was unregistered or blurred.
610                self.coord.clear_focus();
611                self.focus = None;
612                true
613            }
614            (None, _) => false,
615        }
616    }
617
618    // -- pointer --------------------------------------------------------------
619
620    fn set_capture(&mut self, capture: Option<Capture>) -> bool {
621        if self.capture == capture {
622            return false;
623        }
624        if let Some(Capture::Widget(_)) = &self.capture {
625            self.coord.release_pointer();
626        }
627        if let Some(Capture::Widget(id)) = &capture {
628            self.coord.grab_pointer(id.clone());
629        }
630        self.capture = capture;
631        true
632    }
633
634    fn cook(&mut self, win: WindowId, now: Seconds, input: PointerInput) -> (bool, CookedPointer) {
635        let t = now.get();
636        let target = match &self.capture {
637            Some(c) => PointerTarget::Captured(c.clone()),
638            None => PointerTarget::HitTest,
639        };
640        let mut drag_started = false;
641        let mut ended_drag = false;
642        let mut changed = false;
643        // Any press (content, chrome, dock) ends keyboard modality; the
644        // ring it hides needs a repaint.
645        if matches!(input, PointerInput::Down { .. }) && self.focus_visible {
646            self.focus_visible = false;
647            changed = true;
648        }
649        match input {
650            PointerInput::Moved { pos, mods } => {
651                self.pointer.pos = Some((pos.x, pos.y));
652                self.pointer.mods = mods;
653                drag_started = self.cook.motion(pos.x, pos.y).drag_started;
654            }
655            PointerInput::Down { pos, button, mods } => {
656                self.pointer.pos = Some((pos.x, pos.y));
657                self.pointer.mods = mods;
658                // A second button during a held press does not restart it.
659                if self.cook.press_origin.is_none() {
660                    self.cook.press(pos.x, pos.y, button, t);
661                }
662            }
663            PointerInput::Up { pos, button, mods } => {
664                self.pointer.pos = Some((pos.x, pos.y));
665                self.pointer.mods = mods;
666                if self.cook.press_origin.map(|o| o.button) == Some(button) {
667                    ended_drag = self.cook.release(pos.x, pos.y, button, t);
668                    self.drag_ended |= ended_drag;
669                    changed = self.set_capture(None);
670                }
671            }
672            PointerInput::Entered | PointerInput::RawDelta { .. } => {}
673            PointerInput::Left => self.pointer.pos = None,
674            PointerInput::Cancelled => {
675                self.cook.press_origin = None;
676                self.cook.drag_armed = false;
677                self.pointer.button_down = None;
678                changed = self.set_capture(None);
679                changed |= self.pressed.take().is_some();
680                self.press_sel = None;
681                self.drag_ended = false;
682            }
683        }
684        // A drag starting on a pressed drag-sensitive widget captures the
685        // pointer for it (design §4.3, routing step 2): from here every
686        // event goes to the widget until pointer-up.
687        if drag_started {
688            let grab = self
689                .pressed
690                .clone()
691                .filter(|id| self.coord.widget_sense(id).is_some_and(|s| s.drag));
692            if let Some(id) = grab {
693                changed = self.set_capture(Some(Capture::Widget(id)));
694            }
695        }
696        let cooked = CookedPointer {
697            win,
698            input,
699            click_count: self.cook.click_count,
700            drag_armed: self.cook.drag_armed,
701            drag_started,
702            ended_drag,
703            target,
704        };
705        (changed, cooked)
706    }
707
708    /// The content widget a pointer at `pos` goes to: the capturing widget,
709    /// else the topmost hit of last frame's registrations.
710    fn content_target(&self, pos: Option<(f64, f64)>) -> Option<WidgetId> {
711        if let Some(Capture::Widget(id)) = &self.capture {
712            return Some(id.clone());
713        }
714        let (x, y) = pos?;
715        self.coord.hit_test_now(x, y)
716    }
717
718    fn deliver(
719        &mut self,
720        win: WindowId,
721        input: PointerInput,
722        fx: &mut InputEffects,
723    ) -> (bool, Option<WidgetId>) {
724        match input {
725            PointerInput::Moved { pos, .. } => {
726                self.pointer.pos = Some((pos.x, pos.y));
727                // A held drag repaints so hooks see the moving pointer; so does a move
728                // onto another widget (or off all of them), so hover paints without
729                // waiting for the next unrelated input.
730                let target = self.content_target(self.pointer.pos);
731                let mut changed = self.pointer.button_down.is_some() || target != self.hover;
732                // `cook` already armed this move. The highlight is the store
733                // range, and the frame paints it before `end_frame`.
734                if self.pointer.button_down == Some(MouseButton::Left)
735                    && self.cook.drag_armed
736                    && self.coord.text_fields().drag_active()
737                {
738                    self.coord.text_fields_mut().on_drag_move(pos.x);
739                    changed = true;
740                }
741                (changed, target)
742            }
743            PointerInput::Down { pos, button, .. } => {
744                self.pointer.pos = Some((pos.x, pos.y));
745                self.pointer.button_down = Some(button);
746                // A release no frame has evaluated yet belongs to the previous
747                // gesture; carried into this press it would click whatever is
748                // under the pointer now.
749                self.pointer.clicked = None;
750                let target = self.content_target(self.pointer.pos);
751                let changed = self.pressed != target;
752                self.pressed.clone_from(&target);
753                let t = target.as_ref().map(|t| self.sel_owner(t));
754                let sel_changed = self.press_down(win, t.as_ref(), pos.x, pos.y, fx);
755                if button == MouseButton::Left {
756                    self.arm_text_drag(target.as_ref(), pos.x);
757                } else if self.coord.text_fields().drag_active() {
758                    self.coord.text_fields_mut().on_drag_end();
759                }
760                (changed | sel_changed, target)
761            }
762            PointerInput::Up { pos, button, .. } => {
763                self.pointer.pos = Some((pos.x, pos.y));
764                self.pointer.button_down = None;
765                self.pointer.clicked = Some(button);
766                if button == MouseButton::Right {
767                    self.pointer.context = Some((pos.x, pos.y));
768                }
769                let target = self.content_target(self.pointer.pos);
770                let _ = self.pressed.take();
771                let t = target.as_ref().map(|t| self.sel_owner(t));
772                let _ = self.release_select(win, t.as_ref(), fx);
773                // A real drag keeps the range (`anchor != cursor`); a click
774                // drops the degenerate one. `end_frame` then commits either
775                // `select_drag` or `select_at_click_count`.
776                if button == MouseButton::Left && self.coord.text_fields().drag_active() {
777                    self.coord.text_fields_mut().on_drag_end();
778                }
779                // Always repaint on release: only a frame evaluates the click
780                // (`pointer.clicked`), on any cadence.
781                (true, target)
782            }
783            PointerInput::Entered
784            | PointerInput::Left
785            | PointerInput::Cancelled
786            | PointerInput::RawDelta { .. } => (false, None),
787        }
788    }
789
790    /// Press on a text field: place the caret and arm a drag so later moves
791    /// extend the selection while the button is held. A double or triple
792    /// click is left to `end_frame` (`select_at_click_count` selects the
793    /// word or the line). Any other press ends a stale text drag so it
794    /// cannot follow the pointer onto another control.
795    fn arm_text_drag(&mut self, target: Option<&WidgetId>, x: f64) {
796        let field = match target {
797            Some(id)
798                if self.coord.widget_sense(id).is_some_and(|s| s.text)
799                    && self.coord.text_fields().has_field(id) =>
800            {
801                Some(id.clone())
802            }
803            _ => None,
804        };
805        if let Some(id) = field {
806            if self.cook.click_count <= 1 {
807                self.coord.text_fields_mut().begin_drag_at(id, x);
808                return;
809            }
810        }
811        if self.coord.text_fields().drag_active() {
812            self.coord.text_fields_mut().on_drag_end();
813        }
814    }
815
816    /// A release on the same selectable widget the press began on, and
817    /// the press never crossed the drag threshold: a click. The selection
818    /// collapses / expands to word / line by the click count.
819    fn release_select(
820        &mut self,
821        win: WindowId,
822        target: Option<&WidgetId>,
823        fx: &mut InputEffects,
824    ) -> bool {
825        if self.drag_ended {
826            return false;
827        }
828        let Some(p) = self.press_sel.clone() else {
829            return false;
830        };
831        if target != Some(&p.widget) {
832            return false;
833        }
834        let Some(st) = self.selectables.get(&p.widget) else {
835            return false;
836        };
837        let sel = TextSelection::for_click_count(&st.text, p.anchor, self.cook.click_count.max(1));
838        let changed = self.set_selection(win, &p.widget, sel, fx);
839        self.escalation = Some((p.widget, EscLevel::Widget));
840        changed
841    }
842
843    fn wheel(&mut self, input: WheelInput) -> Option<WidgetId> {
844        let (dx, dy) = match input.delta {
845            WheelDelta::Lines { x, y } => (x, y),
846            WheelDelta::Pixels { x, y } => {
847                self.pointer.scroll_precise = true;
848                (x / WHEEL_PIXELS_PER_LINE, y / WHEEL_PIXELS_PER_LINE)
849            }
850        };
851        self.pointer.pos = Some((input.pos.x, input.pos.y));
852        self.pointer.mods = input.mods;
853        self.pointer.scroll.0 += dx;
854        self.pointer.scroll.1 += dy;
855        if let Some(Capture::Widget(id)) = &self.capture {
856            return Some(id.clone());
857        }
858        self.coord.process_scroll(input.pos.x, input.pos.y)
859    }
860
861    // -- plain-text selection (T2) -------------------------------------------
862
863    /// The selectable a hit widget acts on (itself unless aliased).
864    fn sel_owner(&self, w: &WidgetId) -> WidgetId {
865        self.sel_alias.get(w).unwrap_or(w).clone()
866    }
867
868    fn sel_get(&self, widget: &WidgetId) -> Option<TextSelection> {
869        self.selections
870            .iter()
871            .find(|(w, _)| w == widget)
872            .map(|(_, s)| *s)
873    }
874
875    fn sel_set(&mut self, widget: WidgetId, sel: TextSelection) -> bool {
876        if let Some(slot) = self.selections.iter_mut().find(|(w, _)| *w == widget) {
877            if slot.1 == sel {
878                return false;
879            }
880            slot.1 = sel;
881            return true;
882        }
883        self.selections.push((widget, sel));
884        true
885    }
886
887    fn sel_remove(&mut self, widget: &WidgetId) -> bool {
888        let before = self.selections.len();
889        self.selections.retain(|(w, _)| w != widget);
890        self.selections.len() != before
891    }
892
893    /// Set one widget's selection, repainting it on change.
894    fn set_selection(
895        &mut self,
896        win: WindowId,
897        widget: &WidgetId,
898        sel: TextSelection,
899        fx: &mut InputEffects,
900    ) -> bool {
901        if !self.sel_set(widget.clone(), sel) {
902            return false;
903        }
904        fx.push(InputEffect::InvalidateField {
905            win,
906            rect: self.coord.widget_rect(widget),
907        });
908        true
909    }
910
911    /// Drop every selection, repainting on change.
912    fn clear_selections(&mut self, win: WindowId, fx: &mut InputEffects) -> bool {
913        if self.selections.is_empty() {
914            return false;
915        }
916        for (w, _) in &self.selections {
917            fx.push(InputEffect::InvalidateField {
918                win,
919                rect: self.coord.widget_rect(w),
920            });
921        }
922        self.selections.clear();
923        self.escalation = None;
924        true
925    }
926
927    /// Selectable widget ids in reading order (top-left), for multi-widget
928    /// select-all and copy concatenation.
929    fn selectable_ids_by_row(&self) -> Vec<WidgetId> {
930        let mut ids: Vec<(f64, f64, WidgetId)> = self
931            .selectables
932            .keys()
933            .map(|w| {
934                let r = self
935                    .coord
936                    .widget_rect(w)
937                    .unwrap_or_else(|| Rect::new(0.0, 0.0, 0.0, 0.0));
938                (r.y, r.x, w.clone())
939            })
940            .collect();
941        uzor::sort::sort_by(&mut ids, |a, b| a.0.total_cmp(&b.0).then_with(|| a.1.total_cmp(&b.1)));
942        ids.into_iter().map(|(_, _, w)| w).collect()
943    }
944
945    /// The selected text of every selected widget, reading order, newline
946    /// joined; `None` when nothing (or only carets) is selected.
947    fn selected_text_concat(&self) -> Option<String> {
948        if self.selections.is_empty() {
949            return None;
950        }
951        let mut parts: Vec<String> = Vec::new();
952        for w in self.selectable_ids_by_row() {
953            if let (Some(sel), Some(st)) = (self.sel_get(&w), self.selectables.get(&w)) {
954                let s = sel.selected_text(&st.text);
955                if !s.is_empty() {
956                    parts.push(s.to_owned());
957                }
958            }
959        }
960        if parts.is_empty() {
961            None
962        } else {
963            Some(parts.join("\n"))
964        }
965    }
966
967    /// The rect of the nearest ancestor registered as `Panel` /
968    /// `BlackboxPanel`, if any — the Ctrl+A escalation boundary.
969    fn nearest_panel_rect(&self, widget: &WidgetId) -> Option<Rect> {
970        let mut cur = self.coord.widget_parent(widget);
971        while let Some(p) = cur {
972            if matches!(
973                self.coord.widget_kind(&p),
974                Some(WidgetKind::Panel | WidgetKind::BlackboxPanel)
975            ) {
976                return self.coord.widget_rect(&p);
977            }
978            cur = self.coord.widget_parent(&p);
979        }
980        None
981    }
982
983    /// Select-all of every selectable whose rect is inside `rect`.
984    fn select_in_rect(&mut self, win: WindowId, rect: &Rect, fx: &mut InputEffects) -> bool {
985        let mut changed = false;
986        for w in self.selectable_ids_by_row() {
987            if let Some(r) = self.coord.widget_rect(&w) {
988                let inside = r.x >= rect.x
989                    && r.y >= rect.y
990                    && r.x + r.width <= rect.x + rect.width
991                    && r.y + r.height <= rect.y + rect.height;
992                if inside {
993                    if let Some(st) = self.selectables.get(&w) {
994                        let sel = TextSelection::all(&st.text);
995                        changed |= self.set_selection(win, &w, sel, fx);
996                    }
997                }
998            }
999        }
1000        changed
1001    }
1002
1003    /// Select-all of every selectable in the window.
1004    fn select_everything(&mut self, win: WindowId, fx: &mut InputEffects) -> bool {
1005        let mut changed = false;
1006        for w in self.selectable_ids_by_row() {
1007            if let Some(st) = self.selectables.get(&w) {
1008                let sel = TextSelection::all(&st.text);
1009                changed |= self.set_selection(win, &w, sel, fx);
1010            }
1011        }
1012        changed
1013    }
1014
1015    /// A press landed on `target` (`None` = empty space): anything selected
1016    /// that is not the target clears; a selectable target starts a press.
1017    fn press_down(
1018        &mut self,
1019        win: WindowId,
1020        target: Option<&WidgetId>,
1021        x: f64,
1022        y: f64,
1023        fx: &mut InputEffects,
1024    ) -> bool {
1025        let mut changed = false;
1026        if !target.is_some_and(|t| self.sel_get(t).is_some()) {
1027            changed |= self.clear_selections(win, fx);
1028        }
1029        self.press_sel = None;
1030        if let Some(t) = target {
1031            if let Some(st) = self.selectables.get(t) {
1032                let anchor = char_at_point(&st.lines, x, y);
1033                self.press_sel = Some(PressSel {
1034                    widget: t.clone(),
1035                    anchor,
1036                });
1037            }
1038        }
1039        changed
1040    }
1041
1042    /// Selection bookkeeping at EndFrame: live drag extension, click
1043    /// selection, press-session cleanup, stale-widget pruning.
1044    fn selection_frame(&mut self, win: WindowId, fx: &mut InputEffects) -> bool {
1045        let mut changed = false;
1046
1047        // Live drag: the press is armed past the threshold (or its release
1048        // just ended the drag) — extend the selection to the current
1049        // pointer char every frame, so the highlight is live.
1050        if let Some(p) = self.press_sel.clone() {
1051            if self.cook.drag_armed || self.drag_ended {
1052                if let (Some(st), Some((x, y))) =
1053                    (self.selectables.get(&p.widget), self.pointer.pos)
1054                {
1055                    let sel = TextSelection::new(p.anchor, char_at_point(&st.lines, x, y));
1056                    changed |= self.set_selection(win, &p.widget, sel, fx);
1057                }
1058            }
1059        }
1060
1061        // Click selection happens at the release (Deliver Up), not here —
1062        // a label has no `click` sense, so the coordinator never reports
1063        // its clicks.
1064
1065        // The press session ends when the button is up.
1066        if self.pointer.button_down.is_none() {
1067            self.press_sel = None;
1068            self.drag_ended = false;
1069        }
1070
1071        // Prune: only widgets reported this frame stay selectable; their
1072        // selections drop with them.
1073        let fresh = std::mem::take(&mut self.reported);
1074        let gone: Vec<WidgetId> = self
1075            .selections
1076            .iter()
1077            .map(|(w, _)| w.clone())
1078            .filter(|w| !fresh.contains_key(w))
1079            .collect();
1080        if !gone.is_empty() {
1081            for w in &gone {
1082                fx.push(InputEffect::InvalidateField {
1083                    win,
1084                    rect: self.coord.widget_rect(w),
1085                });
1086                self.sel_remove(w);
1087            }
1088            if let Some((w, _)) = &self.escalation {
1089                if gone.contains(w) {
1090                    self.escalation = None;
1091                }
1092            }
1093            changed = true;
1094        }
1095        self.selectables = fresh.0;
1096        self.sel_alias = fresh.1;
1097
1098        changed
1099    }
1100
1101    /// Ctrl+A with no focused text field: select all, escalating widget →
1102    /// panel → window across repeated presses. `Some(changed)` = consumed;
1103    /// `None` = no selectable context (the key routes on).
1104    fn ctrl_a(&mut self, win: WindowId, fx: &mut InputEffects) -> Option<bool> {
1105        if let Some((w, level)) = self.escalation.clone() {
1106            let next = match level {
1107                EscLevel::Widget => match self.nearest_panel_rect(&w) {
1108                    Some(rect) => {
1109                        self.select_in_rect(win, &rect, fx);
1110                        EscLevel::Panel
1111                    }
1112                    None => {
1113                        self.select_everything(win, fx);
1114                        EscLevel::Window
1115                    }
1116                },
1117                EscLevel::Panel => {
1118                    self.select_everything(win, fx);
1119                    EscLevel::Window
1120                }
1121                EscLevel::Window => return Some(false),
1122            };
1123            self.escalation = Some((w, next));
1124            return Some(true);
1125        }
1126        // First press: the hovered selectable, else the single selection.
1127        let start = self
1128            .hover
1129            .clone()
1130            .filter(|h| self.selectables.contains_key(h))
1131            .or_else(|| (self.selections.len() == 1).then(|| self.selections[0].0.clone()));
1132        let w = start?;
1133        let st = self.selectables.get(&w)?;
1134        let sel = TextSelection::all(&st.text);
1135        let changed = self.set_selection(win, &w, sel, fx);
1136        self.escalation = Some((w, EscLevel::Widget));
1137        Some(changed)
1138    }
1139
1140    // -- frame ----------------------------------------------------------------
1141
1142    fn begin_frame(&mut self, now: Seconds) -> bool {
1143        let mut state = InputState::new();
1144        state.pointer.pos = self.pointer.pos;
1145        state.pointer.prev_pos = self.pointer.prev_pos;
1146        state.pointer.button_down = self.pointer.button_down;
1147        state.pointer.clicked = self.pointer.clicked.take();
1148        state.modifiers = self.pointer.mods;
1149        state.scroll_delta = std::mem::take(&mut self.pointer.scroll);
1150        self.pointer.scroll_precise = false;
1151        self.pointer.context = None;
1152        state.time = now.get();
1153        self.pointer.prev_pos = self.pointer.pos;
1154        self.coord.begin_frame(state);
1155        let had_clicks = !self.clicked.is_empty();
1156        self.clicked.clear();
1157        had_clicks
1158    }
1159
1160    fn end_frame(&mut self, win: WindowId, fx: &mut InputEffects) -> bool {
1161        let mut hover = None;
1162        let mut clicked = SmallVec::new();
1163        for (id, r) in self.coord.end_frame() {
1164            if r.hovered {
1165                hover = Some(id.clone());
1166            }
1167            if r.clicked {
1168                let count = if r.triple_clicked {
1169                    3
1170                } else if r.double_clicked {
1171                    2
1172                } else {
1173                    1
1174                };
1175                clicked.push((id, count));
1176            }
1177        }
1178        for w in self.key_clicks.drain(..) {
1179            if !clicked.iter().any(|(c, _)| *c == w) {
1180                clicked.push((w, 1));
1181            }
1182        }
1183        let mut changed = hover != self.hover || clicked != self.clicked;
1184        self.hover = hover;
1185        self.clicked = clicked.clone();
1186        // A click on a focusable widget inside the active scope focuses
1187        // it (design §4.3, routing step 6); text fields reconcile below.
1188        let clicked_focus = clicked
1189            .iter()
1190            .map(|(id, _)| id.clone())
1191            .find(|id| self.allowed(id) && self.coord.widget_sense(id).is_some_and(|s| s.focus));
1192        if let Some(id) = clicked_focus {
1193            if self.focused_id() != Some(&id) {
1194                self.focus_raw(id);
1195                changed = true;
1196            }
1197        }
1198        changed |= self.selection_frame(win, fx);
1199        changed |= self.reconcile_focus();
1200        changed
1201    }
1202
1203    // -- text -----------------------------------------------------------------
1204
1205    /// The focused text field, when the store and the record agree.
1206    fn text_focus(&self) -> Option<WidgetId> {
1207        let f = self.focus.as_ref().filter(|f| f.field)?;
1208        self.coord
1209            .text_fields()
1210            .is_focused(&f.id)
1211            .then(|| f.id.clone())
1212    }
1213
1214    fn key(
1215        &mut self,
1216        win: WindowId,
1217        input: KeyInput,
1218        next_ticket: &mut u64,
1219        fx: &mut InputEffects,
1220    ) -> bool {
1221        let m = input.mods;
1222        if input.code == KeyCode::Space && input.state == KeyState::Up {
1223            if let Some(w) = self.space_armed.take() {
1224                if self.focused_id() == Some(&w) {
1225                    self.key_clicks.push(w);
1226                    return true;
1227                }
1228            }
1229        }
1230        if input.state == KeyState::Up {
1231            fx.push(InputEffect::KeyPassed { win, key: input });
1232            return false;
1233        }
1234        if input.code != KeyCode::Unknown {
1235            self.focus_visible = true;
1236        }
1237        // Enter / Space on a focused control (not a text field) activate it.
1238        if matches!(input.code, KeyCode::Enter | KeyCode::Space) && !(m.ctrl || m.alt || m.meta) {
1239            if let Some(f) = self.focus.as_ref().filter(|f| !f.field).map(|f| f.id.clone()) {
1240                if self.coord.widget_sense(&f).is_some_and(|s| s.click) {
1241                    let (enter, space) = activation(self.coord.widget_kind(&f));
1242                    if input.code == KeyCode::Enter && enter {
1243                        self.key_clicks.push(f);
1244                        return true;
1245                    }
1246                    if input.code == KeyCode::Space && space {
1247                        self.space_armed = Some(f);
1248                        return false;
1249                    }
1250                }
1251            }
1252        }
1253        if input.code == KeyCode::Tab && !(m.ctrl || m.alt || m.meta) {
1254            return match self.cycle(!m.shift) {
1255                Some(changed) => changed,
1256                None => {
1257                    fx.push(InputEffect::KeyPassed { win, key: input });
1258                    false
1259                }
1260            };
1261        }
1262        let field = self.text_focus();
1263        let edit = editing_chord(&input);
1264        let (field, edit) = match (field, edit) {
1265            (Some(f), Some(e)) => (f, e),
1266            // No focused text field: a plain-text selection takes the copy
1267            // / select-all chords; with nothing selected they route on.
1268            (None, Some(Edit::Copy)) => {
1269                if let Some(text) = self.selected_text_concat() {
1270                    fx.push(InputEffect::CopyText { win, text });
1271                } else {
1272                    // The focused custom widget's offer answers the copy;
1273                    // the key still reaches it.
1274                    if let Some(text) = self.offer.clone() {
1275                        fx.push(InputEffect::CopyText { win, text });
1276                    }
1277                    fx.push(InputEffect::KeyPassed { win, key: input });
1278                }
1279                return false;
1280            }
1281            (None, Some(Edit::Cut)) => {
1282                if let Some(text) = self.offer.clone() {
1283                    fx.push(InputEffect::CopyText { win, text });
1284                }
1285                fx.push(InputEffect::KeyPassed { win, key: input });
1286                return false;
1287            }
1288            (None, Some(Edit::Paste)) => {
1289                // No text field: the clipboard text goes to the app
1290                // (`UnhandledInput::Paste`). A web host answers with the DOM
1291                // paste event instead of a read.
1292                let ticket = Ticket(INPUT_TICKET_BASE.saturating_add(*next_ticket));
1293                *next_ticket = next_ticket.saturating_add(1);
1294                self.pending_paste = Some((ticket, None));
1295                fx.push(InputEffect::NeedPaste { win, ticket });
1296                return false;
1297            }
1298            (None, Some(Edit::Key(KeyPress::SelectAll)))
1299                if self.focus.as_ref().is_some_and(|f| !f.field && self.coord.widget_kind(&f.id).is_some_and(|k| k.is_blackbox())) =>
1300            {
1301                // A focused blackbox (terminal, remote view) owns its Ctrl+A.
1302                fx.push(InputEffect::KeyPassed { win, key: input });
1303                return false;
1304            }
1305            (None, Some(Edit::Key(KeyPress::SelectAll))) => {
1306                // `None` = no selectable context: the key routes on.
1307                return match self.ctrl_a(win, fx) {
1308                    Some(changed) => changed,
1309                    None => {
1310                        fx.push(InputEffect::KeyPassed { win, key: input });
1311                        false
1312                    }
1313                };
1314            }
1315            _ => {
1316                fx.push(InputEffect::KeyPassed { win, key: input });
1317                return false;
1318            }
1319        };
1320        let text_before = self.coord.text_fields().text(&field).to_owned();
1321        let changed_text = |action: &TextAction| matches!(action, TextAction::TextChanged(_));
1322        let mut changed = false;
1323        let multiline = self.coord.text_fields().field_state(&field).is_some_and(|s| s.config.multiline);
1324        let edit = match edit {
1325            Edit::Newline if multiline => Edit::Key(KeyPress::Paste("\n".into())),
1326            Edit::Newline => Edit::Submit,
1327            e => e,
1328        };
1329        match edit {
1330            Edit::Newline => {}
1331            Edit::Key(kp) => changed = changed_text(&self.coord.on_key(kp)),
1332            Edit::Char(c) => changed = changed_text(&self.coord.on_char(c)),
1333            Edit::Text(s) => {
1334                for c in s.chars() {
1335                    changed |= changed_text(&self.coord.on_char(c));
1336                }
1337            }
1338            Edit::Submit => {
1339                if let TextAction::Commit(_) = self.coord.on_char('\r') {
1340                    fx.push(InputEffect::Text(TextIntent::Submitted {
1341                        win,
1342                        field: field.clone(),
1343                    }));
1344                }
1345            }
1346            Edit::Copy => {
1347                // A field with no selection of its own (it kept focus while the user
1348                // selected page text): the page selection is what the user means.
1349                let own = if self.masked(&field) { None } else { self.coord.text_fields().copy_selection().filter(|t| !t.is_empty()) };
1350                if let Some(text) = own.or_else(|| self.selected_text_concat()) {
1351                    fx.push(InputEffect::CopyText { win, text });
1352                }
1353            }
1354            Edit::Cut => {
1355                if !self.masked(&field) {
1356                    if let Some(text) = self.coord.text_fields_mut().cut_selection(&field) {
1357                        fx.push(InputEffect::CopyText { win, text });
1358                    }
1359                }
1360            }
1361            Edit::Paste => {
1362                let ticket = Ticket(INPUT_TICKET_BASE.saturating_add(*next_ticket));
1363                *next_ticket = next_ticket.saturating_add(1);
1364                self.pending_paste = Some((ticket, Some(field.clone())));
1365                fx.push(InputEffect::NeedPaste { win, ticket });
1366            }
1367        }
1368        if changed || self.coord.text_fields().text(&field) != text_before {
1369            fx.push(InputEffect::Text(TextIntent::Changed { win, field }));
1370        }
1371        // Text and caret changes are revisioned by `settle`.
1372        false
1373    }
1374
1375    fn masked(&self, field: &WidgetId) -> bool {
1376        self.coord
1377            .text_fields()
1378            .field_state(field)
1379            .is_some_and(|s| s.config.masked)
1380    }
1381
1382    fn ime(&mut self, win: WindowId, input: ImeInput, fx: &mut InputEffects) {
1383        let Some(field) = self.text_focus() else {
1384            return;
1385        };
1386        match input {
1387            ImeInput::Enabled => {}
1388            ImeInput::Preedit { text, cursor } => {
1389                let chars = |b: usize| text.get(..b).map(|s| s.chars().count());
1390                let at = cursor
1391                    .and_then(|(b, _)| chars(b))
1392                    .unwrap_or_else(|| text.chars().count());
1393                self.coord.text_fields_mut().preedit_set(&field, text, at);
1394            }
1395            ImeInput::Commit(text) => {
1396                let action = self.coord.text_fields_mut().ime_commit(&field, text);
1397                if let TextAction::TextChanged(_) = action {
1398                    fx.push(InputEffect::Text(TextIntent::Changed { win, field }));
1399                }
1400            }
1401            ImeInput::Disabled => {
1402                self.coord
1403                    .text_fields_mut()
1404                    .preedit_set(&field, String::new(), 0);
1405            }
1406        }
1407    }
1408
1409    fn clipboard(&mut self, win: WindowId, result: ClipboardResult, fx: &mut InputEffects) {
1410        let Some((ticket, field)) = self.pending_paste.clone() else {
1411            return;
1412        };
1413        if ticket != result.ticket {
1414            return;
1415        }
1416        self.pending_paste = None;
1417        let Some(text) = result.text.filter(|t| !t.is_empty()) else {
1418            return;
1419        };
1420        let Some(field) = field else {
1421            fx.push(InputEffect::Pasted { win, text });
1422            return;
1423        };
1424        let Some(focused) = self.text_focus() else {
1425            return;
1426        };
1427        if focused != field {
1428            return;
1429        }
1430        if let TextAction::TextChanged(_) = self.coord.on_key(KeyPress::Paste(text)) {
1431            fx.push(InputEffect::Text(TextIntent::Changed { win, field }));
1432        }
1433    }
1434
1435    /// The platform paste gesture's text: into the focused text field,
1436    /// else to the app. Settles an engine read still waiting for it (the
1437    /// web answers Ctrl/Cmd+V this way), so the text lands once.
1438    fn paste(&mut self, win: WindowId, text: String, fx: &mut InputEffects) {
1439        self.pending_paste = None;
1440        if text.is_empty() {
1441            return;
1442        }
1443        match self.text_focus() {
1444            Some(field) => {
1445                if let TextAction::TextChanged(_) = self.coord.on_key(KeyPress::Paste(text)) {
1446                    fx.push(InputEffect::Text(TextIntent::Changed { win, field }));
1447                }
1448            }
1449            None => fx.push(InputEffect::Pasted { win, text }),
1450        }
1451    }
1452
1453    // -- caret ----------------------------------------------------------------
1454
1455    fn caret_key(&self) -> Option<CaretKey> {
1456        let store = self.coord.text_fields();
1457        let field = store.focused()?;
1458        let s = store.field_state(field)?;
1459        Some(CaretKey {
1460            field: field.clone(),
1461            engaged: s.engaged,
1462            text: s.text.clone(),
1463            cursor: s.cursor,
1464            selection: s.selection_start,
1465            preedit: s.preedit.clone(),
1466            preedit_cursor: s.preedit_cursor,
1467        })
1468    }
1469
1470    fn field_rect(&self, field: &WidgetId) -> Option<Rect> {
1471        let (x, y, w, h) = self.coord.text_fields().field_state(field)?.last_rect?;
1472        Some(Rect::new(x, y, w, h))
1473    }
1474
1475    /// The caret's rect: the char boundary at the cursor, full field height.
1476    fn caret_rect(&self, field: &WidgetId) -> Option<Rect> {
1477        let s = self.coord.text_fields().field_state(field)?;
1478        let (x, y, _, h) = s.last_rect?;
1479        let cx = s.last_char_positions.get(s.cursor).copied().unwrap_or(x);
1480        Some(Rect::new(cx, y, 1.0, h))
1481    }
1482
1483    /// Re-derive caret blink, repaint, IME area and IME-allowed state after
1484    /// any op. Returns whether observable state changed.
1485    fn settle(&mut self, win: WindowId, now: Seconds, fx: &mut InputEffects) -> bool {
1486        let now_ms = millis(now);
1487        let key = self.caret_key();
1488        let key_changed = key != self.caret;
1489        if key_changed {
1490            if let Some(old) = &self.caret {
1491                if key.as_ref().map(|k| &k.field) != Some(&old.field) {
1492                    fx.push(InputEffect::InvalidateField {
1493                        win,
1494                        rect: self.field_rect(&old.field),
1495                    });
1496                }
1497            }
1498            self.caret = key;
1499            self.blink_anchor_ms = now_ms;
1500        }
1501        self.coord
1502            .text_fields_mut()
1503            .set_blink_time(self.blink_anchor_ms);
1504        let active = self.os_focused && self.caret.as_ref().is_some_and(|k| k.engaged);
1505        let visible = active && self.coord.text_fields().cursor_visible(now_ms);
1506        let visible_changed = visible != self.caret_visible;
1507        self.caret_visible = visible;
1508        if key_changed || visible_changed {
1509            if let Some(k) = &self.caret {
1510                fx.push(InputEffect::InvalidateField {
1511                    win,
1512                    rect: self.field_rect(&k.field),
1513                });
1514            }
1515        }
1516        let at = active.then(|| next_blink_edge(self.blink_anchor_ms, now_ms));
1517        if at != self.armed {
1518            self.armed = at;
1519            fx.push(InputEffect::CaretDeadline { win, at });
1520        }
1521        let field = self.caret.as_ref().map(|k| k.field.clone());
1522        let allowed = field.is_some();
1523        if allowed != self.ime_allowed {
1524            self.ime_allowed = allowed;
1525            fx.push(InputEffect::ImeAllowed { win, allowed });
1526        }
1527        let area = field.and_then(|f| self.caret_rect(&f));
1528        if area != self.ime_area {
1529            self.ime_area = area;
1530            if let Some(rect) = area {
1531                fx.push(InputEffect::ImeArea { win, rect });
1532            }
1533        }
1534        key_changed || visible_changed
1535    }
1536}
1537
1538/// Host clock in whole milliseconds (the store's blink unit); negative and
1539/// NaN instants count as 0.
1540fn millis(t: Seconds) -> u64 {
1541    // `as` saturates: NaN -> 0, beyond u64::MAX -> u64::MAX.
1542    (t.get() * 1000.0).round().max(0.0) as u64
1543}
1544
1545/// The first blink edge strictly after `now_ms` for a phase anchored at
1546/// `anchor_ms`.
1547fn next_blink_edge(anchor_ms: u64, now_ms: u64) -> Seconds {
1548    let phases = now_ms.saturating_sub(anchor_ms) / CARET_BLINK_MS + 1;
1549    let edge = anchor_ms.saturating_add(phases.saturating_mul(CARET_BLINK_MS));
1550    Seconds(edge as f64 / 1000.0)
1551}
1552
1553/// What a key does to a focused text field.
1554#[derive(Clone, Debug, PartialEq, Eq)]
1555enum Edit {
1556    Key(KeyPress),
1557    Char(char),
1558    Text(String),
1559    Submit,
1560    /// Shift+Enter: a newline in a multiline field, else a submit.
1561    Newline,
1562    Copy,
1563    Cut,
1564    Paste,
1565}
1566
1567/// The editing chord a key press is for a focused text field, or `None`
1568/// when the field does not take it (it routes on to overlays and keymap).
1569fn editing_chord(input: &KeyInput) -> Option<Edit> {
1570    let m = input.mods;
1571    let cmd = m.ctrl || m.meta;
1572    let edit = match input.code {
1573        KeyCode::A if cmd => Edit::Key(KeyPress::SelectAll),
1574        KeyCode::Z if cmd && m.shift => Edit::Key(KeyPress::Redo),
1575        KeyCode::Z if cmd => Edit::Key(KeyPress::Undo),
1576        KeyCode::Y if m.ctrl && !m.alt => Edit::Key(KeyPress::Redo),
1577        KeyCode::C if cmd => Edit::Copy,
1578        KeyCode::X if cmd => Edit::Cut,
1579        KeyCode::V if cmd => Edit::Paste,
1580        KeyCode::ArrowLeft if cmd => Edit::Key(KeyPress::WordLeft),
1581        KeyCode::ArrowRight if cmd => Edit::Key(KeyPress::WordRight),
1582        KeyCode::Backspace if cmd => Edit::Key(KeyPress::DeleteWordBack),
1583        KeyCode::Delete if cmd => Edit::Key(KeyPress::DeleteWordForward),
1584        KeyCode::ArrowLeft if m.shift => Edit::Key(KeyPress::ShiftLeft),
1585        KeyCode::ArrowRight if m.shift => Edit::Key(KeyPress::ShiftRight),
1586        KeyCode::Home if m.shift => Edit::Key(KeyPress::ShiftHome),
1587        KeyCode::End if m.shift => Edit::Key(KeyPress::ShiftEnd),
1588        KeyCode::ArrowLeft => Edit::Key(KeyPress::ArrowLeft),
1589        KeyCode::ArrowRight => Edit::Key(KeyPress::ArrowRight),
1590        KeyCode::Home => Edit::Key(KeyPress::Home),
1591        KeyCode::End => Edit::Key(KeyPress::End),
1592        KeyCode::Backspace => Edit::Char('\x08'),
1593        KeyCode::Delete => Edit::Key(KeyPress::Delete),
1594        KeyCode::Enter if m.shift => Edit::Newline,
1595        KeyCode::Enter => Edit::Submit,
1596        // Other Ctrl / Cmd chords belong to the keymap; Ctrl+Alt is AltGr
1597        // on some layouts and does produce text.
1598        _ if cmd && !(m.ctrl && m.alt) => return None,
1599        _ => {
1600            let text: String = input
1601                .text
1602                .as_deref()?
1603                .chars()
1604                .filter(|c| !c.is_control())
1605                .collect();
1606            if text.is_empty() {
1607                return None;
1608            }
1609            match text.chars().count() {
1610                1 => Edit::Char(text.chars().next()?),
1611                _ => Edit::Text(text),
1612            }
1613        }
1614    };
1615    Some(edit)
1616}
1617
1618// ---------------------------------------------------------------------------
1619// InputEngine
1620// ---------------------------------------------------------------------------
1621
1622/// The InputEngine: see the module docs.
1623#[derive(Default)]
1624pub struct InputEngine {
1625    windows: VecMap<WindowId, PerWindowInput>,
1626    next_scope: u64,
1627    next_ticket: u64,
1628    rev: Revision,
1629}
1630
1631impl fmt::Debug for InputEngine {
1632    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1633        f.debug_struct("InputEngine")
1634            .field("windows", &self.windows.keys().collect::<Vec<_>>())
1635            .field("rev", &self.rev)
1636            .finish()
1637    }
1638}
1639
1640impl InputEngine {
1641    /// An engine with no windows.
1642    pub fn new() -> Self {
1643        Self::default()
1644    }
1645
1646    /// The only mutation door. Bumps the revision iff observable state
1647    /// changed (see the module docs).
1648    pub fn apply(&mut self, op: InputOp) -> InputEffects {
1649        let mut fx = InputEffects::new();
1650        let Self {
1651            windows,
1652            next_scope,
1653            next_ticket,
1654            rev,
1655        } = self;
1656        let changed = match op {
1657            InputOp::Open(win) => match windows.entry(win) {
1658                crate::types::vecmap::Entry::Occupied(_) => false,
1659                crate::types::vecmap::Entry::Vacant(slot) => {
1660                    slot.insert(PerWindowInput::new());
1661                    true
1662                }
1663            },
1664            InputOp::Close(win) => windows.remove(&win).is_some(),
1665            InputOp::WindowFocus { win, focused, now } => match windows.get_mut(&win) {
1666                Some(w) => {
1667                    w.os_focused = focused;
1668                    w.settle(win, now, &mut fx)
1669                }
1670                None => false,
1671            },
1672            InputOp::Pointer { win, now, input } => match windows.get_mut(&win) {
1673                Some(w) => {
1674                    let (changed, cooked) = w.cook(win, now, input);
1675                    fx.push(InputEffect::Pointer(cooked));
1676                    changed
1677                }
1678                None => false,
1679            },
1680            InputOp::Deliver { win, input } => match windows.get_mut(&win) {
1681                Some(w) => {
1682                    let (changed, target) = w.deliver(win, input, &mut fx);
1683                    fx.push(InputEffect::Content { win, target, changed });
1684                    changed
1685                }
1686                None => false,
1687            },
1688            InputOp::Wheel { win, input } => {
1689                if let Some(w) = windows.get_mut(&win) {
1690                    let target = w.wheel(input);
1691                    let changed = target.is_some();
1692                    fx.push(InputEffect::Content { win, target, changed });
1693                }
1694                false
1695            }
1696            InputOp::Key { win, now, input } => match windows.get_mut(&win) {
1697                Some(w) => {
1698                    let changed = w.key(win, input, next_ticket, &mut fx);
1699                    w.settle(win, now, &mut fx) | changed
1700                }
1701                None => false,
1702            },
1703            InputOp::Ime { win, now, input } => match windows.get_mut(&win) {
1704                Some(w) => {
1705                    w.ime(win, input, &mut fx);
1706                    w.settle(win, now, &mut fx)
1707                }
1708                None => false,
1709            },
1710            InputOp::Paste { win, now, text } => match windows.get_mut(&win) {
1711                Some(w) => {
1712                    w.paste(win, text, &mut fx);
1713                    w.settle(win, now, &mut fx)
1714                }
1715                None => false,
1716            },
1717            InputOp::Offer { win, text } => {
1718                if let Some(w) = windows.get_mut(&win) {
1719                    w.offer = text;
1720                }
1721                false
1722            }
1723            InputOp::Clipboard { win, now, result } => match windows.get_mut(&win) {
1724                Some(w) => {
1725                    w.clipboard(win, result, &mut fx);
1726                    w.settle(win, now, &mut fx)
1727                }
1728                None => false,
1729            },
1730            InputOp::Focus { win, now, op } => match windows.get_mut(&win) {
1731                Some(w) => {
1732                    let changed = w.focus_op(win, op, next_scope, &mut fx);
1733                    w.settle(win, now, &mut fx) | changed
1734                }
1735                None => false,
1736            },
1737            InputOp::SetCapture { win, capture } => windows
1738                .get_mut(&win)
1739                .is_some_and(|w| w.set_capture(capture)),
1740            InputOp::BeginFrame { win, now } => {
1741                windows.get_mut(&win).is_some_and(|w| w.begin_frame(now))
1742            }
1743            InputOp::EndFrame { win, now } => match windows.get_mut(&win) {
1744                Some(w) => {
1745                    let changed = w.end_frame(win, &mut fx);
1746                    w.settle(win, now, &mut fx) | changed
1747                }
1748                None => false,
1749            },
1750        };
1751        if changed {
1752            rev.bump();
1753        }
1754        fx
1755    }
1756
1757    /// Caret blink edges: every window whose armed edge is due at `now`
1758    /// flips its caret, asks for a repaint of that field and re-arms the
1759    /// next edge. The kernel calls it when `TimerOwner::CaretBlink` fires
1760    /// (calling it at any other time is harmless).
1761    pub fn tick(&mut self, now: Seconds) -> InputEffects {
1762        let mut fx = InputEffects::new();
1763        let mut changed = false;
1764        for (win, w) in &mut self.windows {
1765            if w.armed.is_some_and(|at| at.get() <= now.get()) {
1766                changed |= w.settle(*win, now, &mut fx);
1767            }
1768        }
1769        if changed {
1770            self.rev.bump();
1771        }
1772        fx
1773    }
1774
1775    /// The compose-phase door for widget registration (`register*`,
1776    /// `register_text_field`, `update_field`, `mark_seen`, `unregister`,
1777    /// layers). Not revisioned: what registration changes is evaluated by
1778    /// the following [`InputOp::EndFrame`]. Lib brief L6 narrows what this
1779    /// reference can reach (see the module docs).
1780    // Read doors for the native/web host briefs (F8+) - unused in-crate until then.
1781    #[allow(dead_code)]
1782    pub fn registrar(&mut self, win: WindowId) -> Option<&mut InputCoordinator> {
1783        self.windows.get_mut(&win).map(|w| &mut w.coord)
1784    }
1785
1786    /// The compose-phase door for the per-widget typed state store (the
1787    /// `Widgets` face of the app hook contexts). Not revisioned: the store
1788    /// holds no on-screen truth of its own.
1789    // Read doors for the native/web host briefs (F8+) - unused in-crate until then.
1790    #[allow(dead_code)]
1791    pub fn states_mut(&mut self, win: WindowId) -> Option<&mut uzor::app_context::StateRegistry> {
1792        self.windows.get_mut(&win).map(|w| &mut w.states)
1793    }
1794
1795    /// The compose-phase `Widgets` pair, borrow-split: a hook holds both
1796    /// halves at once, so the two single doors cannot produce them
1797    /// together. Same revision rules as the single doors.
1798    pub fn compose_parts(
1799        &mut self,
1800        win: WindowId,
1801    ) -> Option<(&mut InputCoordinator, &mut uzor::app_context::StateRegistry, &mut Selectables)> {
1802        self.windows
1803            .get_mut(&win)
1804            .map(|w| (&mut w.coord, &mut w.states, &mut w.reported))
1805    }
1806
1807    /// Compose-phase door (T2): report one selectable plain-text widget's
1808    /// content and line geometry for this frame — the input the selection
1809    /// owner resolves presses / drags against, mirroring
1810    /// `TextFieldStore::update_field`. A widget not reported in a frame
1811    /// stops being selectable and loses its selection. Not revisioned: the
1812    /// change is evaluated by the following [`InputOp::EndFrame`].
1813    // Read doors for the native/web host briefs (F8+) - unused in-crate until then.
1814    #[allow(dead_code)]
1815    pub fn update_selectable(
1816        &mut self,
1817        win: WindowId,
1818        widget: WidgetId,
1819        text: impl Into<String>,
1820        lines: Vec<SelectionLine>,
1821    ) {
1822        if let Some(w) = self.windows.get_mut(&win) {
1823            w.reported.report(widget, text, lines);
1824        }
1825    }
1826
1827    /// Route presses on the hit region `member` to the selectable `owner` for
1828    /// this frame (see `Selectables::alias`).
1829    #[allow(dead_code)]
1830    pub fn alias_selectable(&mut self, win: WindowId, member: WidgetId, owner: WidgetId) {
1831        if let Some(w) = self.windows.get_mut(&win) {
1832            w.reported.alias(member, owner);
1833        }
1834    }
1835
1836    /// Bumped on every observable state change.
1837    pub fn revision(&self) -> Revision {
1838        self.rev
1839    }
1840
1841    /// Read-only projection.
1842    pub fn view(&self) -> InputEngineView<'_> {
1843        InputEngineView { e: self }
1844    }
1845}
1846
1847/// Read-only projection of the [`InputEngine`].
1848#[derive(Clone, Copy, Debug)]
1849pub struct InputEngineView<'a> {
1850    e: &'a InputEngine,
1851}
1852
1853// Read doors for the native/web host briefs (F8+) - unused in-crate until then.
1854#[allow(dead_code)]
1855impl<'a> InputEngineView<'a> {
1856    fn w(&self, win: WindowId) -> Option<&'a PerWindowInput> {
1857        self.e.windows.get(&win)
1858    }
1859
1860    /// Tracked windows, ascending.
1861    pub fn ids(&self) -> impl Iterator<Item = WindowId> + 'a {
1862        self.e.windows.keys().copied()
1863    }
1864
1865    /// The published input state of one window.
1866    pub fn window(&self, win: WindowId) -> Option<InputView> {
1867        self.w(win).map(|w| InputView {
1868            hovered: w.hover.clone(),
1869            pressed: w.pressed.clone(),
1870            focused: w.focused_id().cloned(),
1871            focus_visible: w.focus_visible,
1872            captured: w.capture.is_some(),
1873            scope_depth: w.scopes.len(),
1874        })
1875    }
1876
1877    /// The widget with keyboard focus.
1878    pub fn focused(&self, win: WindowId) -> Option<&'a WidgetId> {
1879        self.w(win)?.focused_id()
1880    }
1881
1882    /// The owner of the active (innermost) focus scope.
1883    pub fn active_scope(&self, win: WindowId) -> Option<&'a ScopeOwner> {
1884        self.w(win)?.scopes.last().map(|s| &s.owner)
1885    }
1886
1887    /// The pointer capture.
1888    pub fn capture(&self, win: WindowId) -> Option<&'a Capture> {
1889        self.w(win)?.capture.as_ref()
1890    }
1891
1892    /// The event-level cook state (click count, drag arm).
1893    pub fn cook(&self, win: WindowId) -> Option<&'a CookState> {
1894        self.w(win).map(|w| &w.cook)
1895    }
1896
1897    /// Widgets clicked in the last evaluated frame, with their click count
1898    /// (1 single, 2 double, 3 triple).
1899    pub fn clicked(&self, win: WindowId) -> &'a [(WidgetId, u8)] {
1900        self.w(win).map_or(&[], |w| w.clicked.as_slice())
1901    }
1902
1903    /// The caret of the focused field is in its visible phase (and blinking
1904    /// is active).
1905    pub fn caret_visible(&self, win: WindowId) -> bool {
1906        self.w(win).is_some_and(|w| w.caret_visible)
1907    }
1908
1909    /// The armed caret blink edge.
1910    pub fn caret_deadline(&self, win: WindowId) -> Option<Seconds> {
1911        self.w(win)?.armed
1912    }
1913
1914    /// The window's text fields (text, cursor, selection, preedit).
1915    pub fn text_fields(&self, win: WindowId) -> Option<&'a TextFieldStore> {
1916        self.w(win).map(|w| w.coord.text_fields())
1917    }
1918
1919    /// The window's plain-text selections (widget → selection), the T2
1920    /// per-window owner state. The app reads this at compose time to draw
1921    /// highlights through the lib's `draw_text_with_selection`.
1922    pub fn selections(&self, win: WindowId) -> Option<&'a [(WidgetId, TextSelection)]> {
1923        self.w(win).map(|w| w.selections.as_slice())
1924    }
1925
1926    /// The window's coordinator, read-only (hit tests, widget state).
1927    pub fn coordinator(&self, win: WindowId) -> Option<&'a InputCoordinator> {
1928        self.w(win).map(|w| &w.coord)
1929    }
1930
1931    /// Scroll accumulated since the last `BeginFrame`, in lines. The
1932    /// compose phase reads it into the hook view before `BeginFrame`
1933    /// moves it into the coordinator's frame input.
1934    pub fn pending_scroll(&self, win: WindowId) -> (f64, f64) {
1935        self.w(win).map_or((0.0, 0.0), |w| w.pointer.scroll)
1936    }
1937
1938    /// Whether [`Self::pending_scroll`] came from pixel deltas (trackpad,
1939    /// smooth wheel): scroll containers then follow 1:1 and fling on release.
1940    pub fn pending_scroll_precise(&self, win: WindowId) -> bool {
1941        self.w(win).is_some_and(|w| w.pointer.scroll_precise)
1942    }
1943
1944    /// Last pointer position in window coordinates and whether a button is
1945    /// held (embedded surfaces that forward raw pointer events need both).
1946    /// Secondary-button release position since the last `BeginFrame`.
1947    pub fn context_click(&self, win: WindowId) -> Option<(f64, f64)> {
1948        self.w(win).and_then(|w| w.pointer.context)
1949    }
1950
1951    pub fn pointer(&self, win: WindowId) -> (Option<(f64, f64)>, bool) {
1952        self.w(win).map_or((None, false), |w| (w.pointer.pos, w.pointer.button_down.is_some()))
1953    }
1954
1955    /// Where the held press went down (window coords), while a button is held. A drag
1956    /// measures from here, not from the first pointer position a frame saw: the pointer
1957    /// may have moved several pixels between the press and that frame.
1958    pub fn press_origin(&self, win: WindowId) -> Option<(f64, f64)> {
1959        let w = self.w(win)?;
1960        w.pointer.button_down?;
1961        w.cook.press_origin.map(|o| (o.x, o.y))
1962    }
1963}
1964
1965#[cfg(test)]
1966mod tests;