tuile 0.15.0 → 0.16.0

data/sig/tuile.rbs

@@ -454,6 +454,321 @@ module Tuile
     def verify_final!: (Class klass) -> void
   end
 
+  # The mouse: the events, their parser, and the tracking levels
+  # {Screen#run_event_loop} asks the terminal for. Who gets one is
+  # {Mouse::Router}'s story.
+  # 
+  # Four of the five classes are what {.parse} reads off the wire; {DragEvent} is
+  # the router's own, a move while something holds the grab. Each is a
+  # `Data.define` including the {Event} marker — no inheritance, so a `case`
+  # matches either one class or `Mouse::Event` for all of them. Enter and exit
+  # have no class at all: nothing is parsed, they are the difference between two
+  # hovered chains.
+  # 
+  # Coordinates are screen-absolute and 0-based everywhere.
+  module Mouse
+    LEVELS: ::Array[Symbol]
+    MODES: ::Hash[Symbol, Integer]
+    MODIFIER_BITS: Integer
+
+    # Normalizes a `capture_mouse:` argument to a level.
+    # 
+    # _@param_ `capture_mouse` — `false`, `true` (== `:clicks`), or one of {LEVELS}.
+    # 
+    # _@return_ — the level; nil when tracking is off.
+    def self.level: ((bool | Symbol) capture_mouse) -> Symbol?
+
+    # _@param_ `level` — one of {LEVELS}.
+    # 
+    # _@return_ — the escape enabling that level.
+    def self.start_tracking: (Symbol level) -> String
+
+    # _@param_ `level` — one of {LEVELS}.
+    # 
+    # _@return_ — the escape disabling that level.
+    def self.stop_tracking: (Symbol level) -> String
+
+    # Whether `key` is a mouse report. True on the X10 `\e[M` prefix
+    # regardless of length — {.parse} is the place that validates the full
+    # 6-byte shape and raises on malformed input.
+    # 
+    # _@param_ `key` — key read via {Keys.getkey}
+    def self.report?: (String key) -> bool
+
+    # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y) into one of
+    # {DownEvent}, {UpEvent}, {ScrollEvent} or {MoveEvent}. Modifier bits are
+    # ignored.
+    # 
+    # Raises {Tuile::Error} when `key` starts with the mouse prefix but is
+    # not exactly 6 bytes long. Both shorter and longer inputs are bugs in
+    # the upstream key-reader: a shorter prefix means the tail was lost on
+    # the way in, and a longer one means we over-consumed into the next
+    # escape sequence. We refuse to silently truncate either case because
+    # the trailing `\e` of an over-read corrupts the *next* getkey, and the
+    # corruption then surfaces as garbled keystrokes in focused inputs
+    # rather than as a parser failure pointing at the actual cause.
+    # 
+    # _@param_ `key` — key read via {Keys.getkey}
+    # 
+    # _@return_ — `nil` if `key` is not a mouse report, or reports
+    # a wheel button beyond the four directions.
+    def self.parse: (String key) -> Event?
+
+    # _@param_ `low` — the code's two low bits.
+    def self.button: (Integer low) -> Symbol?
+
+    # Included by every mouse event class: a marker for `case`/`is_a?`, plus the
+    # {#point} they share.
+    module Event
+      # _@return_ — the event's position.
+      def point: () -> Point
+    end
+
+    # A button went down.
+    # 
+    # @!attribute [r] button
+    #   @return [Symbol] `:left`, `:middle` or `:right`.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    class DownEvent < Data
+      include Tuile::Mouse::Event
+
+      # _@return_ — the event's position.
+      def point: () -> Point
+
+      # _@return_ — `:left`, `:middle` or `:right`.
+      attr_reader button: Symbol
+
+      # _@return_ — 0-based column.
+      attr_reader x: Integer
+
+      # _@return_ — 0-based row.
+      attr_reader y: Integer
+    end
+
+    # A button came up. **Deliberately no `button`**: an up reaches only the
+    # component that claimed the press, and that grab already knows which button
+    # it holds (`D_mouse_dispatch`).
+    # 
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    class UpEvent < Data
+      include Tuile::Mouse::Event
+
+      # _@return_ — the event's position.
+      def point: () -> Point
+
+      # _@return_ — 0-based column.
+      attr_reader x: Integer
+
+      # _@return_ — 0-based row.
+      attr_reader y: Integer
+    end
+
+    # One wheel notch. A notch is not a button, which is why this is not a
+    # {DownEvent}.
+    # 
+    # @!attribute [r] direction
+    #   @return [Symbol] `:up`, `:down`, `:left` or `:right`.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    class ScrollEvent < Data
+      include Tuile::Mouse::Event
+
+      # _@return_ — the event's position.
+      def point: () -> Point
+
+      # _@return_ — `:up`, `:down`, `:left` or `:right`.
+      attr_reader direction: Symbol
+
+      # _@return_ — 0-based column.
+      attr_reader x: Integer
+
+      # _@return_ — 0-based row.
+      attr_reader y: Integer
+    end
+
+    # The pointer moved and nothing holds the grab.
+    # 
+    # @!attribute [r] button
+    #   @return [Symbol, nil] the button held while moving, or nil.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    class MoveEvent < Data
+      include Tuile::Mouse::Event
+
+      # _@return_ — the event's position.
+      def point: () -> Point
+
+      # _@return_ — the button held while moving, or nil.
+      attr_reader button: Symbol?
+
+      # _@return_ — 0-based column.
+      attr_reader x: Integer
+
+      # _@return_ — 0-based row.
+      attr_reader y: Integer
+    end
+
+    # The pointer moved while a component holds the grab.
+    # 
+    # The one event {Router} *makes* rather than routes, so posting one to
+    # {Screen#handle_mouse} raises: drive a grabbed component with a
+    # {MoveEvent} carrying the held button, or with {FakeScreen#drag}.
+    # 
+    # @!attribute [r] button
+    #   @return [Symbol] the button whose press took the grab.
+    # @!attribute [r] x
+    #   @return [Integer] 0-based column — may lie outside the grabbed
+    #     component's rect, and even outside the screen's last known size.
+    # @!attribute [r] y
+    #   @return [Integer] 0-based row.
+    class DragEvent < Data
+      include Tuile::Mouse::Event
+
+      # _@return_ — the event's position.
+      def point: () -> Point
+
+      # _@return_ — the button whose press took the grab.
+      attr_reader button: Symbol
+
+      # _@return_ — 0-based column — may lie outside the grabbed
+      # component's rect, and even outside the screen's last known size.
+      attr_reader x: Integer
+
+      # _@return_ — 0-based row.
+      attr_reader y: Integer
+    end
+
+    # Delivers {Mouse::Event}s to the component tree. {Screen} owns one and hands
+    # it every event the terminal reports; a component only answers the handlers
+    # it calls, and walks nothing itself.
+    # 
+    #   screen.handle_mouse(Mouse::DownEvent.new(:left, 5, 2))   # what the loop does
+    # 
+    # Every event resolves against one **path**: the topmost popup containing the
+    # point, else the tiled content unless a modal popup is open
+    # ({ScreenPane#mouse_root_at}), then down through the shown children whose
+    # {Component#rect} contains it.
+    # 
+    # - **{DownEvent}** — focuses the innermost {Component#focusable?} on that
+    #   path, then offers {Component#handle_mouse_down?} innermost-first until one
+    #   component answers `true`. That claimant becomes {#grabbed}.
+    # - **{ScrollEvent}**, **{MoveEvent}** — bubble the same way through
+    #   {Component#handle_mouse_scroll?} / {Component#handle_mouse_move?}, and grab
+    #   nothing. A move fires the enter/exit hooks first, and arrives only at
+    #   `:hover`.
+    # - **{DragEvent}**, **{UpEvent}** — skip the path entirely: they go to
+    #   {#grabbed}, wherever the pointer is, and an up ends the grab.
+    # 
+    # The two geometries are deliberately different. Focus follows `rect`, so a
+    # press on the dead tail a widget does not paint still focuses it; the
+    # handlers bubble only along the prefix whose {Component#extent_rect} contains
+    # the point, so that same press activates nothing (`D_extent`).
+    # 
+    # UI-thread-confined.
+    # 
+    # == Implementation details
+    # 
+    # **The grab has three releases and no relinquishing**: the up, the next
+    # down (the up was lost — ssh and tmux do lose them), and any key
+    # ({#release_grab}). None of the last two tells the grabbed component. Hiding
+    # or detaching it does not end the grab either; the router just stops
+    # delivering to it until the release (`D_mouse_dispatch`).
+    # 
+    # **The hovered chain is synced, not toggled**: a move re-resolves it and
+    # diffs, and {#sync_hover} — run by {Screen#repaint} — drops members that
+    # were detached, hidden or reparented since, firing their exits.
+    class Router
+      # _@param_ `screen`
+      def initialize: (Screen screen) -> void
+
+      # _@return_ — the innermost component under the pointer, as of
+      # the last move under `:hover`.
+      def hovered: () -> Component?
+
+      # _@param_ `event`
+      def dispatch: (Mouse::Event event) -> void
+
+      # Ends the grab without telling the grabbed component.
+      def release_grab: () -> void
+
+      # Drops the hovered-chain members that are no longer attached, shown, or
+      # children of the member before them, firing
+      # {Component#handle_mouse_exit} innermost first. Idempotent.
+      def sync_hover: () -> void
+
+      # _@param_ `event`
+      def press: (DownEvent event) -> void
+
+      # _@param_ `event`
+      def release: (UpEvent event) -> void
+
+      # _@param_ `event`
+      def move: (MoveEvent event) -> void
+
+      # A non-modal overlay is never focused into: it sits outside the key scope,
+      # so focus there would make every keystroke go dead (`D_overlay`).
+      # 
+      # _@param_ `root`
+      # 
+      # _@param_ `path`
+      def focus_innermost: (Component? root, ::Array[Component] path) -> void
+
+      # _@param_ `path` — root first.
+      # 
+      # _@param_ `handler` — a routed `handle_mouse_…?`.
+      # 
+      # _@param_ `event`
+      # 
+      # _@return_ — the component that answered true.
+      def bubble: (::Array[Component] path, Symbol handler, Mouse::Event event) -> Component?
+
+      # _@param_ `point`
+      # 
+      # _@return_ — the shown components under `point` whose
+      # extent contains it, root first.
+      def extent_path: (Point point) -> ::Array[Component]
+
+      # _@param_ `root`
+      # 
+      # _@param_ `point`
+      # 
+      # _@return_ — the shown components whose rect contains
+      # `point`, root first. Tiled siblings never overlap, so at most one child
+      # qualifies at each level.
+      def rect_path: (Component? root, Point point) -> ::Array[Component]
+
+      # _@param_ `chain` — the new hovered chain, root first.
+      def rehover: (::Array[Component] chain) -> void
+
+      # _@param_ `component`
+      # 
+      # _@return_ — whether `component` is attached and it and every
+      # ancestor are shown.
+      def reachable?: (Component? component) -> bool
+
+      # The tracking level {Screen#run_event_loop} asked the terminal for, one of
+      # {Mouse::LEVELS}; `:hover` while no loop is running, so a spec may post
+      # anything. An ungrabbed move is dropped below `:hover` — under `:drag` the
+      # terminal reports one only while a button nobody claimed is held, and
+      # enter/exit that fire *sometimes* are worse than none.
+      attr_accessor level: Symbol?
+
+      # _@return_ — the component whose {Component#handle_mouse_down?}
+      # claimed the press currently held.
+      attr_reader grabbed: Component?
+    end
+  end
+
   # A point with `x` and `y` integer coordinates, both 0-based.
   # 
   # @!attribute [r] x
@@ -476,12 +791,12 @@ module Tuile
   # restyles everything via one invalidate-everything pass. Book ch6 is the
   # concept in full (why accents-only, dark/light, live OS flips).
   # 
-  # The rendering helpers — {#active_bg}, {#active_border}, {#input_bg},
-  # {#hint} — wrap a plain string in the token's SGR color (on the channel
-  # appropriate for the token's role) and reset:
+  # The rendering helpers — {#active_bg}, {#active_border}, {#input_bg} — wrap
+  # a plain string in the token's SGR color (on the channel appropriate for the
+  # token's role) and reset:
   # 
-  #   screen.theme.active_bg("[ Ok ]")   # => "\e[48;5;59m[ Ok ]\e[0m"
-  #   screen.theme.hint("quit")          # => "\e[38;5;109mquit\e[0m"
+  #   screen.theme.active_bg("[ Ok ]")       # => "\e[48;5;59m[ Ok ]\e[0m"
+  #   screen.theme.active_border("┌────┐")   # => "\e[32m┌────┐\e[0m"
   # 
   # Content passes through verbatim (so it may carry other escapes). For
   # span-aware styling — a token applied to a {StyledString} without flattening
@@ -513,7 +828,7 @@ module Tuile
   # 
   # For a color slot resolved *live* at paint — currently
   # {Component#bg_color=} — assign a {Ref} instead of reading + rebuilding
-  # the token in {Component#on_theme_changed}; it tracks theme swaps on its
+  # the token in {Component#handle_theme_changed}; it tracks theme swaps on its
   # own. Baked content colors ({Component::Label} text and friends) can't:
   # they live in a frozen {StyledString} and still need the hook.
   # 
@@ -533,12 +848,6 @@ module Tuile
   #   {Component::TextArea} when *not* active — visibly a field, but
   #   distinctly subtler than {#active_bg_color}.
   #   @return [Color]
-  # @!attribute [r] hint_color
-  #   Foreground of subdued *accent* text an app wants noticed — a
-  #   keyboard-shortcut caption, a {Component::PickerWindow} option. An accent,
-  #   not a grey: it pulls the eye, which is why a placeholder uses
-  #   {#placeholder_color} instead. See {#hint}.
-  #   @return [Color]
   # @!attribute [r] placeholder_color
   #   Foreground of the hint a field paints into its own empty well
   #   ({Component::HasPlaceholder}) — the one token tuned to be *barely*
@@ -583,8 +892,6 @@ module Tuile
     # 
     # _@param_ `input_bg_color`
     # 
-    # _@param_ `hint_color`
-    # 
     # _@param_ `placeholder_color`
     # 
     # _@param_ `error_color`
@@ -600,7 +907,6 @@ module Tuile
                       active_bg_color: Color,
                       active_border_color: Color,
                       input_bg_color: Color,
-                      hint_color: Color,
                       placeholder_color: Color,
                       error_color: Color,
                       error_bg_color: Color,
@@ -627,7 +933,14 @@ module Tuile
     def self.ref: (Symbol name) -> Ref
 
     # Renders `text` in the foreground color of the app-specific `token`
-    # — the generic counterpart of {#hint} for {#custom} tokens.
+    # — the generic counterpart of {#active_border} for {#custom} tokens, and
+    # the route for an app's own status-line chrome:
+    # 
+    #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
+    # 
+    # The color is baked into the returned String, so text built this way does
+    # *not* restyle on a {Screen#theme=} — rebuild it from
+    # {Component#handle_theme_changed} instead.
     # 
     # _@param_ `token`
     # 
@@ -669,17 +982,6 @@ module Tuile
     # _@return_ — ANSI-rendered text, ending with an SGR reset.
     def input_bg: (String text) -> String
 
-    # Renders `text` in the {#hint_color} foreground, for status-bar hints,
-    # e.g. `"q #{screen.theme.hint("quit")}"`. The color is baked into the
-    # returned String, so strings built this way do *not* restyle when the
-    # theme changes — rebuild them instead (the framework's own call sites
-    # rebuild on every status-bar refresh).
-    # 
-    # _@param_ `text`
-    # 
-    # _@return_ — ANSI-rendered text, ending with an SGR reset.
-    def hint: (String text) -> String
-
     # The single sanctioned place for verbatim SGR wrapping: `text` is not
     # parsed or validated, so callers may embed non-SGR escapes. Emits the
     # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
@@ -708,12 +1010,6 @@ module Tuile
     # distinctly subtler than {#active_bg_color}.
     attr_reader input_bg_color: Color
 
-    # Foreground of subdued *accent* text an app wants noticed — a
-    # keyboard-shortcut caption, a {Component::PickerWindow} option. An accent,
-    # not a grey: it pulls the eye, which is why a placeholder uses
-    # {#placeholder_color} instead. See {#hint}.
-    attr_reader hint_color: Color
-
     # Foreground of the hint a field paints into its own empty well
     # ({Component::HasPlaceholder}) — the one token tuned to be *barely*
     # visible, since a placeholder the user misses costs nothing.
@@ -750,7 +1046,7 @@ module Tuile
     # A live reference to a theme token, resolved against the current theme at
     # paint time rather than baked to a concrete {Color}. Assign one where a
     # slot is resolved late — currently {Component#bg_color=} — and it follows
-    # light/dark flips with no {Component#on_theme_changed} hook:
+    # light/dark flips with no {Component#handle_theme_changed} hook:
     # 
     #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
     #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
@@ -1973,17 +2269,17 @@ module Tuile
     def add_popup: (Component::Overlay window) -> void
 
     # Runs the event loop on the calling thread, taking over stdin (raw mode,
-    # echo off): keys and mouse events are dispatched via {#handle_key} /
+    # echo off): keys and mouse events are dispatched via {#handle_key?} /
     # {#handle_mouse}, and the loop repaints once per drained tick. Returns
     # when `q` or ESC is pressed unhandled. Restores terminal state on exit.
     # 
     # For the duration this thread owns the UI ({#state} is `:running`);
     # ownership reverts to the creating thread once it returns.
     # 
-    # _@param_ `capture_mouse` — when true (default), enables xterm mouse tracking so clicks and scroll wheel arrive as {MouseEvent}s and feed {Component#handle_mouse}. When false, no tracking escape sequence is written: the terminal keeps its native click handling, which is what you want if the app benefits more from select-to-copy than from click-to-focus. Components' `handle_mouse` is simply never invoked from the loop in that mode (the terminal stops sending the bytes).
+    # _@param_ `capture_mouse` — how much mouse tracking to ask the terminal for — each level unlocking one tier of {Mouse}'s events, and costing what that tier reports:  - `false` — none. The terminal keeps its native click handling, which is   what you want if the app benefits more from select-to-copy. - `true` (default), `:clicks` — presses, releases and the wheel. - `:drag` — plus motion while a button is held, as   {Component#handle_mouse_drag}. - `:hover` — plus motion with no button, as   {Component#handle_mouse_move?} and the enter/exit hooks. ~84 reports a   second (`R_mouse_reporting`), so ask for it only if something uses it.
     # 
     # _@param_ `bracketed_paste` — when true (default), enables DEC private mode 2004 so pasted text arrives whole, as {Component#handle_paste}, instead of as one keystroke per character — which is the only way a pasted line break can be told from a typed Enter. When false, a paste streams in as keys again and a component that gives ENTER a meaning fires it once per pasted line. Turn it off only for a terminal that mishandles the mode.
-    def run_event_loop: (?capture_mouse: bool, ?bracketed_paste: bool) -> void
+    def run_event_loop: (?capture_mouse: (bool | Symbol), ?bracketed_paste: bool) -> void
 
     # Advances focus to the next {Component#tab_stop?} in tree order, wrapping
     # around. Scope is the topmost popup if one is open, otherwise {#content}
@@ -2008,9 +2304,9 @@ module Tuile
     # 
     # - **Printable keys** — they'd hijack typing into a
     #   {Component::TextField}. A scope-wide one-key binding belongs on the
-    #   scope root's own `handle_key`, where a focused field consumes it first
-    #   (see {ScreenPane#handle_key}).
-    # - **TAB / SHIFT_TAB** — {#handle_key} intercepts them for focus
+    #   scope root's own `handle_key?`, where a focused field consumes it first
+    #   (see {ScreenPane#handle_key?}).
+    # - **TAB / SHIFT_TAB** — {#handle_key?} intercepts them for focus
     #   navigation before the registry is consulted, so a binding would never
     #   fire.
     # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
@@ -2063,7 +2359,7 @@ module Tuile
 
     # Tears the screen down and vacates the singleton slot, moving {#state} to
     # the terminal `:closed`. Unmounts the tree first, so every component gets
-    # its {Component#on_detached}. Idempotent.
+    # its {Component#handle_detached}. Idempotent.
     def close: () -> void
 
     def self.close: () -> void
@@ -2111,13 +2407,31 @@ module Tuile
     # but only one focused.
     def cursor_position: () -> Point?
 
+    # Routes one mouse event into the tree ({Mouse::Router}) — what the event
+    # loop does with every report the terminal sends, and how a spec drives the
+    # mouse:
+    # 
+    #   screen.handle_mouse(Mouse::DownEvent.new(:left, 5, 2))
+    # 
+    # _@param_ `event`
+    def handle_mouse: (Mouse::Event event) -> void
+
+    # _@return_ — the innermost component the pointer is over, as
+    # of the last move. Always nil below `capture_mouse: :hover`, and frozen
+    # at its last value while a press is grabbed.
+    def hovered: () -> Component?
+
+    # _@return_ — the component holding the mouse grab — the one
+    # whose {Component#handle_mouse_down?} claimed the press still held.
+    def grabbed: () -> Component?
+
     # Whether `component` is out of the user's reach because it or an ancestor
     # is {Component#visible? hidden}.
     # 
     # Private, not a `Component#shown?`, for the reason `D_empty_ancestor`
     # declined a `Component#paintable?`: it reads as a component-level concept
     # and is really this class's question. A *walk* needs no such predicate —
-    # it prunes at the hidden subtree's root ({Component#on_shown_tree}).
+    # it prunes at the hidden subtree's root ({Component#walk_shown_tree}).
     # 
     # _@param_ `component`
     def hidden?: (Component component) -> bool
@@ -2164,7 +2478,7 @@ module Tuile
     # thread as an {EventQueue::BackgroundColorEvent}.
     # 
     # _@param_ `scheme` — `:dark` or `:light`.
-    def on_color_scheme: (Symbol scheme) -> void
+    def handle_color_scheme: (Symbol scheme) -> void
 
     # The re-probe answered: adopt the color and restyle, since an app's
     # background-derived tints are now a scheme behind. Deliberately keeps
@@ -2173,7 +2487,7 @@ module Tuile
     # would otherwise lose the color it gave us at startup, permanently.
     # 
     # _@param_ `color`
-    def on_background_color: (Color color) -> void
+    def handle_background_color: (Color color) -> void
 
     # Walks the current modal scope in pre-order, collects tab stops, and
     # advances focus by one (wrapping). When the focused component isn't in
@@ -2215,18 +2529,13 @@ module Tuile
     #      default `over_popups: false` fires only when no modal popup is open
     #      (otherwise the modal popup receives the key normally). A non-modal
     #      overlay doesn't suppress global shortcuts.
-    #   3. {ScreenPane#handle_key} — delivery to {#focused}, bubbling up the
+    #   3. {ScreenPane#handle_key?} — delivery to {#focused}, bubbling up the
     #      focus chain to the scope root.
     # 
     # _@param_ `key`
     # 
     # _@return_ — true if the key was handled by some window.
-    def handle_key: (String key) -> bool
-
-    # Finds target window and calls {Component::Window#handle_mouse}.
-    # 
-    # _@param_ `event`
-    def handle_mouse: (MouseEvent event) -> void
+    def handle_key?: (String key) -> bool
 
     # Delivers pasted text to {#focused} ({ScreenPane#handle_paste}).
     # 
@@ -2234,12 +2543,11 @@ module Tuile
     # Tab traversal and the global-shortcut registry entirely, goes straight to
     # delivery, and does not bubble to ancestors the way a key does. Unhandled
     # text is dropped — there is no fallback that replays it as keys, which
-    # would put back the very ambiguity mode 2004 exists to remove.
+    # would put back the very ambiguity mode 2004 exists to remove — and with no
+    # alternative delivery, no verdict to carry either.
     # 
     # _@param_ `text`
-    # 
-    # _@return_ — true if the focused component consumed it.
-    def handle_paste: (String text) -> bool
+    def handle_paste: (String text) -> void
 
     def event_loop: () -> void
 
@@ -2318,7 +2626,7 @@ module Tuile
     # Kept current across OS appearance flips, a frame behind: the flip
     # report carries light/dark only, so the screen re-probes and this
     # updates when the reply lands. A changed color then fires
-    # {Component#on_theme_changed} across the tree exactly as a theme swap
+    # {Component#handle_theme_changed} across the tree exactly as a theme swap
     # does — a background-derived tint *is* a theme-derived color.
     attr_reader background_color: Color?
 
@@ -2348,17 +2656,17 @@ module Tuile
     # 
     #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
     # 
-    # **Edge-triggered**, like {Component#on_attached}: re-assigning the
+    # **Edge-triggered**, like {Component#handle_attached}: re-assigning the
     # component that already has focus fires nothing, so a callback can be as
     # expensive as rebuilding a hint string without a `did it really change?`
     # guard of its own. That matters more than it looks — `ScreenPane#content=`
     # clears focus on every content swap, which on a level-triggered hook would
     # fire a nil→nil notification during assembly.
     # 
-    # It runs *after* the active-flag cascade and `on_focus`, so the tree is
+    # It runs *after* the active-flag cascade and `handle_focus`, so the tree is
     # settled. Two things a callback must tolerate: {#focused} being `nil`, and
     # firing during {#close} — teardown clears focus, exactly as it fires
-    # {Component#on_detached}. A raising callback propagates out of {#focused=}
+    # {Component#handle_detached}. A raising callback propagates out of {#focused=}
     # and leaves focus assigned; keep it trivial, as with the attach hooks.
     attr_accessor on_focus_changed: Proc?
 
@@ -2377,7 +2685,7 @@ module Tuile
   # Finds a component in the tree, so a spec can drive the UI it built four
   # layers down:
   # 
-  #   Testing.get(Component::Button, caption: "Save").handle_key(Keys::ENTER)
+  #   Testing.get(Component::Button, caption: "Save").handle_key?(Keys::ENTER)
   #   Testing.get(id: :name).value = "Zaphod"
   #   Testing.find(Component::Checkbox, in: pane, count: 3)
   # 
@@ -2393,7 +2701,7 @@ module Tuile
   # 
   # **A hidden component is never found**: these simulate a user, and a spec
   # that drove a hidden {Component::Button} would pass against a form nobody
-  # can operate. Both walk {Component#on_shown_tree}; a failed lookup says how
+  # can operate. Both walk {Component#walk_shown_tree}; a failed lookup says how
   # many hidden components *would* have matched, and {.dump} shows them.
   # 
   #   Testing.find(Component::TextField, count: 0)   # the user can't reach it
@@ -2404,7 +2712,7 @@ module Tuile
   # 
   # For *what a component shows*, assert on {Screen#buffer} instead — this
   # locates and drives, it does not replace that channel. See book ch8 for the
-  # worked usage and `DECISIONS.md` `D_component_lookup` for the design.
+  # worked usage and `design/decisions.md` `D_component_lookup` for the design.
   module Testing
     # Every component in the searched tree matching the spec, in pre-order.
     # 
@@ -2579,6 +2887,29 @@ module Tuile
   # isn't {Screen#pane}) is never enqueued for repaint via {#invalidate}, and
   # any stale invalidation entries are filtered out at drain time. Subclasses
   # can paint freely in {#repaint} without re-asserting attachment.
+  # 
+  # == Handlers and listener slots
+  # 
+  # Two families, told apart by the `=`:
+  # 
+  #   class Trimmed < Component::TextField
+  #     def handle_blur                  # handle_ — the override point
+  #       super
+  #       self.text = text.strip
+  #     end
+  #   end
+  # 
+  #   label.on_theme_changed = -> { … }   # on_…= — the listener slot
+  # 
+  # **What a handler returns is per hook**, declared in its own rdoc. Only the
+  # ones a dispatcher routes answer at all — {#handle_key?},
+  # {#handle_text_input_key?}, `MenuBar#handle_mnemonic?` — where `true` means "I
+  # took this, stop bubbling". The rest, {#handle_paste} included, return `void`.
+  # 
+  # An override calls `super`, even where the base body is empty: that is what
+  # lets a hook grow an `on_foo=` slot without breaking you. The one carve-out is
+  # {#handle_child_removed}, whose base does real work and whose overrides
+  # replace it. `D_handler_naming` carries the argument.
   class Component
     extend Tuile::Final
     BG_STATES: ::Array[Symbol]
@@ -2618,7 +2949,7 @@ module Tuile
     # It flows **downward only**: no container consults it when dividing space,
     # so {#rect} still means exactly what the parent assigned (`D_extent`). Three
     # things read it, all of them this component or the framework painting it:
-    # {#clear_outside_extent} blanks the dead tail, {#handle_mouse} hit-tests
+    # {#clear_outside_extent} blanks the dead tail, {Mouse::Router} hit-tests
     # against it so a click on that tail doesn't activate the widget, and a
     # dropdown anchors under it rather than under unused space.
     # 
@@ -2629,7 +2960,7 @@ module Tuile
     def extent: () -> Size?
 
     # {#extent} placed at {#rect}'s top-left, for the consumers that need
-    # coordinates: `extent_rect.contains?(event.point)` in a {#handle_mouse}, and
+    # coordinates: `extent_rect.contains?(point)` in {Mouse::Router}, and
     # the anchor a dropdown hangs from. Total — an undeclared {#extent} yields
     # the whole {#rect}, so a generic caller never sees `nil`.
     def extent_rect: () -> Rect
@@ -2659,7 +2990,7 @@ module Tuile
     #   showing it restores exactly the subtree that was showing before.
     # - **Focus never stays on what the user cannot see.** Hiding the subtree
     #   holding focus repairs it exactly as removing that subtree would (see
-    #   {#on_child_removed}), and does not hand it back on the way in.
+    #   {#handle_child_removed}), and does not hand it back on the way in.
     # 
     # For "invisible but still occupying its space", use a
     # {Component::Slot} with no content (`D_slots`).
@@ -2688,6 +3019,9 @@ module Tuile
     # skipping `super`.** The clear then covers only what is outside it, so the
     # cells it is about to repaint are not blanked first — blanking them would
     # mark them dirty and make {Buffer#flush} re-emit them (`D_progress_bar`).
+    # That saving is a *leaf*'s: a container's children paint its extent for it,
+    # so a cell among them that none covers still gets blanked — an extent
+    # narrows which cells are yours, never whether your gaps are wiped.
     # 
     # **The children are re-invalidated whether or not they tile.** A container
     # that paints nothing of its own can only redraw its area *through* them, so
@@ -2709,48 +3043,108 @@ module Tuile
     # on the key alone and never gate on your own {#active?} state. See book ch5
     # for how a keystroke is routed to reach here.
     # 
+    # The `?` reads like `Set#add?`: calling it *delivers* the key and reports
+    # whether it was taken, so it is never a "would you handle this?" probe.
+    # 
     # _@param_ `_key` — a key.
     # 
     # _@return_ — true if the key was handled, false if not.
-    def handle_key: (String _key) -> bool
+    def handle_key?: (String _key) -> bool
 
     # Called when text is pasted while this component is {Screen#focused};
-    # override to accept it (the default reports every paste unhandled, and
-    # unhandled text is dropped). Unlike a key, a paste does **not** bubble —
-    # only the focused component is offered it, so an ancestor never sees one
-    # its descendant declined. The text arrives whole and `\n`-normalized, so
-    # `text.lines.size` is the paste's line count and a single mutation can
-    # absorb it:
+    # override to accept it. The default drops the text. It arrives whole and
+    # `\n`-normalized, so `text.lines.size` is the paste's line count and a
+    # single mutation can absorb it:
     # 
     #   def handle_paste(text)
     #     self.caption = "[Pasted #{text.lines.size} lines]"
-    #     true
     #   end
     # 
+    # **No verdict, unlike {#handle_key?}**: a paste reaches the focused component
+    # and stops, so one that declines has nowhere to hand it on to
+    # (`D_bracketed_paste`).
+    # 
     # Reaching here means the terminal said "this came from the clipboard" —
     # {Component::AbstractStringField} inserts it at the caret, which is why a
     # subclass that rebinds ENTER to submit needs no paste handling of its own
     # to stop firing once per pasted line.
     # 
     # _@param_ `_text` — the pasted text.
+    def handle_paste: (String _text) -> void
+
+    # Called when a mouse button goes down over this component; answer `true` to
+    # claim the press. The default claims nothing.
+    # 
+    #   def handle_mouse_down?(event)
+    #     return false unless event.button == :left
     # 
-    # _@return_ — true if the paste was consumed.
-    def handle_paste: (String _text) -> bool
+    #     @on_click&.call
+    #     true
+    #   end
+    # 
+    # {Mouse::Router} delivers it to the innermost component under the pointer
+    # and bubbles it up the ancestors until one answers `true`; the claimant
+    # then holds the *grab*, and the button's {#handle_mouse_drag} and
+    # {#handle_mouse_up} go to it alone. The press has already moved focus by
+    # the time it arrives, and it only arrives where {#extent_rect} contains the
+    # point, so an override needs neither `super` nor a hit test of its own.
+    # 
+    # Activate here, on the press: Tuile synthesizes no click, because a release
+    # is losable over ssh and tmux (`D_mouse_dispatch`).
+    # 
+    # _@param_ `_event`
+    # 
+    # _@return_ — whether this component claimed the press.
+    def handle_mouse_down?: (Mouse::DownEvent _event) -> bool
+
+    # Called when the wheel turns over this component; answer `true` to consume
+    # the notch. Bubbles exactly as {#handle_mouse_down?} does, but grabs
+    # nothing — so a scroller already at its limit answers `false` and its
+    # ancestor scrolls instead.
+    # 
+    # _@param_ `_event`
+    # 
+    # _@return_ — whether this component consumed the notch.
+    def handle_mouse_scroll?: (Mouse::ScrollEvent _event) -> bool
 
-    # Focuses this component when left-clicked (if {#focusable?}), then hands the
-    # event down to every child whose {#rect} contains the point — which is how a
-    # click descends the tiled tree to a leaf.
+    # Called when the pointer moves over this component with nothing grabbed;
+    # answer `true` to consume the move. Bubbles as {#handle_mouse_down?} does.
+    # Arrives only under `run_event_loop(capture_mouse: :hover)`, at up to ~84
+    # events a second, which is why the default passes it on untouched.
+    # 
+    # _@param_ `_event`
     # 
-    # A widget that resolves clicks *inside* its own rect — mapping a point to a
-    # row, or toggling an overlay — overrides this and does not call `super`.
-    # Such an override hit-tests {#extent_rect} rather than {#rect}, so a click
-    # on the tail it doesn't paint never activates it.
+    # _@return_ — whether this component consumed the move.
+    def handle_mouse_move?: (Mouse::MoveEvent _event) -> bool
+
+    # Called on the component that claimed a press when the button comes up,
+    # ending the grab. For press feedback and for ending a drag — never for
+    # activation: a release may never arrive, and any key or the next press
+    # ends the grab without it.
     # 
-    # The walk stops at a hidden child, so a hidden component is never reached
-    # and an override needs no `visible?` check of its own.
+    # _@param_ `_event`
+    def handle_mouse_up: (Mouse::UpEvent _event) -> void
+
+    # Called on the component that claimed a press whenever the pointer moves
+    # while the button is held, wherever the pointer is. Needs
+    # `capture_mouse: :drag` or `:hover`.
     # 
-    # _@param_ `event`
-    def handle_mouse: (MouseEvent event) -> void
+    # _@param_ `_event` — its point may lie outside {#rect}.
+    def handle_mouse_drag: (Mouse::DragEvent _event) -> void
+
+    # Called when the pointer comes over this component or any of its
+    # descendants — down the chain, root first, and after every
+    # {#handle_mouse_exit} the same move fires. Needs `capture_mouse: :hover`,
+    # and is suspended while a press is grabbed.
+    # 
+    # **Never a commit point**: no terminal reports the pointer leaving the
+    # window, so the matching {#handle_mouse_exit} may arrive late or not at
+    # all. Anything done here must be cosmetic and survive that.
+    def handle_mouse_enter: () -> void
+
+    # The other half of {#handle_mouse_enter}; also fires when this component is
+    # detached or hidden while hovered, innermost first.
+    def handle_mouse_exit: () -> void
 
     # _@return_ — true if the component is on the active chain — i.e. it
     # is the focused component or an ancestor of it. Set by {Screen#focused=}.
@@ -2787,30 +3181,30 @@ module Tuile
     def root: () -> Component
 
     # Calls block for this component and for every descendant component.
-    def on_tree: () ?{ (Component component) -> void } -> void
+    def walk_tree: () ?{ (Component component) -> void } -> void
 
-    # {#on_tree}, pruned: a hidden subtree is skipped whole, this component
+    # {#walk_tree}, pruned: a hidden subtree is skipped whole, this component
     # included when it is itself hidden (in which case nothing is yielded).
     # 
     #   stops = []
-    #   scope.on_shown_tree { |c| stops << c if c.tab_stop? }
+    #   scope.walk_shown_tree { |c| stops << c if c.tab_stop? }
     # 
-    # **Use this for anything asking "can the user reach it"**, {#on_tree} for
+    # **Use this for anything asking "can the user reach it"**, {#walk_tree} for
     # what the framework does *to* a component regardless — lifecycle, theme
     # fan-out, invalidation — which a hidden component still gets. Writing the
-    # first as `on_tree` plus a `visible?` test is the trap: that is this walk
+    # first as `walk_tree` plus a `visible?` test is the trap: that is this walk
     # with the ancestor case missing, so a field under a hidden panel is back
     # in the Tab cycle (`D_visibility`).
-    def on_shown_tree: () ?{ (Component component) -> void } -> void
+    def walk_shown_tree: () ?{ (Component component) -> void } -> void
 
     # Called when the component receives focus — on this component alone, never
-    # on the ancestors that light up with it. {#on_blur} is the other half.
+    # on the ancestors that light up with it. {#handle_blur} is the other half.
     # 
-    # Unlike `on_blur` it is **not** edge-triggered: it fires on every
+    # Unlike `handle_blur` it is **not** edge-triggered: it fires on every
     # {Screen#focused=}, re-assigning the component that already has focus
     # included, which is what lets a container forward focus into its content
     # from here.
-    def on_focus: () -> void
+    def handle_focus: () -> void
 
     # Whether this component's tree is mounted on a UI, {ScreenPane} being the
     # root of every displayed tree.
@@ -2838,8 +3232,11 @@ module Tuile
     # its parent: an override may repair focus however it likes, but must not
     # assume the child is gone. Removal bookkeeping belongs in the remover.
     # 
+    # The one hook whose base body does real work, so an override *replaces* it
+    # (as {Component::Slot} and {ScreenPane} do) instead of calling `super`.
+    # 
     # _@param_ `child` — the just-detached, or just-hidden, child.
-    def on_child_removed: (Component child) -> void
+    def handle_child_removed: (Component child) -> void
 
     # Where the hardware terminal cursor should sit when this component is the
     # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
@@ -2885,7 +3282,7 @@ module Tuile
     # _@param_ `at` — index to insert at; appends when nil.
     def add_child: (Component child, ?at: Integer?) -> void
 
-    # Drops `child` and notifies {#on_child_removed}.
+    # Drops `child` and notifies {#handle_child_removed}.
     # Final: one of the three mutators that write {#children} and the parent
     # pointer in the same call, which is what keeps them in agreement.
     # 
@@ -2893,12 +3290,12 @@ module Tuile
     def remove_child: (Component child) -> void
 
     # Drops `child` *without* notifying — for a container swapping a named slot,
-    # which owes the {#on_child_removed} call once the new occupant is wired:
+    # which owes the {#handle_child_removed} call once the new occupant is wired:
     # 
     #   detach_child(old)
     #   @content = new
     #   add_child(new, at: 0)
-    #   on_child_removed(old)   # focus repair cascades into the *new* content
+    #   handle_child_removed(old)   # focus repair cascades into the *new* content
     # 
     # The child leaves {#children} before its pointer is cleared, so nothing
     # observes a child whose parent has disowned it while still listing it.
@@ -2912,33 +3309,33 @@ module Tuile
     # i.e. when {#attached?} flips to true — the place to acquire whatever is
     # supposed to live for exactly as long as the component is on screen:
     # 
-    #   def on_attached
+    #   def handle_attached
     #     @ticker = screen.event_queue.tick_fps(10) { advance }
     #   end
     # 
-    #   def on_detached
+    #   def handle_detached
     #     @ticker&.cancel
     #     @ticker = nil
     #   end
     # 
-    # `on_attached` starts what `on_detached` stops; both must be cheap and
+    # `handle_attached` starts what `handle_detached` stops; both must be cheap and
     # idempotent, since a component moved between parents is genuinely detached
     # in between and gets both, in that order. Whatever you acquire here you
-    # must release in {#on_detached} — nothing else will. Not a destructor:
-    # process teardown does *not* fire {#on_detached}.
+    # must release in {#handle_detached} — nothing else will. Not a destructor:
+    # process teardown does *not* fire {#handle_detached}.
     # 
     # {#invalidate} needs no guard: {#attached?} is already true here (and
-    # already false in {#on_detached}, where it no-ops). Do not read {#rect} —
+    # already false in {#handle_detached}, where it no-ops). Do not read {#rect} —
     # a parent assigns it *after* wiring, so it is still stale. Runs on the
     # thread that owns the UI.
-    def on_attached: () -> void
+    def handle_attached: () -> void
 
-    # Mirror of {#on_attached}, called once the tree has been unmounted — see
+    # Mirror of {#handle_attached}, called once the tree has been unmounted — see
     # there for the contract. Two things are still mid-flight when it runs, both
     # deliberate: {Screen#focused} may still point into this subtree (repair
     # happens after), and the ex-parent's own bookkeeping may not be finished.
     # So release resources here and don't inspect the tree around you.
-    def on_detached: () -> void
+    def handle_detached: () -> void
 
     # Walks self-then-children calling one lifecycle hook, delivering at most one
     # call per component per transition however the hooks mutate the tree. Two
@@ -2950,22 +3347,25 @@ module Tuile
     #   current attachedness rather than on `parent.equal?(self)`: a child pulled
     #   out during a detach walk is *already* detached, so its own `parent=` saw
     #   no transition and stayed silent — a parentage check would skip it too and
-    #   it would never hear `on_detached` at all. The reverse case (pulled out
-    #   during an *attach* walk) gets `on_detached` from its own `parent=` and no
-    #   `on_attached`, which is why the hooks are required to be idempotent: an
-    #   unpaired detach releases nothing, whereas firing `on_attached` at a
+    #   it would never hear `handle_detached` at all. The reverse case (pulled out
+    #   during an *attach* walk) gets `handle_detached` from its own `parent=` and no
+    #   `handle_attached`, which is why the hooks are required to be idempotent: an
+    #   unpaired detach releases nothing, whereas firing `handle_attached` at a
     #   component that is no longer attached would start a ticker nothing stops.
     # 
-    # _@param_ `attached` — true to fire {#on_attached}, false for {#on_detached}.
+    # _@param_ `attached` — true to fire {#handle_attached}, false for {#handle_detached}.
     def fire_lifecycle: (bool attached) -> void
 
     # Called whenever the component width changes. Does nothing by default.
-    def on_width_changed: () -> void
+    def handle_width_changed: () -> void
 
     # Called on the parent after a direct child's {#visible=} flipped, so a
     # container that divides space can re-divide it:
     # 
-    #   def on_child_visibility_changed(_child) = relayout
+    #   def handle_child_visibility_changed(_child)
+    #     super
+    #     relayout
+    #   end
     # 
     # **A container with layout arithmetic owes this override**, or a hidden
     # child keeps its slot and its gap — the hole the flag exists to close.
@@ -2973,27 +3373,31 @@ module Tuile
     # arithmetic, and an app wanting the space back reads `visible?` there.
     # 
     # Fires on the flip only, before the subtree is invalidated, never for a
-    # grandchild. {#visible=} repairs focus itself, so an override needs no
-    # `super`. Reached through `__send__`, so it may declare any visibility
-    # (`D_hook_visibility`).
+    # grandchild. {#visible=} repairs focus itself, so an override has nothing
+    # to inherit — it still calls `super`, per the class doc. Reached through
+    # `__send__`, so it may declare any visibility (`D_hook_visibility`).
     # 
     # _@param_ `_child` — the direct child whose flag changed.
-    def on_child_visibility_changed: (Component _child) -> void
+    def handle_child_visibility_changed: (Component _child) -> void
 
-    # Mirror of {#on_focus}: the component just lost focus, to another component
+    # Mirror of {#handle_focus}: the component just lost focus, to another component
     # or to nothing. The commit point a Tab-away still reaches — Tab is
     # unconditional, so {Component::TextField#on_enter} never fires for a user
     # who tabs out of a half-typed field:
     # 
     #   class TrimmedField < Component::TextField
-    #     protected def on_blur = (self.text = text.strip)
+    #     protected def handle_blur
+    #       super
+    #       self.text = text.strip
+    #       false
+    #     end
     #   end
     # 
     # Edge-triggered, and fired on the blurred component alone — never on the
     # ancestors leaving the active chain with it, so a composed widget asking
     # "did focus leave me *and* my children" overrides {#active=} instead
     # ({Component::ComboBox} closes its dropdown from there). Focus that merely
-    # *passes through* does blur: a container forwarding focus from {#on_focus}
+    # *passes through* does blur: a container forwarding focus from {#handle_focus}
     # is blurred by its own forward.
     # 
     # A notification, not a veto — focus has already moved, and the active-flag
@@ -3006,11 +3410,47 @@ module Tuile
     # It fires wherever focus is *dropped*, not only where a user moved it, so
     # two paths reach it with the tree mid-flight: the popup-close repair blurs
     # an **already-detached** component, where {#invalidate} is the same silent
-    # no-op as in {#on_detached}, and {Screen#close} blurs on its way out. Keep
+    # no-op as in {#handle_detached}, and {Screen#close} blurs on its way out. Keep
     # it cheap; a raise propagates out of {Screen#focused=}. Protected because
     # the framework calls it and an app never does — {Screen} reaches it with
     # `__send__`, so an override may declare any visibility (`D_hook_visibility`).
-    def on_blur: () -> void
+    def handle_blur: () -> void
+
+    # Called on every attached component (pre-order, popups included) when
+    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=} and on
+    # OS appearance flips. The hook exists for app *content* whose colors were
+    # baked in from the old theme (a {Label#text} / {List#lines=} {StyledString}
+    # styled with `theme[:accent]`); rebuild it here by re-running the code that
+    # rendered it. See book ch6 for why built-in accents need no such handling.
+    # 
+    # Runs on the UI thread with {Screen#theme} already updated, so mutating
+    # content (`text=`, `lines=`, …) is safe. Do not assign {Screen#theme=}
+    # here. Subclasses overriding this must call `super` so an assigned
+    # {#on_theme_changed=} listener keeps firing.
+    # 
+    # Plumbing an app overrides and never calls, hence protected — and
+    # {Screen}, not being a {Component}, fans it out through `__send__`, so an
+    # override is free to declare any visibility (`D_hook_visibility`).
+    # 
+    # _@return_ — is whatever the app's lambda happened to return.
+    def handle_theme_changed: () -> void
+
+    # Called on every attached component (pre-order, popups included) when
+    # {Screen#locale} changes — for state derived from the old conventions and
+    # **pushed** somewhere, such as a date already rendered into a {Label}'s
+    # text. Anything read at paint or parse time needs no override: the locale
+    # change invalidates the whole tree.
+    # 
+    # Runs on the UI thread with {Screen#locale} already updated. Subclasses
+    # overriding it must call `super` so an assigned {#on_locale_changed=}
+    # listener keeps firing.
+    # 
+    # Plumbing an app overrides and never calls, hence protected — {Screen}
+    # fans it out through `__send__`, so an override may declare any visibility
+    # (`D_hook_visibility`).
+    # 
+    # _@return_ — is whatever the app's lambda happened to return.
+    def handle_locale_changed: () -> void
 
     # The formatting conventions to render and parse by ({Screen#locale}), or
     # {Locale::ISO} when there is no screen in the process — which a tree
@@ -3049,6 +3489,21 @@ module Tuile
     # it directly.
     def clear_outside_extent: () -> void
 
+    # Blanks the {#extent} itself, for a *container* whose children don't cover
+    # it — a {Component::Layout::Box}'s `spacing` column, the slack past the last
+    # child, the span a child abandoned by going hidden or by a narrowing resize.
+    # 
+    # In the *ambient* background, the same answer {#clear_outside_extent} gives
+    # the dead tail: a gap between two children is not this widget's ink, so an
+    # app's {#bg_color} tint covers it but a well of its own — a field's, a
+    # validation error's — must not bleed into it.
+    # 
+    # Called by the default {#repaint} for a container only; a leaf paints its
+    # extent itself, and blanking that first is the re-emit `D_progress_bar`
+    # bought back. Override it to decline when you paint your own ink into a
+    # face cell no child covers.
+    def clear_inside_extent: () -> void
+
     # The background this component paints when the app has set no {#bg_color} —
     # `nil` by default, meaning "I have no surface of my own; whatever is behind
     # me shows through". A widget that paints an opaque surface overrides it, and
@@ -3065,7 +3520,7 @@ module Tuile
     # the cheap form and allocates nothing on the paint path.
     # 
     # Read the theme here rather than in an ivar: this runs at paint time, so a
-    # {Screen#theme=} restyles the widget with no {#on_theme_changed} hook.
+    # {Screen#theme=} restyles the widget with no {#handle_theme_changed} hook.
     def default_bg_color: () -> (Color | Theme::Ref | ::Hash[untyped, untyped])?
 
     # Final, and protected: it answers what the *framework* paints with, and an
@@ -3158,7 +3613,7 @@ module Tuile
                    ) -> void
 
     # Hands focus out of the subtree just hidden, if it was in there, through
-    # the parent's {#on_child_removed} — see there for why hiding reuses the
+    # the parent's {#handle_child_removed} — see there for why hiding reuses the
     # removal repair instead of growing a second one.
     # 
     # The parent is necessarily showing (focus was inside it a moment ago, and
@@ -3256,43 +3711,25 @@ module Tuile
     # callers! May be empty.
     attr_reader children: ::Array[Component]
 
-    # Called on every attached component (pre-order, popups included) when
-    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=} and on
-    # OS appearance flips. The hook exists for app *content* whose colors were
-    # baked in from the old theme (a {Label#text} / {List#lines=} {StyledString}
-    # styled with `theme[:accent]`); rebuild it here by re-running the code that
-    # rendered it. See book ch6 for why built-in accents need no such handling.
+    # Optional zero-arg listener fired by the base {#handle_theme_changed} — the
+    # composition-style alternative to overriding the method, for apps that
+    # assemble stock components rather than subclass:
     # 
-    # Runs on the UI thread with {Screen#theme} already updated, so mutating
-    # content (`text=`, `lines=`, …) is safe. Do not assign {Screen#theme=}
-    # here. Subclasses overriding this must call `super` so an assigned
-    # {#on_theme_changed=} listener keeps firing.
-    # 
-    # Plumbing an app overrides and never calls, hence protected — and
-    # {Screen}, not being a {Component}, fans it out through `__send__`, so an
-    # override is free to declare any visibility (`D_hook_visibility`).
+    #   label.on_theme_changed = -> { label.text = render_status_line }
     attr_accessor on_theme_changed: Proc?
 
-    # Called on every attached component (pre-order, popups included) when
-    # {Screen#locale} changes — for state derived from the old conventions and
-    # **pushed** somewhere, such as a date already rendered into a {Label}'s
-    # text. Anything read at paint or parse time needs no override: the locale
-    # change invalidates the whole tree.
+    # Optional zero-arg listener fired by the base {#handle_locale_changed} — the
+    # composition-style alternative to overriding the method, for an app that
+    # rendered a date or a number into a stock component:
     # 
-    # Runs on the UI thread with {Screen#locale} already updated. Subclasses
-    # overriding it must call `super` so an assigned {#on_locale_changed=}
-    # listener keeps firing.
-    # 
-    # Plumbing an app overrides and never calls, hence protected — {Screen}
-    # fans it out through `__send__`, so an override may declare any visibility
-    # (`D_hook_visibility`).
+    #   label.on_locale_changed = -> { label.text = due_date.strftime(fmt) }
     attr_accessor on_locale_changed: Proc?
 
     # A scrollable list of typed items, one row each, with cursor support.
     # 
     #   list = Component::List.new
     #   list.items    = people
-    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.hint(" #{p.email}") }
+    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.fg(:muted, " #{p.email}") }
     #   list.cursor   = List::Cursor.new                  # a bare list has none
     #   list.on_item_chosen = ->(index, person) { open(person) }
     # 
@@ -3374,7 +3811,7 @@ module Tuile
       # _@param_ `key` — a key.
       # 
       # _@return_ — true if the key was handled.
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # Moves the cursor to the next item whose text contains `query`
       # (case-insensitive substring match). Search wraps around the end of the
@@ -3414,8 +3851,17 @@ module Tuile
       # _@return_ — whether the cursor moved there.
       def select: (Integer index) -> bool
 
+      # Moves the cursor to the pressed row and fires {#on_item_chosen}; what
+      # each {Cursor} does with a press is its own.
+      # 
+      # _@param_ `event`
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
+
+      # Scrolls four rows a notch, and declines — so the notch bubbles to an
+      # ancestor scroller — once this list is at that end of its items.
+      # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_scroll?: (Mouse::ScrollEvent event) -> bool
 
       # Paints the visible items into {#rect}, rendering the ones not already
       # cached.
@@ -3436,7 +3882,7 @@ module Tuile
       # populated before the popup was opened), the auto-scroll update
       # was skipped because there was no viewport — re-run it now that there
       # is one, so the list snaps to the bottom on first paint.
-      def on_width_changed: () -> void
+      def handle_width_changed: () -> void
 
       # Coerces and flattens a list of input entries into trimmed
       # {StyledString} lines. Each entry becomes a {StyledString} (String
@@ -3524,7 +3970,7 @@ module Tuile
       # negating the auto-scroll. Skipped when {#rect} is empty: without a
       # viewport the "items minus viewport" formula yields `@items.size`,
       # which would leave `scroll_top_row` past the last item once a real rect
-      # arrives. {#on_width_changed} re-runs this hook when the rect grows so
+      # arrives. {#handle_width_changed} re-runs this hook when the rect grows so
       # the snap-to-bottom intent is preserved.
       # 
       # Gated on {#following?}: once the user scrolls up off the bottom the
@@ -3652,16 +4098,16 @@ module Tuile
         # _@param_ `viewport_rows` — number of visible rows.
         # 
         # _@return_ — true if the cursor moved.
-        def handle_key: (String key, Integer item_count, Integer viewport_rows) -> bool
+        def handle_key?: (String key, Integer item_count, Integer viewport_rows) -> bool
 
-        # _@param_ `item_index` — the item the cursor is hovering over.
+        # _@param_ `item_index` — the item pressed on.
         # 
         # _@param_ `event` — the event.
         # 
         # _@param_ `item_count` — number of items in the list.
         # 
-        # _@return_ — true if the event was handled.
-        def handle_mouse: (Integer item_index, MouseEvent event, Integer item_count) -> bool
+        # _@return_ — true if the cursor moved.
+        def handle_mouse_down?: (Integer item_index, Mouse::DownEvent event, Integer item_count) -> bool
 
         # Moves the cursor to the new position. Public only because of testing.
         # 
@@ -3701,14 +4147,14 @@ module Tuile
           # _@param_ `_item_count`
           # 
           # _@param_ `_viewport_rows`
-          def handle_key: (String _key, Integer _item_count, Integer _viewport_rows) -> bool
+          def handle_key?: (String _key, Integer _item_count, Integer _viewport_rows) -> bool
 
           # _@param_ `_item_index`
           # 
           # _@param_ `_event`
           # 
           # _@param_ `_item_count`
-          def handle_mouse: (Integer _item_index, MouseEvent _event, Integer _item_count) -> bool
+          def handle_mouse_down?: (Integer _item_index, Mouse::DownEvent _event, Integer _item_count) -> bool
 
           # _@param_ `_item_count`
           def candidate_positions: (Integer _item_count) -> ::Array[Integer]
@@ -3736,7 +4182,7 @@ module Tuile
           # _@param_ `event`
           # 
           # _@param_ `_item_count`
-          def handle_mouse: (Integer item_index, MouseEvent event, Integer _item_count) -> bool
+          def handle_mouse_down?: (Integer item_index, Mouse::DownEvent event, Integer _item_count) -> bool
 
           # _@param_ `item_count`
           def candidate_positions: (Integer item_count) -> ::Array[Integer]
@@ -3778,7 +4224,7 @@ module Tuile
     # (what {Window} does with an absent footer); never detach it.
     # 
     # Transparent to input: not {Component#focusable?},
-    # {Component#handle_mouse} descends through it, and a departing occupant's
+    # the mouse routes straight through it, and a departing occupant's
     # focus repair is handed to the container.
     class Slot < Component
       include Tuile::Component::HasContent
@@ -3791,7 +4237,7 @@ module Tuile
       # nothing to bubble from.
       # 
       # _@param_ `child` — the just-detached occupant.
-      def on_child_removed: (Component child) -> void
+      def handle_child_removed: (Component child) -> void
 
       # _@param_ `content`
       def layout: (Component content) -> void
@@ -3799,7 +4245,7 @@ module Tuile
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
     end
 
     # A one-row strip of captions with exactly one of them selected — the map of
@@ -3829,7 +4275,7 @@ module Tuile
     # 
     # {Tab} handles are minted by {#add_tab} and owned by the strip. There is no
     # `items=`: a tab is identity plus its own state, so the set grows and
-    # shrinks one tab at a time. See book ch7 and `DECISIONS.md` `D_tabs`.
+    # shrinks one tab at a time. See book ch7 and `design/decisions.md` `D_tabs`.
     # 
     # == Sizing
     # Assign a {#rect} (typically from the surrounding {Layout}). One wider than
@@ -3913,7 +4359,7 @@ module Tuile
       # 
       # Both the focus highlight and the click hit test use it, so a click on the
       # blank tail — or on a lower row, when the rect is taller than one —
-      # selects nothing. It still *focuses*: {Component#handle_mouse}'s
+      # selects nothing. It still *focuses*: {Mouse::Router}'s
       # click-to-focus is ungated by geometry.
       def extent: () -> Size
 
@@ -3922,13 +4368,13 @@ module Tuile
       # bubbles to an ancestor; an empty strip handles nothing at all.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
-      # Selects the tab under a left click; `super` runs first, so a click
-      # anywhere in {#rect} still focuses.
+      # Selects the tab under a left press; a press between tabs selects
+      # nothing and still claims the strip.
       # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
@@ -3938,7 +4384,7 @@ module Tuile
 
       # The rect's *width* is the only part of it the offset depends on, so this
       # hook is the whole geometry story; {Component#rect=} invalidates for us.
-      def on_width_changed: () -> void
+      def handle_width_changed: () -> void
 
       # Scrolls the minimum needed to show the selected segment whole, and is the
       # sole writer of {#left_column}. Idempotent, so every mutation site can
@@ -4134,7 +4580,7 @@ module Tuile
       # that carries its own background keeps it.
       def repaint: () -> void
 
-      def on_width_changed: () -> void
+      def handle_width_changed: () -> void
 
       # Recomputes {@rows} for the current text and rect width.
       # Each line is ellipsized to fit and padded with trailing spaces out to
@@ -4178,7 +4624,7 @@ module Tuile
     # 
     # `q` and ESC close the popup — handled here, at the top of the popup's own
     # subtree, so the key only arrives after every component on the focus chain
-    # declined it (see {ScreenPane#handle_key}). That's why typing `q` into a
+    # declined it (see {ScreenPane#handle_key?}). That's why typing `q` into a
     # nested {Component::TextField} doesn't dismiss the popup: the field consumes
     # it first.
     # 
@@ -4224,7 +4670,7 @@ module Tuile
       # _@param_ `key`
       # 
       # _@return_ — true if the key was handled.
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # The box this popup asks for, *as set* — a {Fraction} comes back
       # unresolved. {#rect} is the resolved answer. Named apart from `size`
@@ -4243,7 +4689,7 @@ module Tuile
     # 
     # Buttons are tab stops — Tab and Shift+Tab will land on them as part of
     # the standard focus cycle. Click-to-focus also works via the inherited
-    # {Component#handle_mouse}.
+    # {Component#handle_mouse_down?}.
     # 
     # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
     # show `[ caption ]` — that natural width is `caption.display_width + 4`.
@@ -4260,13 +4706,13 @@ module Tuile
       def tab_stop?: () -> bool
 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # The cells the button actually paints: one row, `caption.display_width + 4`
       # columns, clipped to {#rect}. Both the focus highlight and the click hit
       # test use it, so a click on the blank tail of an over-wide rect — or on a
       # lower row, when the rect is taller than one — does not fire {#on_click}.
-      # It still *focuses*: {Component#handle_mouse}'s click-to-focus is ungated
+      # It still *focuses*: {Mouse::Router}'s click-to-focus is ungated
       # by geometry. Same rule as {Checkbox#extent}, which documents the two
       # traps behind it.
       def extent: () -> Size
@@ -4275,7 +4721,7 @@ module Tuile
       # a click anywhere in {#rect} still focuses.
       # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
@@ -4324,7 +4770,7 @@ module Tuile
       # the popup. Layouts don't paint any visible chrome of their own
       # (the auto-cleared background is just blank space), so this has no
       # mouse-routing consequences — clicks on a gap area land back on the
-      # Layout itself and the on_focus cascade forwards to a tab stop.
+      # Layout itself and the handle_focus cascade forwards to a tab stop.
       def focusable?: () -> bool
 
       # Adds a child component to this layout.
@@ -4335,7 +4781,7 @@ module Tuile
       # _@param_ `child`
       def remove: (Component child) -> void
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # How much space a child gets along one axis of a {Box}: exactly {#cells},
       # clamped to whatever is still unassigned.
@@ -4592,7 +5038,7 @@ module Tuile
         # {Component#visible=} buys over `remove` plus `add(…, at:)`.
         # 
         # _@param_ `_child`
-        def on_child_visibility_changed: (Component _child) -> void
+        def handle_child_visibility_changed: (Component _child) -> void
 
         # Recomputes and assigns every child's rect, giving each an empty one
         # when this layout's own rect — or {#inner_rect} — is empty.
@@ -4835,7 +5281,7 @@ module Tuile
     # Home/End are declined too, so they stay available app-wide.
     # 
     # There is no type-ahead: a hidden prefix buffer *is* the ComboBox query with
-    # the feedback removed (`DECISIONS.md` `D_select`). Which is also why labels
+    # the feedback removed (`design/decisions.md` `D_select`). Which is also why labels
     # need no prefix-disambiguation.
     # 
     # == Implementation details
@@ -4880,22 +5326,21 @@ module Tuile
       # is left unhandled so it bubbles to an ancestor.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # The one row this Select paints — the full width, at the top of {#rect}.
       # A single-slot container ({Component::Window}, {Component::Popup}) hands
       # its content the whole inner rect, so a Select is routinely assigned more
-      # height than it uses; {#repaint} clears that tail, {#handle_mouse} refuses
-      # clicks in it, and the dropdown hangs under this rather than under the
+      # height than it uses; {#repaint} clears that tail, a press in it never reaches
+      # {#handle_mouse_down?}, and the dropdown hangs under this rather than under the
       # unused space.
       def extent: () -> Size
 
-      # Toggles the dropdown on a left click anywhere in {#extent} — a field's
-      # affordance is its whole row, as the well advertises; `super` runs first,
-      # so the click also focuses.
+      # Toggles the dropdown on a left press anywhere in {#extent} — a field's
+      # affordance is its whole row, as the well advertises.
       # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
@@ -4975,7 +5420,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -5131,7 +5576,7 @@ module Tuile
       # Adds `caption="…"` to {Component#inspect}, omitted while empty.
       def inspect_details: () -> ::Array[String]
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # _@return_ — optional chrome embedded into the bottom border
       # line, mirroring {#caption} on the top line. Empty by default; hidden
@@ -5160,7 +5605,7 @@ module Tuile
     # **{#focusable?} and {#modal?} move together — flip both or neither.** The
     # defaults here are inert (`false`, `false`): a bare overlay floats without
     # disturbing focus or key dispatch. {Component::Popup} flips both. What must
-    # not appear is a *focusable non-modal* overlay: {ScreenPane#handle_key}
+    # not appear is a *focusable non-modal* overlay: {ScreenPane#handle_key?}
     # scopes delivery to the topmost modal popup or else the tiled content, so
     # such an overlay would hold focus outside the key scope, where delivery
     # reaches nobody and *every* keystroke goes dead until Tab recovers. A
@@ -5211,9 +5656,9 @@ module Tuile
       def visible=: (bool _value) -> void
 
       # Whether a left click outside this overlay closes it (default true). The
-      # pane does the closing — {ScreenPane#handle_mouse} snapshots the open
-      # overlays *before* routing the click and closes the dismissable ones
-      # *after*, so a widget that toggles its own overlay from a click on its
+      # pane does the closing — {ScreenPane#dismissing_popups_outside} snapshots
+      # the open overlays *before* the press is routed and closes the
+      # dismissable ones *after*, so a widget that toggles its own overlay from a click on its
       # face (a {Component::Select}, a {Component::MenuBar} title) still toggles
       # correctly: the delivered click closes the overlay and the dismissal then
       # no-ops on it, rather than closing and reopening it. Only `:left`
@@ -5249,7 +5694,7 @@ module Tuile
       #   overlay = Component::Overlay.new(content: label).open   # construct and mount
       # 
       # There is deliberately no class-level `Overlay.open` factory — see
-      # `DECISIONS.md` `D_popup_open`; returning `self` is what keeps the
+      # `design/decisions.md` `D_popup_open`; returning `self` is what keeps the
       # one-liner above available without one.
       def open: () -> self
 
@@ -5267,7 +5712,7 @@ module Tuile
 
       # Fires {#on_close}. A subclass overriding this **must** call `super`, or
       # the overlay's driver never hears that it closed.
-      def on_detached: () -> void
+      def handle_detached: () -> void
 
       # Content fills the overlay's full rect — an Overlay has no border to
       # subtract.
@@ -5275,7 +5720,7 @@ module Tuile
       # _@param_ `content`
       def layout: (Component content) -> void
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # _@return_ — see {#close_on_outside_click?}.
       attr_writer close_on_outside_click: bool
@@ -5298,12 +5743,12 @@ module Tuile
       # A callback taking no arguments, fired once this overlay has left the
       # screen — **however it left**: {#close}, a direct {Screen#remove_popup},
       # an outside click, or teardown via {Screen#close}. That unconditionality
-      # is the point, so it hangs off {#on_detached} rather than {#close}; a
+      # is the point, so it hangs off {#handle_detached} rather than {#close}; a
       # driver keeping its own record of open overlays reconciles it here and
       # cannot drift ({Component::MenuBar::Cascade} is the worked example).
       # 
       # It fires *after* the overlay is detached, so {#open?} is already false
-      # and the usual {Component#on_detached} caveats apply: release state, don't
+      # and the usual {Component#handle_detached} caveats apply: release state, don't
       # inspect the tree, keep it trivial (it may run while the pane is mid-way
       # through closing a batch of overlays, and a raise propagates).
       attr_accessor on_close: Proc?
@@ -5385,7 +5830,7 @@ module Tuile
       # 
       # Both the focus highlight and the click hit test use it, so a click on the
       # blank tail — or on a lower row, when the rect is taller than one — does
-      # not toggle. It still *focuses*: {Component#handle_mouse}'s click-to-focus
+      # not toggle. It still *focuses*: {Mouse::Router}'s click-to-focus
       # is ungated by geometry, and the tail is the field's own row.
       # 
       # The extent ignores {Component#bg_color}: an inherited tint paints the dead
@@ -5397,13 +5842,13 @@ module Tuile
       # to an ancestor.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
-      # Toggles on a left click within {#extent}; `super` runs first, so a click
-      # anywhere in {#rect} still focuses.
+      # Toggles on a left press; a press on the dead tail past {#extent} focuses
+      # the checkbox without reaching here.
       # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
@@ -5444,7 +5889,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -5515,7 +5960,7 @@ module Tuile
     # 
     # {Item} handles are minted by {#add_item} and nest via the *same* method, so
     # depth is unlimited. There is no removal, no reordering and no dynamic
-    # rebuilding: a menu is built once, at construction. See `DECISIONS.md`
+    # rebuilding: a menu is built once, at construction. See `design/decisions.md`
     # `D_menu_bar`.
     # 
     # == Sizing
@@ -5577,7 +6022,7 @@ module Tuile
       # 
       # Both the highlight and the click hit test use it, so a click on the blank
       # tail — or on a lower row, when the rect is taller than one — opens
-      # nothing. It still *focuses*: {Component#handle_mouse}'s click-to-focus is
+      # nothing. It still *focuses*: {Mouse::Router}'s click-to-focus is
       # ungated by geometry.
       def extent: () -> Size
 
@@ -5593,7 +6038,7 @@ module Tuile
       # Closes the cascade, so a bar removed from the tree can't strand its
       # panels on the pane — they are the {ScreenPane}'s children, not the bar's,
       # so nothing else would take them down.
-      def on_detached: () -> void
+      def handle_detached: () -> void
 
       # Offers the key to the open cascade first, then to the strip's own
       # LEFT/RIGHT/Enter/Space/Down.
@@ -5603,14 +6048,14 @@ module Tuile
       # submenu — and both step to the sibling menu.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
-      # Opens the menu under a left click, or closes it when it is already the
-      # open one; `super` runs first, so a click anywhere in {#rect} still
-      # focuses.
+      # Opens the menu under a left press, or closes it when it is already the
+      # open one; a press on the strip's padding claims the press and does
+      # nothing else.
       # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
@@ -5629,7 +6074,7 @@ module Tuile
       # The rect's *width* is the only part of it the offset depends on, so this
       # hook is the whole geometry story; {Component#rect=} invalidates for us,
       # and {#rect=} closes the cascade rather than re-anchoring it.
-      def on_width_changed: () -> void
+      def handle_width_changed: () -> void
 
       # Scrolls the minimum needed to show the highlighted segment whole, and is
       # the sole writer of {#left_column}. Idempotent, so every mutation site can
@@ -5719,7 +6164,7 @@ module Tuile
       # _@param_ `key`
       # 
       # _@return_ — whether a mnemonic claimed the key.
-      def handle_mnemonic: (String key) -> bool
+      def handle_mnemonic?: (String key) -> bool
 
       # Moves the highlight along the strip, clamping at both ends. Consumes the
       # key even at an end, as {Tabs} does.
@@ -5841,18 +6286,18 @@ module Tuile
       # machinery of {MenuBar}; an app never names it.
       # 
       #   cascade.open_below(segment_rect, item)   # Enter/Down on the strip
-      #   return true if cascade.handle_key(key)   # MenuBar#handle_key, first
+      #   return true if cascade.handle_key?(key)   # MenuBar#handle_key?, first
       #   cascade.close                            # focus lost, or rect changed
       # 
       # A panel is a **non-modal overlay, not a child**, so it never takes focus:
       # focus stays on the {MenuBar} for the whole interaction and every key
-      # arrives via {MenuBar#handle_key}, which offers it here first. That is
+      # arrives via {MenuBar#handle_key?}, which offers it here first. That is
       # {Component::Select}'s architecture extended to N levels, and it is why
       # nothing in the key-dispatch ladder changes.
       # 
       # Widths are measured here, per level — the panel is as wide as the level's
       # widest label — because {ListDropdown} deliberately measures nothing
-      # itself (`DECISIONS.md` `D_select`).
+      # itself (`design/decisions.md` `D_select`).
       # 
       # == Implementation details
       # While open it consumes **everything** except the two keys that mean
@@ -5892,7 +6337,7 @@ module Tuile
         # _@return_ — `true` when consumed — almost always, while open.
         # `false` when closed, and for the two sideways keys {MenuBar} answers
         # (see the class docs).
-        def handle_key: (String key) -> bool
+        def handle_key?: (String key) -> bool
 
         # Activates the deepest level's item bound to `key` — the drill-or-fire
         # the mnemonic shares with Enter. The highlight moves there *first*, so a
@@ -5903,7 +6348,7 @@ module Tuile
         # 
         # _@return_ — whether an item on the deepest level claimed it. A
         # miss is never offered to a shallower level.
-        def handle_mnemonic: (String key) -> bool
+        def handle_mnemonic?: (String key) -> bool
 
         # _@return_ — the deepest open panel.
         def deepest: () -> ListDropdown
@@ -5992,9 +6437,16 @@ module Tuile
     # The dropdown is a {ListDropdown}, tinted to read as a floating panel; see
     # it for the theming knob.
     # 
+    # == The inner field is private machinery
+    # It has no public accessor: its buffer is the *query*, so swapping the field
+    # would break the filtering. What is worth reaching is re-exposed here
+    # ({#placeholder}, {#cursor_position}); a **spec** reaches the field itself:
+    # 
+    #   field = Testing.get(Component::TextField, in: combo)
+    #   field.text = "ap"          # type a query without a real loop
+    # 
     # UI-thread-confined, like every component (see {Screen}).
     class ComboBox < Component
-      include Tuile::Component::HasContent
       include Tuile::Component::HasValue
       include Tuile::Component::HasPlaceholder
 
@@ -6020,12 +6472,13 @@ module Tuile
       # _@param_ `text`
       def placeholder=: (String? text) -> void
 
-      # Re-anchors the (open) dropdown after {HasContent#rect=} has resized the
-      # field via {#layout}.
+      # Resizes the field and re-anchors the dropdown if it is open.
       # 
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
 
+      def handle_focus: () -> void
+
       # Closes the dropdown and reverts an uncommitted query when the combo
       # leaves the focus chain — so tabbing away doesn't strand an open menu or
       # a half-typed filter. Safe against re-entrancy: focus never sits inside
@@ -6048,10 +6501,13 @@ module Tuile
       # _@param_ `key`
       # 
       # _@return_ — true if consumed.
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
+      # Toggles the dropdown on a left press on the ▾ cell — the only cell of
+      # this component's own that is not the field's.
+      # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
@@ -6067,12 +6523,10 @@ module Tuile
       # hangs under this rather than under the unused space below it.
       def extent: () -> Size
 
-      # Field spans the row bar the last column, which the `▾` occupies
-      # ({HasContent} layout hook). One row, or none at all when the combo itself
-      # was given none — a starved parent must not hand out a rect it doesn't own.
-      # 
-      # _@param_ `field`
-      def layout: (Component field) -> void
+      # Declines the default's blank: `field` covers every column of the face but
+      # the last, and this combo paints the `▾` into that one, so blanking would
+      # only dirty a cell it is about to repaint (`D_progress_bar`).
+      def clear_inside_extent: () -> void
 
       # Dismisses the dropdown and puts the current value's label back in the
       # field, undoing an uncommitted query.
@@ -6105,7 +6559,7 @@ module Tuile
       # Sets the field's text without triggering a refilter — for programmatic
       # value changes and query reverts, which must not spring the dropdown.
       # Every programmatic write to the field goes through here; a direct
-      # `content.text =` reaches the field's `on_change` and pops the dropdown
+      # `field.text =` reaches the field's `on_change` and pops the dropdown
       # open on a {#value=} the user never asked to browse.
       # Parks the caret at the end: `text=` only *clamps* the caret, so a
       # shorter query replaced by a longer label would otherwise strand it
@@ -6153,7 +6607,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -6183,14 +6637,15 @@ module Tuile
       # represent is invalid on the face too, even with no verdict written.
       def error_ink?: () -> bool
 
-      def on_focus: () -> void
-
       # _@return_ — the candidate items.
       attr_accessor items: ::Array[untyped]
 
       # _@return_ — item -> shown label (a `String` or
       # {StyledString}); the field shows its `#to_s`, the list its styled form.
       attr_accessor item_label: (Proc | Method)
+
+      # _@return_ — the inner field, holding the query.
+      attr_reader field: TextField
     end
 
     # The value seam every input component shares: a settable/gettable {#value}
@@ -6249,7 +6704,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -6311,11 +6766,11 @@ module Tuile
     # designing around:
     # 
     # - A hidden pane is invisible to *everything*: the Tab cycle, focus
-    #   cascades, repaint, the cursor, `on_tree` walks. No gates anywhere.
+    #   cascades, repaint, the cursor, `walk_tree` walks. No gates anywhere.
     # - Its state survives, because state is ivars — scroll position, caret,
     #   list cursor, text are all exactly as the user left them, and mutating a
     #   hidden pane is safe (`invalidate` while detached is a silent no-op).
-    # - {Component#on_detached} / {Component#on_attached} fire on every switch,
+    # - {Component#handle_detached} / {Component#handle_attached} fire on every switch,
     #   so a pane holding a mounted-lifetime resource — a {Component::ProgressBar}'s
     #   ticker — releases it while hidden and re-acquires it on return. A pane
     #   that must keep something alive while hidden can't; that something
@@ -6325,7 +6780,7 @@ module Tuile
     # `children` is `[strip, pane]`, the strip pinned at index 0, so pre-order
     # traversal gives the strip-then-pane Tab order for free. The swap follows
     # the slot-swap recipe {Component#detach_child} documents — detach, rewire,
-    # `on_child_removed` last, so the focus repair sees the new occupant.
+    # `handle_child_removed` last, so the focus repair sees the new occupant.
     # 
     # Panes live in an identity-keyed `Tab => Component` map here rather than in
     # a slot on {Tabs::Tab}: the strip's tab array stays the sole ordering
@@ -6396,14 +6851,14 @@ module Tuile
 
       # Sends focus to the strip: a sheet is a container, and the strip is where
       # a tab switch is driven from. The pane is a Tab press away.
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # Lands focus on the strip rather than on `self` when the focused pane is
       # swapped out — a bare container can't use keys, and the user's last
       # action was a tab switch.
       # 
       # _@param_ `child`
-      def on_child_removed: (Component child) -> void
+      def handle_child_removed: (Component child) -> void
 
       # Makes the visible pane match `strip.selected`, swapping if it doesn't.
       # Idempotent and the sole writer of `@pane`: it derives everything from
@@ -6468,7 +6923,7 @@ module Tuile
     #   class PromptArea < Component::TextArea
     #     protected
     # 
-    #     def handle_text_input_key(key)
+    #     def handle_text_input_key?(key)
     #       return recall_previous if key == Keys::UP_ARROW && caret_row.zero?
     #       return recall_next if key == Keys::DOWN_ARROW && caret_row == row_count - 1
     # 
@@ -6504,21 +6959,21 @@ module Tuile
       def cursor_position: () -> Point?
 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
-      def on_text_mutated: () -> void
+      def handle_text_mutated: () -> void
 
-      def on_caret_mutated: () -> void
+      def handle_caret_mutated: () -> void
 
       # HOME/END and CTRL+U act on the caret's **row** — the wrapped one, not
       # the `\n` line — so CTRL+U kills back to exactly where HOME would go.
       # 
       # _@param_ `key`
-      def handle_text_input_key: (String key) -> bool
+      def handle_text_input_key?: (String key) -> bool
 
-      def on_width_changed: () -> void
+      def handle_width_changed: () -> void
 
       # _@return_ — the current wrap of {#text} at {Rect#width}.
       def wrap: () -> WrappedText
@@ -6777,8 +7232,8 @@ module Tuile
     # splice a range in place. Turn on {#auto_scroll} to keep the latest content
     # in view.
     # 
-    # Meant to be the content of a {Window} — focus indication and keyboard-hint
-    # surfacing rely on the surrounding window chrome.
+    # Meant to be the content of a {Window} — focus indication relies on the
+    # surrounding window chrome.
     class TextView < Component
       def initialize: () -> void
 
@@ -6913,10 +7368,13 @@ module Tuile
       # an unfocused view scrolls it (dispatch gates on focus, this doesn't).
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
+      # Scrolls four rows a notch, and declines — so the notch bubbles to an
+      # ancestor scroller — once this view is at that end of its text.
+      # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_scroll?: (Mouse::ScrollEvent event) -> bool
 
       # Paints the text into {#rect}.
       # 
@@ -6930,7 +7388,7 @@ module Tuile
       # Rewraps the text on width changes — {#wrap_width} is {#rect}`.width`
       # minus {#scrollbar_columns}, and the latter varies with the width too.
       # A {#scrollbar_visibility=} flip rewraps from its own setter instead.
-      def on_width_changed: () -> void
+      def handle_width_changed: () -> void
 
       # Validates and unpacks a {#replace}-style range argument into
       # inclusive `[from, to]` line indices. An `Integer` `n` becomes
@@ -7292,7 +7750,7 @@ module Tuile
     # empty). Give it a single-row {#rect}:
     # 
     #   field = Component::DateField.new
-    #   field.on_value_change = ->(d) { puts d.inspect }  # Date or nil, per change
+    #   field.on_value_change = ->(d) { puts d.inspect }  # Date or nil, per commit
     #   field.value = Date.new(2026, 9, 4)                # field shows "2026-09-04"
     #   field.placeholder                                 # => "yyyy-mm-dd"
     #   field.clear                                       # empties it; value => nil
@@ -7349,6 +7807,19 @@ module Tuile
     # `20`, `202` stay quiet, leaving the field (or pressing ENTER) reddens what
     # did not parse, and the next edit clears it again.
     # 
+    # == The value notice waits for the same gesture
+    # A prefix of a date can also parse *cleanly*: typing `1.1.2024` into a
+    # `%d.%m.%Y` field passes through `1.1.2`, a perfectly good 1st of January
+    # in the year 2. So {HasValue#on_value_change} does not fire per keystroke,
+    # but when the user leaves the field or presses ENTER — and a form
+    # recalculating from it never sees that year 2.
+    # 
+    # {#value} does *not* wait: it is a live parse of the buffer at every
+    # moment, so a save gate reached without leaving the field reads the date
+    # on screen. Nor does a change nobody had to type — a {#value=}, an Up/Down
+    # step, a {#clear} and a reparse under new {#formats} all fire as they
+    # happen.
+    # 
     # == Implementation details
     # - **The buffer is the single source of truth.** {#value} is a parse of it,
     #   recomputed on read — so {#formats=} and {#calendar_start=} can change the
@@ -7456,6 +7927,11 @@ module Tuile
       # way, so input it could not parse starts painting the well.
       def commit: () -> void
 
+      # `false`: a prefix of a date can parse cleanly (`1.1.2` for `1.1.2024`),
+      # so the notice settles onto the commit gestures, exactly as the ink
+      # does. The class docs carry the case.
+      def notify_on_edit?: () -> bool
+
       # Every prefix of a date is bad input, so the well is latched to the
       # commit gestures instead of painted per keystroke: `2`, `20`, `202` on
       # the way to `2026-09-04` never redden, and a date the field cannot parse
@@ -7465,11 +7941,11 @@ module Tuile
 
       # An edit is the user having another go, so the well goes quiet again
       # until the next commit gesture.
-      def on_editor_change: () -> void
+      def handle_editor_change: () -> void
 
       # Re-derives the hint (which was *pushed* into the editor, so a repaint
       # alone would keep the old one) and rewrites a buffer that still parses.
-      def on_locale_changed: () -> void
+      def handle_locale_changed: () -> void
 
       # _@param_ `flag`
       def settle: (bool flag) -> void
@@ -7571,7 +8047,7 @@ module Tuile
     # - an **index** counts characters into {#text} — {#caret},
     #   {#max_text_length}, `text[i]`, every edit;
     # - a **column** counts terminal cells — {#rect}, {#cursor_position}, a
-    #   {MouseEvent}, and the private horizontal scroll offset `left_column`.
+    #   {Mouse::DownEvent}, and the private horizontal scroll offset `left_column`.
     # 
     # They coincide only while every glyph is one column wide. A fullwidth CJK
     # char is two columns and a combining mark zero, so index 3 of `"日本語"` is
@@ -7596,11 +8072,11 @@ module Tuile
 
       def cursor_position: () -> Point?
 
-      # Places the caret at the clicked column. A click on the right half of a
+      # Places the caret at the pressed column. A press on the right half of a
       # wide glyph lands *after* it, as in any editor.
       # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
 
       def repaint: () -> void
 
@@ -7608,12 +8084,12 @@ module Tuile
       # "clear what I typed".
       # 
       # _@param_ `key`
-      def handle_text_input_key: (String key) -> bool
+      def handle_text_input_key?: (String key) -> bool
 
       # Keeps the paste's **first line** and drops the rest, then trims what's
       # left to what {#max_text_length} still allows:
       # 
-      #   f.handle_paste("name\nstreet\ncity")   # => true
+      #   f.handle_paste("name\nstreet\ncity")
       #   f.text                                 # => "name"
       # 
       # Overshooting the cap trims rather than rejects, which is what typing the
@@ -7623,11 +8099,11 @@ module Tuile
       # _@param_ `text`
       def preprocess_paste: (String text) -> String
 
-      def on_text_mutated: () -> void
+      def handle_text_mutated: () -> void
 
-      def on_caret_mutated: () -> void
+      def handle_caret_mutated: () -> void
 
-      def on_width_changed: () -> void
+      def handle_width_changed: () -> void
 
       # What the field paints in place of {#text}: one display character per
       # {#text} character, in order. `column_at` measures `display_text[0, i]` as
@@ -7804,6 +8280,19 @@ module Tuile
     # the field (or pressing ENTER) reddens what did not parse, and the next
     # edit clears it again.
     # 
+    # == The value notice waits for the same gesture
+    # A prefix of a time can also parse *cleanly*: typing `13:45` passes
+    # through `13:4`, a perfectly good four minutes past one. So
+    # {HasValue#on_value_change} does not fire per keystroke, but when the user
+    # leaves the field or presses ENTER — and a form recalculating from it
+    # never sees those intermediate readings.
+    # 
+    # {#value} does *not* wait: it is a live parse of the buffer at every
+    # moment, so a save gate reached without leaving the field reads the time
+    # on screen. Nor does a change nobody had to type — a {#value=}, a
+    # {#set_to}, an arrow-key step, a {#clear} and a reparse under a new
+    # {#step} all fire as they happen.
+    # 
     # == Implementation details
     # - **The buffer is the single source of truth.** {#value} is a parse of it,
     #   recomputed on read — so {#step=} and a {Screen#locale=} can change the
@@ -7927,13 +8416,18 @@ module Tuile
       # 
       # _@return_ — `true` for the two page keys, else whatever `super`
       # returns.
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # Rewrites a buffer that parses in the primary format, leaving one that
       # does not exactly as the user typed it — and settles the field either
       # way, so input it could not parse starts painting the well.
       def commit: () -> void
 
+      # `false`: a prefix of a time can parse cleanly (`13:4` for `13:45`), so
+      # the notice settles onto the commit gestures, exactly as the ink does.
+      # The class docs carry the case.
+      def notify_on_edit?: () -> bool
+
       # Every prefix of a time is bad input, so the well is latched to the
       # commit gestures instead of painted per keystroke: `1`, `13`, `13:` on
       # the way to `13:45` never redden, and a time the field cannot parse
@@ -7943,9 +8437,9 @@ module Tuile
 
       # An edit is the user having another go, so the well goes quiet again
       # until the next commit gesture.
-      def on_editor_change: () -> void
+      def handle_editor_change: () -> void
 
-      def on_locale_changed: () -> void
+      def handle_locale_changed: () -> void
 
       # Re-derives the hint (which was *pushed* into the editor, so a repaint
       # alone would keep the old one) and rewrites a buffer that still parses —
@@ -8128,7 +8622,7 @@ module Tuile
       #   def bad_input_settled? = @settled   # set on commit, cleared on an edit
       # 
       # It gates the **ink only**: {#bad_input?} is a pull, and a save gate
-      # asking at a click must get the answer settled or not (`DECISIONS.md`
+      # asking at a click must get the answer settled or not (`design/decisions.md`
       # `D_bad_input`).
       def bad_input_settled?: () -> bool
 
@@ -8253,7 +8747,7 @@ module Tuile
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # _@return_ — the current content component.
       attr_accessor content: Component?
@@ -8370,7 +8864,7 @@ module Tuile
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # _@return_ — the presented items.
       def items: () -> ::Array[untyped]
@@ -8393,7 +8887,7 @@ module Tuile
       # neither of us wants bubbles on to an ancestor.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # Selects the item on row `index`; an index outside {#items} is ignored —
       # {List::Cursor::None}'s `-1` would otherwise select the *last* item.
@@ -8447,7 +8941,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -8482,9 +8976,10 @@ module Tuile
 
       # The composed {List}: an app may *tune* it — its scrollbar, its cursor,
       # `show_cursor_when_inactive` — but never replace it, since this group's
-      # renderer and selection are wired into this one. Those knobs are {List}
-      # concepts rather than group concepts, which is why they are reached here
-      # instead of forwarded (`DECISIONS.md` `D_wrapping_field`).
+      # renderer and selection are wired into this one (`design/decisions.md`
+      # `D_has_content`). Those knobs are {List} concepts rather than group
+      # concepts, which is why they are reached here instead of forwarded
+      # (`D_wrapping_field`).
       attr_reader list: List
 
       # _@return_ — item -> row label (a `String`, {StyledString}, or
@@ -8518,20 +9013,20 @@ module Tuile
     # (floor {MIN_CAP_WIDTH}) and {HEIGHT_FRACTION} tall, and **grows but never
     # shrinks** while it lives; a long message wraps to {MAX_ROWS_PER_MESSAGE}
     # rows and is then ellipsized, and entries past the height cap wait unpainted.
-    # `DECISIONS.md` `D_notification` has why each of those is what it is.
+    # `design/decisions.md` `D_notification` has why each of those is what it is.
     # 
     # Three things it deliberately doesn't do:
     # 
     # - **Take focus, or receive keys.** An {Overlay} sits off the
-    #   key-dispatch scope ({ScreenPane#handle_key}), so no key arrives here at
-    #   all. A left click *on the box* dismisses ({#handle_mouse}); an app
+    #   key-dispatch scope ({ScreenPane#handle_key?}), so no key arrives here at
+    #   all. A left click *on the box* dismisses ({#handle_mouse_down?}); an app
     #   wanting a key registers a global shortcut and calls {Overlay#close}. A
     #   click *elsewhere* does not — this is the one overlay with
     #   {Overlay#close_on_outside_click?} false, since a toast is timed and an
     #   unrelated click is not about it.
     # - **Follow a theme flip.** A `Theme::Ref` `color:` is resolved once, when
     #   the message is added — a toast lives seconds, so there is no
-    #   {Component#on_theme_changed} rebuild.
+    #   {Component#handle_theme_changed} rebuild.
     # - **Take a size.** An {Overlay} has no declared box; the messages decide
     #   this one's, in {#reposition}.
     class Notification < Tuile::Component::Overlay
@@ -8577,20 +9072,21 @@ module Tuile
       # from the width.
       def reposition: () -> void
 
-      # A left click dismisses the whole box, every message with it. Other buttons
-      # are consumed and inert — including the scroll wheel, which would otherwise
-      # nuke the box on a stray spin.
-      # 
-      # Deliberately *replaces* rather than augments: neither `super` nor
-      # {HasContent#handle_mouse} may run, since both end at a
-      # `screen.focused = …` inside this subtree (see {Overlay#focusable?}).
+      # A left press dismisses the whole box, every message with it. Every other
+      # press is claimed and inert, so nothing beneath the toast acts on it.
       # 
       # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      def handle_mouse_down?: (Mouse::DownEvent event) -> bool
+
+      # Claimed and inert: a stray wheel spin over the toast must neither nuke it
+      # nor reach whatever it covers.
+      # 
+      # _@param_ `_event`
+      def handle_mouse_scroll?: (Mouse::ScrollEvent _event) -> bool
 
-      def on_attached: () -> void
+      def handle_attached: () -> void
 
-      def on_detached: () -> void
+      def handle_detached: () -> void
 
       # Retires the oldest message, closing the box when it was the last. Runs on
       # the event-loop thread, from the ticker.
@@ -8599,7 +9095,7 @@ module Tuile
       # Syncs the retirement clock from the invariant "something to retire, and on
       # screen" — the sole writer of `@ticker`. Four sites change whether it is
       # wanted (append, a retirement that empties the queue, {#close}, detach),
-      # which is the 2×2 a start-in-{#on_attached} / cancel-in-{#on_detached} pair
+      # which is the 2×2 a start-in-{#handle_attached} / cancel-in-{#handle_detached} pair
       # gets half wrong. The early return is also what keeps an append from
       # *restarting* the clock and extending the oldest message's life.
       def sync_ticker: () -> void
@@ -8646,6 +9142,19 @@ module Tuile
       # 
       # _@param_ `rows`
       def join_rows: (::Array[StyledString] rows) -> StyledString
+
+      # The message rows, minus the wheel — the one thing a plain
+      # {Component::TextView} would add here. On a short terminal the queued
+      # messages are taller than the box, and the box is unfocusable, so
+      # scrolling them would be a capability the keyboard cannot reach
+      # (`D_mouse`); they are meant to *wait* until the ticker retires the ones
+      # above.
+      class View < Tuile::Component::TextView
+        # _@param_ `_event`
+        # 
+        # _@return_ — true — claimed on the box's behalf, and inert.
+        def handle_mouse_scroll?: (Mouse::ScrollEvent _event) -> bool
+      end
     end
 
     # A one-row progress bar: a run of `█` growing left to right across {#rect},
@@ -8684,7 +9193,7 @@ module Tuile
     # The `█`/`░` pair is the same one {VerticalScrollBar} uses — East-Asian
     # Ambiguous and Neutral respectively, so under an ambiguous-as-wide terminal
     # the rendered length would vary with the fill level. Shipped anyway, per
-    # `DECISIONS.md` `D_ambiguous_width`: a bar that rhymes with the scrollbar
+    # `design/decisions.md` `D_ambiguous_width`: a bar that rhymes with the scrollbar
     # beats a third convention, and if that bet is ever reversed both swap
     # together.
     class ProgressBar < Component
@@ -8730,9 +9239,9 @@ module Tuile
       # _@param_ `flag` — coerced; truthiness decides.
       def indeterminate=: (bool flag) -> void
 
-      def on_attached: () -> void
+      def handle_attached: () -> void
 
-      def on_detached: () -> void
+      def handle_detached: () -> void
 
       # Paints the bar on the first row of {#rect} and blanks the rest.
       # 
@@ -8811,7 +9320,7 @@ module Tuile
     # 
     # == Implementation details
     # An includer overrides {#bad_input_message} and nothing else. Two rules
-    # bind that override, and `DECISIONS.md` `D_bad_input` has the why:
+    # bind that override, and `design/decisions.md` `D_bad_input` has the why:
     # 
     # - **Empty input is not bad input.** Return `nil` for an empty buffer even
     #   though it parses to nothing, or every blank *optional* field blocks a
@@ -8859,7 +9368,7 @@ module Tuile
       #   def bad_input_settled? = @settled   # set on commit, cleared on an edit
       # 
       # It gates the **ink only**: {#bad_input?} is a pull, and a save gate
-      # asking at a click must get the answer settled or not (`DECISIONS.md`
+      # asking at a click must get the answer settled or not (`design/decisions.md`
       # `D_bad_input`).
       def bad_input_settled?: () -> bool
 
@@ -8966,7 +9475,7 @@ module Tuile
       #   def bad_input_settled? = @settled   # set on commit, cleared on an edit
       # 
       # It gates the **ink only**: {#bad_input?} is a pull, and a save gate
-      # asking at a click must get the answer settled or not (`DECISIONS.md`
+      # asking at a click must get the answer settled or not (`design/decisions.md`
       # `D_bad_input`).
       def bad_input_settled?: () -> bool
 
@@ -9132,7 +9641,7 @@ module Tuile
       # 
       # _@param_ `rows` — how many rows there are to show — the content count, not the height; more than fits turns the scrollbar on. `0` collapses the dropdown to an empty rect (drivers close instead).
       # 
-      # _@param_ `width` — the panel's width in columns, clamped to the screen. **Required, with no default:** `anchor.width` is the *parent's* width and would be meaningless here, so the caller measures (see `DECISIONS.md` `D_select` on why the width policy stays with the driver).
+      # _@param_ `width` — the panel's width in columns, clamped to the screen. **Required, with no default:** `anchor.width` is the *parent's* width and would be meaningless here, so the caller measures (see `design/decisions.md` `D_select` on why the width policy stays with the driver).
       # 
       # _@param_ `max_rows` — rows shown before the list scrolls.
       def anchor_beside: (
@@ -9234,18 +9743,33 @@ module Tuile
     end
 
     # A {Window} that lists options identified by single keyboard keys, asks
-    # the user to pick one, and fires a callback with the picked key.
+    # the user to pick one, and fires a callback with the picked key. Each row
+    # is `"<key> <caption>"`:
+    # 
+    #   PickerWindow.open("Sort by", [%w[n name], %w[s size]]) { sort_by(_1) }
+    # 
+    #   ┌Sort by───────┐
+    #   │n name        │
+    #   │s size        │
+    #   └──────────────┘
     # 
     # Usable tiled (just add to a {Layout} and read picks via the block) or
     # as a popup via {.open}, which wraps it in a {Popup} that closes itself
     # after a pick. ESC / `q` close without firing the callback.
+    # 
+    # Captions paint in the terminal's own foreground. To color them, hand in
+    # {StyledString} captions — the picker styles nothing itself, so an app's
+    # own token applies per option:
+    # 
+    #   PickerWindow.open("File", [["o", StyledString.plain("Open")],
+    #                              ["d", theme.fg(:danger, "Delete")]]) { … }
     class PickerWindow < Tuile::Component::Window
       MAX_ITEMS: Integer
 
       # _@param_ `caption` — the window caption.
       # 
-      # _@param_ `options` — pairs of keyboard key and option caption. No Rainbow formatting must be used.
-      def initialize: (String caption, ::Array[[String, String]] options) ?{ (String key) -> void } -> void
+      # _@param_ `options` — pairs of keyboard key and option caption. A caption goes through {StyledString.parse}, so a plain String, an ANSI-coded one (what {Theme#fg} returns) and a {StyledString} are all accepted.
+      def initialize: (String caption, ::Array[[String, StyledString]] options) ?{ (String key) -> void } -> void
 
       # Handles an option-key press. Reached by bubbling: the inner {List}
       # (the focused component) sees the key first and handles cursor/Enter
@@ -9253,7 +9777,7 @@ module Tuile
       # option's `key` picks that option.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # Opens a picker as a popup. Picking an option fires `block`, then
       # closes the popup; ESC / `q` close without firing `block`.
@@ -9263,7 +9787,7 @@ module Tuile
       # _@param_ `options`
       # 
       # _@return_ — the wrapping popup.
-      def self.open: (String caption, ::Array[[String, String]] options) ?{ (String key) -> void } -> Popup
+      def self.open: (String caption, ::Array[[String, StyledString]] options) ?{ (String key) -> void } -> Popup
 
       # _@param_ `key`
       def select_option: (String key) -> void
@@ -9277,13 +9801,15 @@ module Tuile
       # @!attribute [r] key
       #   @return [String] the keyboard key that picks this option.
       # @!attribute [r] caption
-      #   @return [String] the option caption.
+      #   @return [StyledString] the option caption, coerced from whatever the
+      #     constructor was handed.
       class Option
         # _@return_ — the keyboard key that picks this option.
         attr_reader key: String
 
-        # _@return_ — the option caption.
-        attr_reader caption: String
+        # _@return_ — the option caption, coerced from whatever the
+        # constructor was handed.
+        attr_reader caption: StyledString
       end
     end
 
@@ -9350,7 +9876,7 @@ module Tuile
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # _@return_ — the presented items.
       def items: () -> ::Array[untyped]
@@ -9377,7 +9903,7 @@ module Tuile
       # neither of us wants bubbles on to an ancestor.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # Flips membership of the item on row `index`; an index outside {#items} is
       # ignored — {List::Cursor::None}'s `-1` would otherwise toggle the *last*
@@ -9430,7 +9956,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -9465,9 +9991,10 @@ module Tuile
 
       # The composed {List}: an app may *tune* it — its scrollbar, its cursor,
       # `show_cursor_when_inactive` — but never replace it, since this group's
-      # renderer and selection are wired into this one. Those knobs are {List}
-      # concepts rather than group concepts, which is why they are reached here
-      # instead of forwarded (`DECISIONS.md` `D_wrapping_field`).
+      # renderer and selection are wired into this one (`design/decisions.md`
+      # `D_has_content`). Those knobs are {List} concepts rather than group
+      # concepts, which is why they are reached here instead of forwarded
+      # (`D_wrapping_field`).
       attr_reader list: List
 
       # _@return_ — item -> row label (a `String`, {StyledString}, or
@@ -9517,7 +10044,7 @@ module Tuile
     # There is deliberately no content slot: the body is prose ({#message=}
     # takes a component for the rare rich body, but the dialog then cannot
     # measure it). A dialog collecting *input* is not a confirm dialog — build a
-    # `Popup.new(content: your_layout)`. See `DECISIONS.md` `D_confirm_window`
+    # `Popup.new(content: your_layout)`. See `design/decisions.md` `D_confirm_window`
     # for the API rationale.
     class ConfirmWindow < Tuile::Component::Window
       BODY_SCROLL_KEYS: ::Array[String]
@@ -9584,8 +10111,10 @@ module Tuile
       def measured_size: (?Size reference) -> Size
 
       # Focus lands on the first button rather than cascading into the message
-      # body, which sits before the button row in the tree.
-      def on_focus: () -> void
+      # body, which sits before the button row in the tree. `super` is reached
+      # only when there is no button to take it: {HasContent#handle_focus} *is*
+      # the cascade this override exists to skip.
+      def handle_focus: () -> void
 
       # Handles the dialog-wide keys: Left/Right move between the buttons,
       # {BODY_SCROLL_KEYS} are hand-fed to the message body, and a mnemonic
@@ -9596,7 +10125,7 @@ module Tuile
       # _@param_ `key`
       # 
       # _@return_ — true if the key was handled.
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # Opens an acknowledgement dialog: a message and one button, whose press
       # is the dismissal. The button exists for discoverability — ESC and `q`
@@ -9751,7 +10280,7 @@ module Tuile
     # nothing — where red *text* is invisible on the empty field that is the
     # required-field case, and invisible again on content carrying colors of its
     # own. It takes two tokens rather than one because a focused invalid field
-    # still has to look focused (`DECISIONS.md` `D_has_validation`).
+    # still has to look focused (`design/decisions.md` `D_has_validation`).
     # 
     # The well reaches the whole widget with nothing forwarding it: a composed
     # field's inner face is marked {Component::BG_INHERIT} and a group's {List}
@@ -9774,7 +10303,7 @@ module Tuile
     # 
     # Unlike `bad_input?`, this fact is *discrete* — asserted at a click or a
     # binder pass, not recomputed per keystroke — which is why it carries a
-    # change notice where `bad_input?` deliberately doesn't (`DECISIONS.md`
+    # change notice where `bad_input?` deliberately doesn't (`design/decisions.md`
     # `D_bad_input`, `D_has_validation`).
     module HasValidation
       # _@return_ — why the field is invalid, or `nil` when it
@@ -9864,6 +10393,217 @@ module Tuile
       attr_accessor revealed: (bool | Object)
     end
 
+    # A one-row field pairing a {DateField} and a {TimeField} behind a single
+    # `DateTime`. Give it a single-row {#rect}, 16 columns or wider:
+    # 
+    #   [2026-09-14] [13:45]
+    #               ↑ the blank column is {Layout::Box#spacing}, not a component
+    # 
+    #   f = Component::DateTimeField.new
+    #   f.on_value_change = ->(dt) { puts dt.inspect }   # DateTime or nil, per commit
+    #   f.value = DateTime.new(2026, 9, 14, 13, 45)      # "2026-09-14" / "13:45"
+    #   f.clear                                          # empties both halves
+    # 
+    # Neither half is labelled: each paints the hint derived from its own format
+    # (`yyyy-mm-dd`, `hh:mm`), which names it while it is empty — the moment
+    # naming matters. The *caption* ("Starts at") belongs to the layout around
+    # the field, as it does for every field (`design/decisions.md`
+    # `D_caption_ownership`).
+    # 
+    # == Tune the halves; don't replace them
+    # They are exposed read-only, so everything they configure is reached
+    # directly rather than forwarded through a second set of names:
+    # 
+    #   f.date_field.formats = "%d.%m.%Y"   # ambiguous if it were `f.formats=`
+    #   f.date_field.calendar_start = Date::ITALY
+    #   f.time_field.step = 900             # Up/Down walk a quarter hour
+    # 
+    # Two of their knobs are **claimed** by this field and must not be
+    # reassigned: each half's {HasValue#on_value_change} (that is how the
+    # composite hears them) and each half's {Component#bg_color} (see the well
+    # rule below).
+    # 
+    # == The value is a `DateTime` at +00:00
+    # Both halves feed it with no adapter, and the offset is a placeholder
+    # rather than a zone — {TimeField}'s epoch cost, taken the same way: a value
+    # that is visibly wrong where an instant was meant beats one that is subtly
+    # wrong. Combine it with a zone at your own boundary (`f.value&.to_time`).
+    # 
+    # Lenient in, strict out, so an input carrying more than the halves can hold
+    # does not round-trip:
+    # 
+    #   f.value = Time.now      # takes today's date and the wall clock
+    #   f.value == DateTime.now # => false — the zone went, and the seconds with it
+    # 
+    # == Three states, and only one of them is this field's own fault
+    # {HasValue#value} is non-nil **iff both halves parse**, so a half going bad
+    # nils the whole value ({HasBadInput}: a field holds bad input *or* a value,
+    # never both). Who reddens follows from whether the fault is attributable:
+    # 
+    #   date half     time half   value       bad_input?                       red
+    #   2026-09-14    13:45       DateTime    no                               nobody
+    #   (empty)       (empty)     nil         no — empty is not bad input      nobody
+    #   2026-99-99    13:45       nil         "not a valid date"               the date half
+    #   2026-09-14    (empty)     nil         "needs both a date and a time"   this field
+    # 
+    # A half's bad input is the half's to paint, on its own latch, and this
+    # field paints nothing. Half-filled is nobody else's, so this field reddens
+    # whole — but **only while it is not active**: it judges you when you leave
+    # and goes quiet when you come back to fix it. A validator's verdict
+    # ({HasValidation#error_message=}) is by definition not attributable either,
+    # and reddens whole with no latch at all.
+    # 
+    # The one cost: **ENTER does not redden this field**, where it reddens a
+    # half. A save gate on ENTER over a date with no time still reads
+    # {HasBadInput#bad_input?} true and gets the message; only the ink waits for
+    # the blur.
+    # 
+    # == Implementation details
+    # - **The halves keep their own wells, and this field's ink is *synced* onto
+    #   them.** `error_bg_color` sits at the top of the background chain, so a
+    #   child answering {Component#default_bg_color} — every field does — never
+    #   inherits an ancestor's error level, so marking only this field would
+    #   leave the halves untouched and reach no cell at all. So the halves are
+    #   marked {Component::BG_INHERIT} exactly while this field inks, and `nil`
+    #   otherwise. A guilty half's *own* error well still beats the mark, which
+    #   is what keeps the ink rule free of arithmetic.
+    # - **The spacing column is nobody's surface** — {Component#clear_inside_extent}
+    #   blanks it in the ambient background, so the two wells read as two fields
+    #   rather than one long one and each half keeps its own focus highlight.
+    # - **A half announces from its own `value=` and its Up/Down step** — the
+    #   other half of {AbstractWrappingField#notify_on_edit?}'s contract — so
+    #   writing a value into both halves would announce a half-assembled
+    #   `DateTime`. Suppressed while applying, and announced once from this
+    #   field's own diff.
+    # - **Nothing else is wired.** Focus forwards through {Layout#handle_focus},
+    #   the mouse routes down through {Mouse::Router}, each half commits
+    #   on its own blur (Tab between them canonicalizes the date and leaves this
+    #   field active), and ENTER commits inside the half and keeps bubbling to
+    #   the scope's default button.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class DateTimeField < Tuile::Component::Layout::Horizontal
+      include Tuile::Component::HasValue
+      include Tuile::Component::HasBadInput
+      HALF_FILLED_MESSAGE: String
+      CIVIL_PARTS: ::Array[Symbol]
+      DATE_WEIGHT: Integer
+      TIME_WEIGHT: Integer
+      DEFAULT_PLACEMENT: ::Hash[Symbol, Object]
+      ALIGNMENTS: ::Array[Symbol]
+
+      def initialize: () -> void
+
+      # _@return_ — the two halves assembled, on the calendar
+      # {DateField#calendar_start} parsed the date in; `nil` unless both parse.
+      def value: () -> DateTime?
+
+      # Writes the date into one half and the time of day into the other, firing
+      # {HasValue#on_value_change} once if the value actually changed.
+      # 
+      # _@param_ `new_value` — anything carrying both a civil date and a time of day; `nil` empties both halves.
+      def value=: ((DateTime | Time)? new_value) -> void
+
+      # `nil`, not a pair of nils: a field with no parseable date *and* time is
+      # empty.
+      def empty_value: () -> void
+
+      # Empties the *input* of both halves, not just the value — either may be
+      # holding glyphs no parse could use ({HasBadInput}).
+      def clear: () -> void
+
+      # The guilty half's own report, the date's first when both are bad; else
+      # the one fault no half can wear, a half-filled pair.
+      def bad_input_message: () -> String?
+
+      # Sets the verdict and syncs the halves' wells onto it.
+      # 
+      # _@param_ `new_message`
+      def error_message=: ((String | StyledString)? new_message) -> void
+
+      # Syncs the halves' wells on both focus edges — this field inks its
+      # half-filled fault only once you have left it.
+      # 
+      # _@param_ `flag`
+      def active=: (bool flag) -> void
+
+      # _@return_ — the full width, one row — so a taller rect gets the
+      # ambient background rather than this field's well ({Component#extent}).
+      def extent: () -> Size
+
+      # The ink rule in the class doc, as an expression.
+      # 
+      # No latch ivar, deliberately: every input here is a fact something
+      # announces, which is what lets the well sync have a complete call list. A
+      # half's `bad_input?` moves with every keystroke and announces nothing at
+      # all by design, so a latch of this field's own could not follow it.
+      def bad_input_settled?: () -> bool
+
+      # _@return_ — whether a half is holding input its own value cannot
+      # represent, and so wears the error itself.
+      def attributable?: () -> bool
+
+      # One idempotent sync over one condition, this field the sole writer of
+      # its halves' {Component#bg_color} — the shape a hook-owned resource takes.
+      # Called from the three places {HasValidation#error_ink?} can change: a
+      # verdict, a focus edge, and a half's announcement. Leave one out and this
+      # field stops inking while its halves stay marked, i.e. both halves flat
+      # with their wells gone.
+      def sync_half_wells: () -> void
+
+      def handle_half_change: () -> void
+
+      # Runs `block` with the halves' notices suppressed, so a value written
+      # into both is announced once rather than half-assembled.
+      def applying: () -> void
+
+      def fire_if_changed: () -> void
+
+      # _@return_ — true iff the field is holding input its value cannot
+      # represent.
+      def bad_input?: () -> bool
+
+      # Widens {HasValidation#error_ink?}: bad input paints the invalid well
+      # too, with no verdict written — once {#bad_input_settled?} says the
+      # report may be shown.
+      def error_ink?: () -> bool
+
+      # _@return_ — why the field is invalid, or `nil` when it
+      # is not; `nil` until something sets it.
+      def error_message: () -> StyledString?
+
+      # The invalid well, picked up by everything this component paints —
+      # including the inner face of a composed field and the {List} of a group,
+      # neither of which forwards anything: both declare no background of their
+      # own, so the ordinary chain walks up to this (overrides
+      # {Component#error_bg_color}).
+      def error_bg_color: () -> Color?
+
+      # Adds `error_message=…` to {Component#inspect}, omitted while valid — so
+      # a {Testing.get} failure dump says which field is already flagged.
+      def inspect_details: () -> ::Array[String]
+
+      # Empty of *value*: a field whose parse is partial reports `true` while the
+      # user is looking at glyphs it could not use, so ask
+      # {HasBadInput#bad_input?} first.
+      # 
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Input fields are focusable by default (overrides {Component#focusable?});
+      # a read-only display field could override back to `false`. Only
+      # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
+      # composing wrappers, so it stays per-class (`design/decisions.md`
+      # `D_integer_field`).
+      def focusable?: () -> bool
+
+      # _@return_ — the left half; tune it, never replace it.
+      attr_reader date_field: DateField
+
+      # _@return_ — the right half; tune it, never replace it.
+      attr_reader time_field: TimeField
+    end
+
     # The hint a field paints in its own cells while it holds nothing — a format
     # the user could not otherwise guess:
     # 
@@ -9883,7 +10623,7 @@ module Tuile
     # Include it in a field whose *input shape* is unguessable from an empty
     # well. Not in {Select}, the near miss: a blank face plus `▾` already reads
     # as "nothing picked", so an absent enum *value* needs no hint the way an
-    # unguessable input *format* does (`DECISIONS.md` `D_select`).
+    # unguessable input *format* does (`design/decisions.md` `D_select`).
     # 
     # == Implementation details
     # The ink is {Theme#placeholder_color}, calibrated to be *barely* visible —
@@ -10008,7 +10748,7 @@ module Tuile
       #   def bad_input_settled? = @settled   # set on commit, cleared on an edit
       # 
       # It gates the **ink only**: {#bad_input?} is a pull, and a save gate
-      # asking at a click must get the answer settled or not (`DECISIONS.md`
+      # asking at a click must get the answer settled or not (`design/decisions.md`
       # `D_bad_input`).
       def bad_input_settled?: () -> bool
 
@@ -10075,7 +10815,7 @@ module Tuile
     #   f.text  = "e\u{0301}x"   # a decomposed e-acute then "x": 3 chars, 2 glyphs
     #   f.caret = 1              # into the middle of the e-acute …
     #   f.caret                  # => 2, its end — where the caret already drew
-    #   f.handle_key(Keys::BACKSPACE)
+    #   f.handle_key?(Keys::BACKSPACE)
     #   f.text                   # => "x": the whole glyph went, not its accent
     # 
     # Insertion stays character-native, so `String#insert` merges a typed
@@ -10085,11 +10825,11 @@ module Tuile
     # Subclasses implement the layout-specific pieces ({#cursor_position},
     # {#repaint}) and add their own keys (HOME/END, ENTER, UP/DOWN,
     # printable insertion) by overriding the protected
-    # {#handle_text_input_key} hook — `super` falls through to the common
+    # {#handle_text_input_key?} hook — `super` falls through to the common
     # navigation handling.
     # 
     # == Customizing a field is subclassing it, and there are two seams
-    # To change what **keys** do, override {#handle_text_input_key}; to
+    # To change what **keys** do, override {#handle_text_input_key?}; to
     # constrain what the buffer may **hold**, override {#insert_text}, which
     # every insertion runs through — typed, pasted, or the ENTER newline:
     # 
@@ -10097,7 +10837,7 @@ module Tuile
     #     protected
     # 
     #     # ENTER submits instead of falling through to the parent.
-    #     def handle_text_input_key(key)
+    #     def handle_text_input_key?(key)
     #       return super unless key == Keys::ENTER
     # 
     #       submit(text)
@@ -10127,7 +10867,7 @@ module Tuile
     #   which insertion does *not* pass through.
     # - {#preprocess_paste} — sanitizer for {#handle_paste}, run before the
     #   clipboard reaches {#insert_text} ({TextField} keeps its first line).
-    # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
+    # - {#handle_text_mutated} / {#handle_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
     class AbstractStringField < Component
@@ -10149,23 +10889,20 @@ module Tuile
 
       def tab_stop?: () -> bool
 
-      # Handles a key, by delegating to the {#handle_text_input_key} hook a
-      # subclass overrides. Dispatch ({ScreenPane#handle_key}) only routes keys
+      # Handles a key, by delegating to the {#handle_text_input_key?} hook a
+      # subclass overrides. Dispatch ({ScreenPane#handle_key?}) only routes keys
       # here when this input is on the focus chain, so there is no {#active?}
       # gate.
       # 
       # _@param_ `key`
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # Inserts pasted text at the caret as **one** mutation, so {#on_change}
       # fires once for the whole paste rather than once per character.
       # {#preprocess_paste} filters it first.
       # 
       # _@param_ `text`
-      # 
-      # _@return_ — always true — a field consumes every paste: an empty
-      # one, and one its {#insert_text} rejects wholesale.
-      def handle_paste: (String text) -> bool
+      def handle_paste: (String text) -> void
 
       # Input filter for {#handle_paste}, the paste-side counterpart of
       # {#preprocess_text}. Strips the C0 control characters a text buffer
@@ -10241,14 +10978,14 @@ module Tuile
       # Hook called after {#text} has been mutated, before invalidation /
       # {#on_change}. Default no-op. Subclasses use this to invalidate caches
       # ({TextArea}'s wrap cache) and update derived state.
-      def on_text_mutated: () -> void
+      def handle_text_mutated: () -> void
 
       # Hook called after {#caret} has been mutated, before invalidation.
       # Default no-op. Subclasses use this to keep the caret visible
       # ({TextArea}'s vertical scroll).
-      def on_caret_mutated: () -> void
+      def handle_caret_mutated: () -> void
 
-      # Dispatch hook for {#handle_key}. Handles ESC and the editing keys that
+      # Dispatch hook for {#handle_key?}. Handles ESC and the editing keys that
       # have identical semantics in single-line and multi-line inputs:
       # LEFT/RIGHT arrows (one grapheme cluster per press, so a press always
       # moves), CTRL+LEFT/CTRL+RIGHT for word jumps, and CTRL+W, which deletes
@@ -10260,7 +10997,7 @@ module Tuile
       # _@param_ `key`
       # 
       # _@return_ — true if the key was handled.
-      def handle_text_input_key: (String key) -> bool
+      def handle_text_input_key?: (String key) -> bool
 
       # Removes the whole grapheme cluster before the caret — one press, one
       # glyph, whatever it is built from (a ZWJ emoji family and a three-jamo
@@ -10328,7 +11065,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -10444,6 +11181,12 @@ module Tuile
     # default button still sees it; only an {#on_enter} of this field's own
     # consumes it, which is {TextField#on_enter}'s existing contract.
     # 
+    # == When the value notice fires
+    # Per edit by default. A field whose grammar is not prefix-closed sets
+    # {#notify_on_edit?} to `false` and lets the notice settle onto those same
+    # two gestures, so a form is never handed a half-typed date that happens to
+    # parse ({DateField}, {TimeField}).
+    # 
     # == Implementation details
     # - **{HasValue#value} and {#value=} raise until overridden.** The inherited
     #   pair stores into `@value` and never touches the editor, so a subclass
@@ -10454,7 +11197,7 @@ module Tuile
     # - **The editor's `on_change` and `on_enter` slots are claimed** — for that
     #   guard, and to commit before an app's ENTER handler runs. A slot cannot
     #   be shared, so a subclass reacting to buffer edits overrides
-    #   {#on_editor_change} (every edit), {#value=} or {#commit} rather than
+    #   {#handle_editor_change} (every edit), {#value=} or {#commit} rather than
     #   reassigning either.
     # - **Not for a field whose editor is a *filter*.** This base assumes the
     #   buffer is a rendering of the value, so an edit may change the value.
@@ -10500,7 +11243,7 @@ module Tuile
       # 
       # _@return_ — whatever `super` returns — committing never consumes
       # the key.
-      def handle_key: (String key) -> bool
+      def handle_key?: (String key) -> bool
 
       # _@return_ — the editor's caret — the hardware cursor is
       # delegated to it.
@@ -10513,7 +11256,7 @@ module Tuile
       # _@param_ `flag`
       def active=: (bool flag) -> void
 
-      def on_focus: () -> void
+      def handle_focus: () -> void
 
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
@@ -10523,13 +11266,27 @@ module Tuile
       # field rewrites its buffer from.
       def commit: () -> void
 
+      # Whether an edit of the buffer fires {HasValue#on_value_change} as it
+      # happens. `true` here, which is right wherever every buffer state is a
+      # value the user might mean: an {IntegerField} passing through `4` on the
+      # way to `42` really does hold 4 for that keystroke. A field whose
+      # grammar is **not prefix-closed** answers `false` and lets the notice
+      # settle onto the commit gestures instead ({DateField}, `D_date_field`).
+      # 
+      # Only the *push* settles: {HasValue#value} stays a live parse of the
+      # buffer either way. And overriding this is half the job — {#commit} is
+      # covered here, but the field must fire from its own `value=` too, or a
+      # programmatic write and an Up/Down step go unannounced until the next
+      # commit.
+      def notify_on_edit?: () -> bool
+
       # Called whenever the editor's buffer changes, however the characters
       # arrived — a typed key, a paste, or a {#value=} of this field's own. It
       # is named for the *editor*, not for the user, because those last two are
       # not input. No-op by default; override it to drop state that describes
       # the *previous* buffer, as a field latching whether its input has settled
       # must ({HasBadInput}).
-      def on_editor_change: () -> void
+      def handle_editor_change: () -> void
 
       # Places the editor across the whole rect; override to reserve cells for a
       # face of your own.
@@ -10542,6 +11299,11 @@ module Tuile
       # widget) and {Component#bg_color} set here reaches the cells it paints.
       def default_bg_color: () -> Color
 
+      # Every commit gesture runs through here, so a field holding its notice
+      # ({#notify_on_edit?}) announces from one place rather than three; the
+      # diff guard makes the call free for a field that fired on the way in.
+      def commit_and_notify: () -> void
+
       # Re-emits {HasValue#on_value_change}, but only when {#value} differs from
       # the last one fired — so a buffer edit that leaves the value alone
       # (`"7"`→`"07"`) stays silent.
@@ -10564,7 +11326,7 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       def focusable?: () -> bool
 
@@ -10781,7 +11543,7 @@ module Tuile
     def running?: () -> bool
 
     # _@return_ — true if this thread is the one running {#run_loop}.
-    def on_loop_thread?: () -> bool
+    def in_loop_thread?: () -> bool
 
     # Stops ongoing {#run_loop}. The stop may not be immediate: {#run_loop} may
     # process a bunch of events before terminating.
@@ -10815,7 +11577,7 @@ module Tuile
     # 
     # {Screen#event_loop} routes it to {Component#handle_paste} down the focus
     # chain. It never enters the key ladder: no Tab traversal, no global
-    # shortcut, no {Component#handle_key}.
+    # shortcut, no {Component#handle_key?}.
     # 
     # @!attribute [r] text
     #   @return [String] the pasted text, `\n`-normalized by
@@ -11012,13 +11774,83 @@ module Tuile
     #   Screen.instance.background_color = Color.rgb(30, 30, 46)
     # 
     # Takes the same path a real reply does — a changed color fires
-    # {Component#on_theme_changed} across the tree and invalidates it.
+    # {Component#handle_theme_changed} across the tree and invalidates it.
     # There is no such writer on {Screen}: the value is a report from the
     # terminal, not a setting.
     # 
     # _@param_ `color`
     def background_color=: (Color color) -> void
 
+    # Plays a whole click at a screen cell — the press, then the release that
+    # ends its grab:
+    # 
+    #   screen.click(save_button.rect.left, save_button.rect.top)
+    # 
+    # Routed exactly as the terminal's own report would be ({Mouse::Router}), so
+    # it focuses, dismisses popups and bubbles.
+    # 
+    # _@param_ `x` — 0-based column.
+    # 
+    # _@param_ `y` — 0-based row.
+    # 
+    # _@param_ `button` — `:left`, `:middle` or `:right`.
+    def click: (Integer x, Integer y, ?button: Symbol) -> void
+
+    # Half a {#click}, for a spec about the grab — what is claimed, what the
+    # drag does, what the release lands on.
+    # 
+    # _@param_ `x` — 0-based column.
+    # 
+    # _@param_ `y` — 0-based row.
+    # 
+    # _@param_ `button` — `:left`, `:middle` or `:right`.
+    def press: (Integer x, Integer y, ?button: Symbol) -> void
+
+    # The other half of {#press}.
+    # 
+    # _@param_ `x` — 0-based column.
+    # 
+    # _@param_ `y` — 0-based row.
+    def release: (Integer x, Integer y) -> void
+
+    # One wheel notch over a cell.
+    # 
+    # _@param_ `direction` — `:up`, `:down`, `:left` or `:right`.
+    # 
+    # _@param_ `x` — 0-based column.
+    # 
+    # _@param_ `y` — 0-based row.
+    def scroll: (Symbol direction, Integer x, Integer y) -> void
+
+    # Moves the pointer, firing the enter/exit hooks the new position implies —
+    # or, while a press is grabbed, one {Component#handle_mouse_drag}.
+    # 
+    # _@param_ `x` — 0-based column.
+    # 
+    # _@param_ `y` — 0-based row.
+    # 
+    # _@param_ `button` — the button held while moving, if any.
+    def move: (Integer x, Integer y, ?button: Symbol?) -> void
+
+    # Plays a whole drag: the press at the first point, one move per point
+    # after it, and the release at the last.
+    # 
+    #   screen.drag([2, 1], [3, 2], [4, 3])         # three reports, a diagonal
+    #   screen.drag(canvas.rect.top_left, [9, 9])   # the coarsest drag there is
+    # 
+    # **Reports only the points given**, as the wire does: at ~84 reports a
+    # second (`R_mouse_reporting`) a quick drag genuinely skips cells, so
+    # interpolating them would let a spec assert a continuity no terminal
+    # delivers. A one-point drag is a {#click} — use that.
+    # 
+    # _@param_ `points` — two or more positions, as {Point}s or `[x, y]` pairs.
+    # 
+    # _@param_ `button` — `:left`, `:middle` or `:right`.
+    def drag: (*::Array[(Point | [Integer, Integer])] points, ?button: Symbol) -> void
+
+    # _@param_ `point`
+    def coerce_point: ((Point | [Integer, Integer]) point) -> Point
+
     # No terminal probing in tests: skip {TerminalBackground.detect}
     # (which would write an OSC 11 query to the test runner's TTY and
     # steal its input) and pin the deterministic default. The color is nil
@@ -11046,59 +11878,6 @@ module Tuile
     attr_reader prints: ::Array[String]
   end
 
-  # A mouse event.
-  # 
-  # @!attribute [r] button
-  #   @return [Symbol, nil] one of `:left`, `:middle`, `:right`, `:scroll_up`,
-  #     `:scroll_down`, `:scroll_left`, `:scroll_right`; `nil` if not known.
-  # @!attribute [r] x
-  #   @return [Integer] x coordinate, 0-based.
-  # @!attribute [r] y
-  #   @return [Integer] y coordinate, 0-based.
-  class MouseEvent
-    # _@return_ — the event's position.
-    def point: () -> Point
-
-    # Checks whether given key is a mouse event key. Returns true on the X10
-    # `\e[M` prefix regardless of length — {.parse} is the place that
-    # validates the full 6-byte shape and raises on malformed input.
-    # 
-    # _@param_ `key` — key read via {Keys.getkey}
-    # 
-    # _@return_ — true if it is a mouse event
-    def self.mouse_event?: (String key) -> bool
-
-    # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y).
-    # 
-    # Raises {Tuile::Error} when `key` starts with the mouse prefix but is
-    # not exactly 6 bytes long. Both shorter and longer inputs are bugs in
-    # the upstream key-reader: a shorter prefix means the tail was lost on
-    # the way in, and a longer one means we over-consumed into the next
-    # escape sequence. We refuse to silently truncate either case because
-    # the trailing `\e` of an over-read corrupts the *next* getkey, and the
-    # corruption then surfaces as garbled keystrokes in focused inputs
-    # rather than as a parser failure pointing at the actual cause.
-    # 
-    # _@param_ `key` — key read via {Keys.getkey}
-    # 
-    # _@return_ — `nil` if `key` is not a mouse event
-    def self.parse: (String key) -> MouseEvent?
-
-    def self.start_tracking: () -> String
-
-    def self.stop_tracking: () -> String
-
-    # _@return_ — one of `:left`, `:middle`, `:right`, `:scroll_up`,
-    # `:scroll_down`, `:scroll_left`, `:scroll_right`; `nil` if not known.
-    attr_reader button: Symbol?
-
-    # _@return_ — x coordinate, 0-based.
-    attr_reader x: Integer
-
-    # _@return_ — y coordinate, 0-based.
-    attr_reader y: Integer
-  end
-
   # The structural root of the {Screen}'s component tree.
   # 
   # {Screen} is a singleton runtime owner (event loop, lock, terminal IO,
@@ -11106,7 +11885,7 @@ module Tuile
   # {#content} and the {#popups} stack. Putting them under a single Component
   # parent gives focus traversal a real root, makes {Component#attached?} a
   # one-liner, and lets popup-focus repair fall out of the standard
-  # {Component#on_child_removed} hook.
+  # {Component#handle_child_removed} hook.
   # 
   # The pane owns no chrome of its own — no status bar, no reserved row.
   # {#content} gets the full pane rect, and an app that wants a status line
@@ -11146,7 +11925,7 @@ module Tuile
     # _@param_ `window`
     def remove_popup: (Component window) -> void
 
-    # Unmounts everything: each child is detached — firing {Component#on_detached}
+    # Unmounts everything: each child is detached — firing {Component#handle_detached}
     # down its subtree — and every slot is emptied. Terminal; the pane isn't
     # reusable afterwards, and {Screen#close} is its only caller.
     # 
@@ -11185,7 +11964,7 @@ module Tuile
     def repaint: () -> void
 
     # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
-    # the first component whose `handle_key` returns true wins.
+    # the first component whose `handle_key?` returns true wins.
     # 
     # Bubbling stops at the *scope* root: the topmost *modal* popup when one is
     # open, else the tiled {#content}. Focus that is nil or sits outside the
@@ -11203,36 +11982,34 @@ module Tuile
     # _@param_ `key`
     # 
     # _@return_ — true if the key was handled.
-    def handle_key: (String key) -> bool
+    def handle_key?: (String key) -> bool
 
     # Delivers pasted text to {Screen#focused} — and to nobody else.
     # 
-    # Scoped exactly like {#handle_key} (focus that is nil or sits outside the
+    # Scoped exactly like {#handle_key?} (focus that is nil or sits outside the
     # modal scope receives nothing, which is what keeps a popup modal) but
     # **not bubbled**: an ancestor is never offered a paste its descendant
     # declined, and unhandled text is dropped. Why keys bubble and pastes
     # don't: `D_bracketed_paste`.
     # 
     # _@param_ `text`
-    # 
-    # _@return_ — true if the focused component consumed it.
-    def handle_paste: (String text) -> bool
+    def handle_paste: (String text) -> void
 
-    # Mouse events check popups in reverse stacking order (topmost first), and
-    # fall through to content only when no popup is hit *and* no modal popup is
-    # open. This preserves modal click-blocking — an open modal eats clicks
-    # even outside its rect — while a non-modal overlay blocks nothing: clicks
-    # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
-    # content beneath.
+    # Where {Mouse::Router} starts its walk for a pointer at `point`: the
+    # topmost popup containing it, else {#content} — unless a modal popup is
+    # open, which eats the event even outside its rect. A non-modal overlay
+    # blocks nothing: a point outside it reaches the content beneath.
     # 
-    # A left click also *dismisses* the open popups it landed outside of that
-    # asked for it ({Component::Overlay#close_on_outside_click?}). That is a
-    # second thing happening on a click, but not a second dispatch: the click is
-    # still delivered exactly once, down one chain, and a dismissed popup is
+    # _@param_ `point`
+    def mouse_root_at: (Point point) -> Component?
+
+    # Runs the press delivery in the block, then *dismisses* the open popups a
+    # left press landed outside of that asked for it
+    # ({Component::Overlay#close_on_outside_click?}). A dismissed popup is
     # closed rather than told.
     # 
     # "Outside" is measured against the {Component::Overlay#owner} chain, not
-    # against one rect and not against stacking order: the popup the click hit
+    # against one rect and not against stacking order: the popup the press hit
     # is kept, and so is every popup that one *belongs to*, transitively. That
     # is what stops a dialog being dismissed by a click on a dropdown its own
     # field opened, and a menu cascade being dismissed by a click on one of its
@@ -11242,10 +12019,10 @@ module Tuile
     # 
     # Two halves of the ordering are load-bearing, and both are specced:
     # 
-    # - **Snapshot before routing.** A popup the delivered click *opens* must
+    # - **Snapshot before the block.** A popup the delivered press *opens* must
     #   not be in the set (it would immediately dismiss itself — every
     #   {Component::Select} would be unopenable by mouse).
-    # - **Close after routing.** A widget toggling its own overlay from a click
+    # - **Close after the block.** A widget toggling its own overlay from a press
     #   on its face closes it during delivery, and {Component::Popup#close} is
     #   idempotent, so the dismissal no-ops. Close *first* and the widget sees
     #   a shut overlay and reopens it — a Select's dropdown could then never be
@@ -11254,10 +12031,12 @@ module Tuile
     # The snapshot is a fresh array for a third reason: a handler may close
     # further popups, and `@popups` must not be mutated mid-iteration.
     # 
-    # _@param_ `event`
-    def handle_mouse: (MouseEvent event) -> void
+    # _@param_ `point`
+    # 
+    # _@param_ `left` — whether the press was the left button; no other button dismisses.
+    def dismissing_popups_outside: (Point point, left: bool) -> void
 
-    # Focus repair when a child detaches. Default {Component#on_child_removed}
+    # Focus repair when a child detaches. Default {Component#handle_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
     # Instead, route focus to the first interactable widget in the now-topmost
     # modal popup; falling back to the focus snapshotted when this popup was opened
@@ -11270,7 +12049,7 @@ module Tuile
     # `q`/ESC still has somewhere to dispatch from.
     # 
     # _@param_ `child`
-    def on_child_removed: (Component child) -> void
+    def handle_child_removed: (Component child) -> void
 
     # The overlays a click counts as landing *inside*: the one it hit, plus
     # every overlay that one belongs to, up the {Component::Overlay#owner}
@@ -11283,6 +12062,11 @@ module Tuile
     # _@param_ `hit` — the overlay the click landed in, if any.
     def kept_by: (Component::Overlay? hit) -> ::Array[Component::Overlay]
 
+    # _@param_ `point`
+    # 
+    # _@return_ — the topmost popup containing `point`.
+    def popup_at: (Point point) -> Component::Overlay?
+
     # _@param_ `component`
     # 
     # _@return_ — `component` itself when it is an
@@ -11814,7 +12598,7 @@ module Tuile
     def running?: () -> bool
 
     # _@return_ — always true.
-    def on_loop_thread?: () -> bool
+    def in_loop_thread?: () -> bool
 
     def stop: () -> void
 
@@ -12034,7 +12818,7 @@ module Tuile
   # track is a solid column carrying no information, so `row_count <= height`
   # paints track at every row — while {#handle_height} / {#handle_start} /
   # {#handle_end} still report the covering handle. Ink only: the caller's bar
-  # keeps its column and its content width (`DECISIONS.md` `D_scrollbar_ink`).
+  # keeps its column and its content width (`design/decisions.md` `D_scrollbar_ink`).
   class VerticalScrollBar
     # One cell, exactly: a painter concatenates the glyph onto a row already
     # padded to fill the rest of its rect, so a two-column one pushes every