tuile 0.9.0 → 0.11.0

data/sig/tuile.rbs

@@ -226,16 +226,10 @@ module Tuile
   # Color.coerce(nil)            # nil → nil
   # ```
   # 
-  # Which entry point to use is a deliberate policy split. High-traffic
-  # call sites ({StyledString} and friends) stay lenient and {.coerce} raw
-  # forms — you don't want factory ceremony on every styled span.
-  # Declaration sites ({Theme}, defined once per app) are strict and take
-  # only {Color} instances, where `Color.palette(130)` documents itself in
-  # a way the bare `130` (palette index? RGB channel?) does not.
-  # 
-  # {#to_ansi} renders a full SGR escape (`"\e[31m"`); {#sgr_codes} returns the
-  # raw numeric codes so callers (notably {StyledString}) can combine them with
-  # other SGR attributes in a single sequence.
+  # {.coerce} is the lenient entry point (raw forms plus `nil`); the named
+  # factories and constants are the strict, self-documenting path for
+  # declaration sites — see the book's chapter 6 for why theme colors take
+  # {Color} instances only.
   class Color
     COLOR_SYMBOLS: ::Array[Symbol]
     PALETTE_NAMES: ::Hash[Symbol, Integer]
@@ -321,67 +315,52 @@ module Tuile
     attr_reader y: Integer
   end
 
-  # A set of semantic colors the built-in components read when painting.
-  # The current theme lives at {Screen#theme}; components must look it up
-  # at paint time (inside `repaint`) rather than caching values, so that
-  # assigning {Screen#theme=} restyles everything via a single
-  # invalidate-everything pass.
+  # A set of semantic colors the built-in components read when painting. The
+  # current theme lives at {Screen#theme}; components must look it up at paint
+  # time (inside `repaint`) rather than caching values, so a {Screen#theme=}
+  # restyles everything via one invalidate-everything pass. Book ch6 is the
+  # concept in full (why accents-only, dark/light, live OS flips).
   # 
-  # The primary API is the rendering helpers — {#active_bg},
-  # {#active_border}, {#input_bg}, {#hint} — which 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},
+  # {#hint} — 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"
   # 
-  # The helpers pass content through verbatim, so input may carry other
-  # escape sequences (e.g. {Component::Window} feeds its border string,
-  # cursor moves included). For span-aware styling — applying a token to a
-  # {StyledString} while preserving per-span colors — use the `*_color`
-  # readers instead (e.g. {Component::List} highlights its cursor row via
-  # `with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome text →
-  # helper; structured text → `*_color` reader + {StyledString}.
+  # Content passes through verbatim (so it may carry other escapes). For
+  # span-aware styling — a token applied to a {StyledString} without flattening
+  # its per-span colors — use the `*_color` readers instead
+  # (`with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome → helper;
+  # structured text → `*_color` reader + {StyledString}.
   # 
-  # Two built-in themes are provided: {DARK} (the default; the colors Tuile
-  # has always used) and {LIGHT} (counterparts legible on light terminal
-  # backgrounds). A custom theme is one `with` away:
+  # Two built-in themes ship: {DARK} (default) and {LIGHT}. A custom one is one
+  # `with` away, and every token must be a {Color} instance — not the lenient
+  # {Color.coerce} forms, since a theme is declared once so the verbosity
+  # self-documents:
   # 
   #   screen.theme = Theme::DARK.with(active_border_color: Color::CYAN)
   # 
-  # Tokens deliberately cover only the *accents* Tuile paints. Everything
-  # else inherits the terminal's own default foreground/background, which
-  # already matches the user's terminal theme perfectly — that's why there
-  # is no global `bg`/`fg` token.
-  # 
-  # Every token is a {Color} — and must be passed as one. Unlike the
-  # lenient {Color.coerce} call sites elsewhere in the framework, a theme
-  # is declared once per app, so it takes only {Color} instances: at a
-  # declaration site `Color.palette(130)` documents itself in a way the
-  # bare `130` does not (palette index? RGB channel?) — and the named
-  # palette constants (`Color::DARK_ORANGE3` *is* 130; see
-  # {Color::PALETTE_NAMES}) go one step further.
-  # 
   # ## App-specific tokens
   # 
-  # Beyond the built-in tokens, an app can carry its own colors in
-  # {#custom} — a frozen `Hash{Symbol => Color}` member. Look them up with
-  # {#[]} (fail-fast: a typo raises `KeyError`) and render with the
-  # generic {#fg} / {#bg} helpers:
+  # An app carries its own colors in {#custom} (frozen `Hash{Symbol => Color}`).
+  # Look them up with {#[]} (fail-fast on typos) and render with the generic
+  # {#fg} / {#bg} helpers; subclass for semantic readers (`Data#with` keeps the
+  # subclass). Pair dark/light variants in a {ThemeDef} for {Screen#theme_def=}.
   # 
   #   theme = Theme::DARK.with(custom: { accent: Color::DARK_ORANGE })
   #   theme[:accent]              # => Color, e.g. for StyledString#with_fg
   #   theme.fg(:accent, "NEW")    # => "\e[38;5;208mNEW\e[0m"
   # 
-  # Apps wanting semantic readers can subclass — `Data#with` preserves the
-  # subclass, so an `AppTheme` stays an `AppTheme` through `with`:
-  # 
   #   class AppTheme < Tuile::Theme
   #     def accent(text) = fg(:accent, text)
   #   end
   # 
-  # Pair the dark and light variants in a {ThemeDef} and hand it to
-  # {Screen#theme_def=} so OS appearance flips pick the right one.
+  # 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
+  # own. Baked content colors ({Component::Label} text and friends) can't:
+  # they live in a frozen {StyledString} and still need the hook.
   # 
   # @!attribute [r] active_bg_color
   #   Background highlight of the component the user is interacting with:
@@ -410,6 +389,7 @@ module Tuile
   #   the tokens.
   #   @return [Hash{Symbol => Color}]
   class Theme
+    CHROME_TOKENS: ::Array[Symbol]
     DARK: Theme
     LIGHT: Theme
 
@@ -435,6 +415,18 @@ module Tuile
     # _@param_ `token`
     def []: (Symbol token) -> Color
 
+    # _@param_ `name` — a token name.
+    # 
+    # _@return_ — true iff `name` is a built-in chrome token (see
+    # {CHROME_TOKENS}) rather than a {#custom} one.
+    def self.chrome_token?: (Symbol name) -> bool
+
+    # Builds a {Ref} — a live theme reference for a late-resolved color slot
+    # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
+    # 
+    # _@param_ `name` — a built-in chrome token ({#input_bg_color} etc.) or a {#custom} token name.
+    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.
     # 
@@ -526,6 +518,34 @@ module Tuile
     # lookups (it fail-fasts on typos); read this directly to enumerate
     # the tokens.
     attr_reader custom: ::Hash[Symbol, Color]
+
+    # 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:
+    # 
+    #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
+    #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
+    # 
+    # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
+    # one; a chrome name takes precedence on the (pathological) collision. This
+    # does *not* add a global bg/fg token — it only lets a slot point at a
+    # color the theme *already* carries, resolved the same way framework chrome
+    # already resolves it.
+    # 
+    # Distinct from {Color.coerce}'s symbol support, which names one of the 16
+    # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
+    # re-reads it each paint.
+    # 
+    # Immutable.
+    class Ref
+      # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
+      # chrome reader when `name` is one ({Theme.chrome_token?}), else a
+      # {#custom} token.
+      # 
+      # _@param_ `theme`
+      def resolve: (Theme theme) -> Color
+    end
   end
 
   # An in-memory grid of styled cells mirroring the terminal screen. This is
@@ -548,17 +568,10 @@ module Tuile
   # size. There is deliberately no per-frame whole-buffer clear or copy;
   # un-touched cells retain the previous frame's value.
   # 
-  # The bookkeeping avoids hashing and full-grid scans: a dirty flag **on each
-  # cell** (O(1) set, no `Set` bucket math, no separate array), a per-row
-  # boolean so {#flush} scans only the rows that changed, and one global flag
-  # so {#dirty?} and the "nothing changed" early-out are O(1). {#flush} clears
-  # every flag it consumes.
-  # 
-  # Cells are **mutable and pre-allocated**: the grid builds its {Cell}s once
+  # Cells are **mutable and pre-allocated** — the grid builds its {Cell}s once
   # (at construction and {#resize}) and rewrites them in place, so a normal
-  # paint allocates nothing per cell. That is why {Cell} is a plain mutable
-  # object rather than a frozen value type. The empty state of a cell is a
-  # space in the default style.
+  # paint allocates nothing per cell. That's why {Cell} is a plain mutable
+  # object, not a frozen value type.
   # 
   # ## Wide characters
   # 
@@ -567,19 +580,6 @@ module Tuile
   # nothing for, since the glyph itself advances the cursor two columns).
   # Overwriting either half of a wide glyph blanks the orphaned half, so the
   # grid never holds a dangling continuation or a headless one.
-  # 
-  # ## Future direction
-  # 
-  # Components paint through this drawing surface ({#set_line} / {#set_char})
-  # without knowing whether it is the one global buffer or a private one — that
-  # indirection is deliberate, so per-component back buffers plus a z-order
-  # compositor could drop in without touching component code. It is not worth
-  # doing yet: the diff already drops unchanged cells from the wire, and an
-  # occluded component that didn't change is never repainted at all, so a
-  # compositor would only save residual `repaint` CPU. It pays off in exactly
-  # one regime — high repeat-rate scroll (held arrow / mouse wheel) of a large
-  # component on a large screen, where re-rendering the content each repeat is
-  # the dominant cost.
   class Buffer
     DEFAULT_STYLE: StyledString::Style
     WIDTH_CACHE: ::Hash[String, Integer]
@@ -631,9 +631,8 @@ module Tuile
                   ) -> void
 
     # Writes a {StyledString} starting at `(x, y)`, advancing by each grapheme's
-    # display width and clipping at the right edge. The workhorse that replaces
-    # the old `screen.print(TTY::Cursor.move_to(x, y), styled.to_ansi)` per-row
-    # paint. Newlines in the string are not handled — pass one physical line.
+    # display width and clipping at the right edge. Newlines are not handled —
+    # pass one physical line.
     # 
     # _@param_ `x` — starting column.
     # 
@@ -793,21 +792,22 @@ module Tuile
                       StyledString::Style style
                     ) -> void
 
-    # If `(x, y)` holds the right half (continuation) of a wide glyph, blanks the
-    # orphaned left half at `x - 1`. Called before a write lands on `x`, so the
-    # wide glyph to the left isn't left headless.
+    # If `(x, y)` holds a continuation, blanks the head of the glyph it belongs to
+    # and every continuation up to — but not including — `x`. Called before a
+    # write lands on `x`, so the glyph reaching into `x` isn't left headless.
+    # Walks left rather than assuming the head sits at `x - 1`: a glyph may be
+    # wider than two columns, so its tail can run several cells.
     # 
     # _@param_ `x` — column
     # 
     # _@param_ `y` — row
     def blank_left_partner: (Integer x, Integer y) -> void
 
-    # If the cell just right of `(x, y)` is a continuation (the right half of a
-    # wide glyph whose origin is `(x, y)`), blanks it. Called before a write
-    # lands on `x`, so overwriting a wide origin doesn't strand its continuation.
-    # A continuation can only ever belong to the wide glyph immediately to its
-    # left, so the empty-grapheme test is exact — and cheaper than re-measuring
-    # the origin's width.
+    # Blanks the run of continuations immediately right of `(x, y)` — the tail of
+    # a glyph whose head is at or before `x`, and which the write landing on `x`
+    # is about to decapitate. A continuation always belongs to the nearest glyph
+    # on its left, so the empty-grapheme test is exact — and cheaper than
+    # re-measuring that glyph's width.
     # 
     # _@param_ `x` — column
     # 
@@ -866,26 +866,57 @@ module Tuile
     end
   end
 
-  # The TTY screen. There is exactly one screen per app.
+  # The process-singleton runtime: one {Screen} per app, reached through
+  # {Screen.instance}. It owns everything the UI needs to exist — the
+  # {#event_queue}, the UI lock, the invalidation set, the terminal IO, the
+  # back {#buffer}, the {#theme}/{#theme_def}, the {#focused} component, the
+  # global-shortcut registry, and the single {ScreenPane} under which *all*
+  # UI lives. Construct one with {Screen.new} (or {Screen.fake} in tests),
+  # tear it down with {Screen.close}.
+  # 
+  # ## The component tree
+  # 
+  # Everything on screen hangs off {#pane} (a {ScreenPane}): the tiled
+  # {#content} (set via {#content=}, filling the whole terminal and laying
+  # out its own children), the modal/overlay {#popups} stack (opened via
+  # {Component::Popup#open}, drawn on top of the content), and the bottom
+  # status bar. Popups are *not* sized from their content — each carries its
+  # own top-down {Component::Popup#size} — and they deliberately overdraw the
+  # content without clipping.
   # 
-  # A screen runs the event loop; call {#run_event_loop} to do that.
+  # ## Repaint model
   # 
-  # A screen holds the screen lock; any UI modifications must be called from
-  # the event queue.
+  # Components never draw to the terminal directly. They call
+  # {Component#invalidate} to mark themselves dirty, and when they do paint
+  # they write styled cells into {#buffer}. Once the event loop drains its
+  # queue, {#repaint} walks the invalidated set in z-order, has each
+  # component paint into the buffer, then flushes the buffer's *minimal diff*
+  # (only cells that changed) to the terminal in one synchronized-output
+  # batch — which is what keeps repaint flicker-free and coalesces many
+  # invalidations into a single frame per tick. See the book (ch. 2) for the
+  # why.
   # 
-  # All UI lives under a single {ScreenPane} owned by the screen. Set tiled
-  # content via {#content=}; the pane fills the entire terminal and is
-  # responsible for laying out its children.
+  # ## Thread-safety
   # 
-  # Modal popups are supported too, via {Component::Popup#open}. They
-  # auto-size to their wrapped content and are drawn centered over the
-  # tiled content.
+  # **UI-thread-confined**, where "the UI thread" changes hands once: it is the
+  # loop's thread while {#run_event_loop} is in progress, and the thread that
+  # *created* the screen whenever no loop is running ({#state} `:idle`). So an
+  # app builds its tree on its own thread, hands ownership to the loop, and
+  # gets it back for teardown — the loop needn't run on the creating thread.
+  # *All* UI mutations — {#content=}, {#focused=}, {#theme=},
+  # {Component#invalidate}, `rect=`, … — obey it via {#check_locked}.
   # 
-  # The drawing procedure is very simple: when a window needs repaint, it
-  # invalidates itself, but won't draw immediately. After the keyboard press
-  # event processing is done in the event loop, {#repaint} is called which
-  # then repaints all invalidated windows. This prevents repeated paintings.
+  # A worker marshals back with `screen.event_queue.submit { … }`, which runs
+  # the block only while a loop is draining the queue — outside `:running` it
+  # silently never fires. Terminal resize, key/mouse input and OS color-scheme
+  # flips arrive as events on that same queue.
+  # 
+  # The singleton slot survives subclassing (`FakeScreen < Screen`), so
+  # {FakeScreen} — which captures output in memory — is what
+  # {Screen.instance} returns under test.
   class Screen
+    EDITING_KEYS: ::Array[String]
+
     # rubocop:disable Style/ClassVars
     def initialize: () -> void
 
@@ -902,8 +933,19 @@ module Tuile
     # to {ScreenPane}). The array must not be modified!
     def popups: () -> ::Array[Component]
 
-    # Checks that the UI lock is held and the current code runs in the "UI
-    # thread".
+    # `:idle` covers *both* ends of the screen's life — before the first
+    # {#run_event_loop} and after it returns — and a screen may cycle
+    # `:idle` → `:running` → `:idle` repeatedly. `:closed` is terminal.
+    # 
+    # _@return_ — `:idle` (no event loop running), `:running` (a
+    # {#run_event_loop} is in progress) or `:closed` (after {#close}).
+    def state: () -> Symbol
+
+    # Raises unless the calling thread currently owns the UI (see the
+    # class-level threading contract).
+    # 
+    #   screen.check_locked   # from a worker: raises; wrap the work in
+    #                         # screen.event_queue.submit { ... } instead
     def check_locked: () -> void
 
     # Clears the TTY screen.
@@ -937,8 +979,13 @@ module Tuile
     # _@param_ `window`
     def add_popup: (Component::Popup window) -> void
 
-    # Runs event loop – waits for keys and sends them to active window. The
-    # function exits when the 'ESC' or 'q' key is pressed.
+    # Runs the event loop on the calling thread, taking over stdin (raw mode,
+    # 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).
     def run_event_loop: (?capture_mouse: bool) -> void
@@ -956,31 +1003,23 @@ module Tuile
     # _@return_ — true if focus moved.
     def focus_previous: () -> bool
 
-    # Registers an app-level keyboard shortcut. When `key` arrives, the block
-    # is invoked on the event-loop thread (so it may freely mutate UI) before
-    # the key reaches any component. Re-registering the same key replaces the
-    # previous binding; use {#unregister_global_shortcut} to remove one.
-    # 
-    # Only unprintable keys are accepted — control characters (Ctrl+letter,
-    # ESC, BACKSPACE, ENTER, …) and multi-character escape sequences (arrows,
-    # F-keys, …). Printable keys raise {ArgumentError}: they'd hijack typing
-    # into a {Component::TextField} and should be expressed as
-    # {Component#key_shortcut} instead, which the dispatcher suppresses while
-    # a text widget owns the hardware cursor. TAB and SHIFT_TAB are also
-    # rejected because {#handle_key} intercepts them for focus navigation
-    # before the global registry is consulted, so a binding on them would
-    # silently never fire.
-    # 
-    # Pass `hint:` to surface the shortcut in the status bar. It's a
-    # preformatted string the caller fully owns (so colors and the key label
-    # style stay consistent with whatever the host app uses elsewhere). The
-    # framework splices it in like any other status hint: in the tiled case,
-    # right after `q quit` and before the active window's own hint; while a
-    # popup is open, only hints from `over_popups: true` shortcuts are
-    # shown, and they're prepended before the popup's `q Close`.
-    # 
-    # Example — open a log popup with Ctrl+L from anywhere, even while a
-    # popup is already on screen:
+    # Registers an app-level keyboard shortcut: when `key` arrives, the block
+    # runs on the event-loop thread (free to mutate UI) before the key reaches
+    # any component. Re-registering a key replaces its binding.
+    # 
+    # This registry is the *only* keyboard mechanism above the component tree,
+    # and nothing suppresses it — so it accepts only keys no widget can need.
+    # Three groups raise at registration rather than misbehaving at runtime:
+    # 
+    # - **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
+    #   navigation before the registry is consulted, so a binding would never
+    #   fire.
+    # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
+    #   which every editable widget needs.
     # 
     #   screen.register_global_shortcut(Keys::CTRL_L,
     #                                   over_popups: true,
@@ -988,11 +1027,11 @@ module Tuile
     #     log_popup.open
     #   end
     # 
-    # _@param_ `key` — unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC}, {Keys::PAGE_UP}).
+    # _@param_ `key` — unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC}).
     # 
-    # _@param_ `over_popups` — when true, fires even while a modal popup is open (pre-empting the popup's own key handling). When false (default), the shortcut is suppressed while any popup is open and the popup gets the key instead.
+    # _@param_ `over_popups` — when true, fires even while a modal popup is open (pre-empting the popup); when false (default), suppressed while any popup is open so the popup gets the key.
     # 
-    # _@param_ `hint` — preformatted status-bar hint (e.g. `"^L #{screen.theme.hint("log")}"`). When nil (default) the shortcut is silent in the status bar. The colors are baked into the string, so a later {#theme=} does not restyle it — re-register if needed.
+    # _@param_ `hint` — preformatted status-bar hint; nil (default) is silent. Colors are baked in — re-register after a {#theme=} to recolor.
     def register_global_shortcut: (String key, ?over_popups: bool, ?hint: String?) -> void
 
     # Removes a shortcut previously installed by {#register_global_shortcut}.
@@ -1034,6 +1073,9 @@ module Tuile
     # return the same object.
     def self.fake: () -> FakeScreen
 
+    # 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.
     def close: () -> void
 
     def self.close: () -> void
@@ -1049,7 +1091,10 @@ module Tuile
     def print: (*String args) -> void
 
     # Repaints the screen; tries to be as effective as possible, by only
-    # considering invalidated windows.
+    # considering invalidated components and flushing just the changed cells
+    # of {#buffer}. Called once per event-loop tick (on {EventQueue::EmptyQueueEvent});
+    # components should {Component#invalidate} and let the loop coalesce rather
+    # than call this directly.
     def repaint: () -> void
 
     # Returns the absolute screen coordinates where the hardware cursor should
@@ -1097,9 +1142,10 @@ module Tuile
     # _@param_ `str`
     def emit: (String str) -> void
 
-    # Recalculates positions of all windows, and repaints the scene.
-    # Automatically called whenever terminal size changes. Call when the app
-    # starts. {#size} provides correct size of the terminal.
+    # Resizes {#buffer} and {#pane} to the current {#size}, invalidates the
+    # whole tree and repaints. Run whenever the terminal size changes (the
+    # {EventQueue::TTYSizeEvent} path) and once at startup via the first
+    # {#content=}.
     def layout: () -> void
 
     # A key has been pressed on the keyboard. Handle it, or forward to active
@@ -1107,17 +1153,15 @@ module Tuile
     # 
     # Dispatch order:
     #   1. Tab / Shift+Tab — reserved focus navigation, intercepted before
-    #      anything else so a focused {Component::TextField} (which would
-    #      otherwise swallow printable keys via cursor-owner suppression)
-    #      doesn't trap them.
+    #      anything else so a focused {Component::TextField} (which swallows
+    #      printable keys) can't trap them.
     #   2. App-level shortcuts from {#register_global_shortcut}. An entry
     #      registered with `over_popups: true` always fires; one with the
     #      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}, which captures a matching {#key_shortcut}
-    #      in the active scope, then delivers the key to {#focused} and bubbles
-    #      it up the focus chain.
+    #   3. {ScreenPane#handle_key} — delivery to {#focused}, bubbling up the
+    #      focus chain to the scope root.
     # 
     # _@param_ `key`
     # 
@@ -1203,16 +1247,12 @@ module Tuile
   end
 
   # A width/height ratio, each a float in `0.0..1.0` — the single relational
-  # sizing primitive in Tuile. It exists for exactly one job: sizing a
-  # {Component::Popup} against the screen. A popup has no siblings competing for
-  # space and no rectangle in a tiled layout, so "half the screen, centered" is
-  # the sensible default, and that wants a ratio rather than a hard-coded cell
-  # count that would be wrong on the next terminal size.
-  # 
-  # Tiled components are *not* sized this way: their parent computes explicit
-  # integer rects in its own `rect=` and hands them down. `Fraction` is
-  # deliberately scoped to {Component::Popup#size=} and is not a general layout
-  # primitive.
+  # sizing primitive in Tuile, scoped to one job: sizing a {Component::Popup}
+  # against the screen (a popup has no siblings competing for space, so "half
+  # the screen, centered" beats a hard-coded cell count that breaks on the next
+  # terminal size). It is deliberately *not* a general layout primitive — tiled
+  # components get explicit integer rects computed by their parent's `rect=`.
+  # See book ch3 for the layout model.
   # 
   # Resolve it against a reference {Size} (the screen) to get concrete integer
   # cells:
@@ -1253,56 +1293,35 @@ module Tuile
     # Focuses this component. Equivalent to `screen.focused = self`.
     def focus: () -> void
 
-    # Repaints the component.
-    # 
-    # The default does the bookkeeping that almost every component would
-    # otherwise have to remember: it clears the background and re-invalidates
-    # any direct children whose rects leave gaps in {#rect}. Concretely:
-    # 
-    # - Leaf (no children): always clears, so subclasses can paint their
-    #   content directly without an explicit `clear_background` call.
-    # - Container with children that fully tile {#rect}: skipped — the
-    #   children themselves will repaint and cover everything.
-    # - Container with gappy children (e.g. a form layout where widgets
-    #   don't tile): clears, then invalidates the children so they re-paint
-    #   on top of the cleared background. This is what makes mixed
-    #   field/button forms safe without each container learning a custom
-    #   damage-tracking pass.
-    # 
-    # Subclasses that paint their entire rect themselves (e.g. {Window}'s
-    # border draws over the area the default would clear; {Component::List}
-    # explicitly paints every row) may skip super and take full
-    # responsibility for {#rect}. Everything else should call super.
-    # 
-    # A component must not draw outside of {#rect}.
-    # 
-    # Only called when the component is attached.
+    # _@return_ — the background actually painted: this component's own
+    # {#bg_color} if set (a {Theme::Ref} resolved against the current theme),
+    # else the nearest ancestor's, else `nil` (terminal default). Resolved at
+    # paint time — never cached, so the subtree tracks both an ancestor's
+    # {#bg_color=} and a {Screen#theme=} on its next repaint.
+    def effective_bg_color: () -> Color?
+
+    # Repaints the component. The default does the bookkeeping most components
+    # need: it clears the background, and for a container whose children leave
+    # gaps in {#rect} it re-invalidates those children so they repaint over the
+    # cleared area (what makes mixed-width form layouts safe). A container whose
+    # children fully tile {#rect} is left alone — the children cover everything.
+    # 
+    # Call `super` from your own `repaint` to inherit this. Skip it only if you
+    # paint the whole {#rect} yourself ({Window}'s border, {Component::List}'s
+    # row-by-row paint). Never draw outside {#rect}. Only called when attached.
     def repaint: () -> void
 
-    # Called when a character is pressed on the keyboard. The default does
-    # nothing and reports the key as unhandled; input components
-    # ({Component::TextField}, {Component::List}, {Component::Button}, …)
-    # override it to act on keys they care about.
-    # 
-    # Dispatch is owned by {ScreenPane#handle_key}: a {#key_shortcut} match
-    # anywhere in the active scope is captured first (suppressed while a
-    # cursor-owner is mid-edit), then the key is delivered to {Screen#focused}
-    # and bubbles up its ancestor chain until some component handles it. A
-    # component therefore only ever receives keys when it is on the focus chain
-    # — or when app code hands it a key directly — so it acts on the key alone
-    # and must never gate on its own {#active?} state.
+    # Called when a key is pressed; override to act on keys you care about (the
+    # default reports every key unhandled). A component only receives keys while
+    # it's on the focus chain — or when app code hands it one directly — so act
+    # on the key alone and never gate on your own {#active?} state. See book ch5
+    # for how a keystroke is routed to reach here.
     # 
     # _@param_ `_key` — a key.
     # 
     # _@return_ — true if the key was handled, false if not.
     def handle_key: (String _key) -> bool
 
-    # _@param_ `key` — keyboard key to look up.
-    # 
-    # _@return_ — the component whose {#key_shortcut} matches `key`,
-    # or nil.
-    def find_shortcut_component: (String key) -> Component?
-
     # Handles mouse event. Default implementation focuses this component when
     # clicked (if {#focusable?}).
     # 
@@ -1318,16 +1337,11 @@ module Tuile
 
     # Whether this component is a valid focus target. `false` by default —
     # passive components like {Label} are decoration and don't accept focus.
-    # The flag gates click-to-focus ({#handle_mouse}) and the focus-cascade
-    # in container components ({HasContent#on_focus}, {Layout#on_focus}).
-    # Independent from {#active?}: every component carries the active flag, but
-    # only focusable ones can become a focus target that puts themselves and
-    # their ancestors on the active chain.
-    # 
-    # See also {#tab_stop?}: focusable controls _can_ receive focus (via click
-    # or programmatic assignment), but only tab stops participate in Tab /
-    # Shift+Tab cycling. Containers like {Window} and {Popup} are focusable
-    # (so a click on chrome lands focus) but are not tab stops.
+    # The flag gates click-to-focus and the container focus-cascade. Independent
+    # from {#active?}: every component carries the active flag, but only
+    # focusable ones can become a focus target that puts themselves and their
+    # ancestors on the active chain. Focusable is broader than {#tab_stop?} —
+    # a {Window} is focusable (a click on chrome lands focus) but not a tab stop.
     # 
     # _@return_ — true if this component can be focused.
     def focusable?: () -> bool
@@ -1348,20 +1362,23 @@ module Tuile
     # _@return_ — the root component of this component hierarchy.
     def root: () -> Component
 
-    # List of child components, defaults to an empty array.
-    # 
-    # _@return_ — child components. Must not be mutated! May be
-    # empty.
-    def children: () -> ::Array[Component]
-
     # Calls block for this component and for every descendant component.
     def on_tree: () ?{ (Component component) -> void } -> void
 
     # Called when the component receives focus.
     def on_focus: () -> void
 
-    # _@return_ — true if this component's tree is currently mounted on
-    # the {Screen}, i.e. its root is the {ScreenPane}.
+    # Whether this component's tree is mounted on a UI, {ScreenPane} being the
+    # root of every displayed tree.
+    # 
+    # A property of the parent chain alone — no {Screen} is consulted, so
+    # assembling a tree needs no screen in the process at all:
+    # 
+    #   layout = Component::Layout::Absolute.new
+    #   layout.add(label)      # legal with no Screen; neither is attached yet
+    #   screen.content = layout # now both are
+    # 
+    # _@return_ — true if {#root} is a {ScreenPane}.
     def attached?: () -> bool
 
     # Called by container components after `child` has been detached from
@@ -1387,6 +1404,86 @@ module Tuile
     # topmost popup. Empty by default; override to advertise shortcuts.
     def keyboard_hint: () -> String
 
+    # Adopts `child`: places it in {#children} and wires its parent pointer.
+    # 
+    #   add_child(@status_bar)                              # paints last
+    #   add_child(popup, at: @children.index(@status_bar))  # …just before it
+    # 
+    # _@param_ `child` — must not already have a parent.
+    # 
+    # _@param_ `at` — index to insert at; appends when nil.
+    def add_child: (Component child, ?at: Integer?) -> void
+
+    # Drops `child` and notifies {#on_child_removed}.
+    # 
+    # _@param_ `child`
+    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:
+    # 
+    #   detach_child(old)
+    #   @content = new
+    #   add_child(new, at: 0)
+    #   on_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.
+    # 
+    # _@param_ `child`
+    def detach_child: (Component child) -> void
+
+    # Called once this component's tree has been mounted on a {ScreenPane},
+    # 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
+    #     @ticker = screen.event_queue.tick_fps(10) { advance }
+    #   end
+    # 
+    #   def on_detached
+    #     @ticker&.cancel
+    #     @ticker = nil
+    #   end
+    # 
+    # `on_attached` starts what `on_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}.
+    # 
+    # {#invalidate} needs no guard: {#attached?} is already true here (and
+    # already false in {#on_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
+
+    # Mirror of {#on_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
+
+    # Walks self-then-children calling one lifecycle hook, delivering at most one
+    # call per component per transition however the hooks mutate the tree. Two
+    # guards, because a hook runs *before* its own children are visited:
+    # 
+    # - the **snapshot** covers a child a hook *adds* — it isn't in `kids`, and
+    #   fires exactly once through its own `parent=`;
+    # - the **state re-check** covers a child a hook *removes*. Matching on
+    #   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
+    #   component that is no longer attached would start a ticker nothing stops.
+    # 
+    # _@param_ `attached` — true to fire {#on_attached}, false for {#on_detached}.
+    def fire_lifecycle: (bool attached) -> void
+
     # Called whenever the component width changes. Does nothing by default.
     def on_width_changed: () -> void
 
@@ -1409,39 +1506,83 @@ module Tuile
     # Children with empty rects contribute zero, since they paint nothing.
     def children_tile_rect?: () -> bool
 
-    # Clears the background: prints spaces into all characters occupied by the
-    # component's rect.
-    def clear_background: () -> void
+    # Clears the background: fills every cell with a blank in the
+    # {#effective_bg_color} (the terminal default when none is inherited).
+    # 
+    # A component that paints part of its {#rect} itself passes just the part it
+    # *doesn't* — blanking a cell it is about to overwrite anyway makes that cell
+    # dirty, and {Buffer#flush} then re-emits it even though nothing visibly
+    # changed.
+    # 
+    # _@param_ `area` — the region to blank; defaults to the whole {#rect}.
+    def clear_background: (?Rect area) -> void
+
+    # {Buffer#set_line} wrapper that fills {#effective_bg_color} behind any span
+    # with no bg of its own (via {StyledString#under_bg}), so an inherited
+    # {#bg_color} shows through the content a component paints. A no-op layer
+    # when nothing is inherited. Self-painters (those skipping the {#repaint}
+    # auto-clear) paint through this instead of {Screen#buffer} directly.
+    # 
+    # _@param_ `x` — starting column.
+    # 
+    # _@param_ `y` — row.
+    # 
+    # _@param_ `styled`
+    def draw_line: (Integer x, Integer y, StyledString styled) -> void
+
+    # {#draw_line}'s single-grapheme counterpart: writes `grapheme` at `(x, y)`,
+    # filling {#effective_bg_color} when `style` carries no bg of its own.
+    # 
+    # _@param_ `x` — column.
+    # 
+    # _@param_ `y` — row.
+    # 
+    # _@param_ `grapheme` — one grapheme cluster.
+    # 
+    # _@param_ `style`
+    def draw_char: (
+                     Integer x,
+                     Integer y,
+                     String grapheme,
+                     ?StyledString::Style style
+                   ) -> void
 
     # _@return_ — the rectangle the component occupies on screen.
     attr_accessor rect: Rect
 
-    # A global keyboard shortcut. When pressed, will focus this component.
-    # 
-    # _@return_ — shortcut, `nil` by default.
-    attr_accessor key_shortcut: String?
+    # _@return_ — this component's own background — the
+    # value as set, so a {Theme::Ref} comes back unresolved; `nil` when unset,
+    # in which case it inherits from the parent (see {#effective_bg_color}),
+    # ultimately the terminal default. {#effective_bg_color} is the resolved
+    # {Color} to paint.
+    attr_accessor bg_color: (Color | Theme::Ref | Symbol | Integer | ::Array[Integer])?
 
     # _@return_ — the parent component or nil if the component has
     # no parent.
     attr_accessor parent: Component?
 
+    # Child components in paint order (siblings left to right, earlier ones
+    # painted under later ones), maintained by {#add_child} / {#remove_child}.
+    # 
+    # Not meant to be overridden: a container that computed this from its own
+    # slots could disagree with the parent pointers, and {#attached?} walks the
+    # chain while subtree walks use this list. Named slots are readers *over*
+    # the array (`Window#footer`), never a second copy of it.
+    # 
+    # _@return_ — child components. Must not be mutated by
+    # 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=}
-    # assignment and on OS appearance flips.
-    # 
-    # Built-in components read {Screen#theme} at paint time, so their accents
-    # restyle automatically; this hook exists for *content* whose colors the
-    # app baked in from the old theme — a {Label#text} / {List#lines} /
-    # {TextView#text} {StyledString} styled with `theme[:accent]` and the
-    # like. Only the app knows which of its colors were theme-derived (as
-    # opposed to inherent to the data, e.g. log-level colors), so it rebuilds
-    # them here, re-running the same code that rendered them initially.
-    # 
-    # Runs on the UI thread; {Screen#theme} already returns the new theme.
-    # Mutating content (`text=`, `lines=`, …) is safe — repaint coalesces per
-    # event-loop tick. Do not assign {Screen#theme=} from inside the hook.
-    # 
-    # Subclasses overriding this should call `super` so an assigned
+    # {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.
     attr_accessor on_theme_changed: Proc?
 
@@ -1449,11 +1590,9 @@ module Tuile
     # 
     # Items are modeled as {StyledString}s and painted directly into the
     # component's {#rect}. Lines wider than the viewport are ellipsized via
-    # {StyledString#ellipsize} (span styles are preserved across the cut —
-    # unlike the older ANSI-as-bytes truncation, color does *not* get
-    # dropped on the surviving characters). Vertical scrolling is supported
-    # via {#top_line}; the list can also automatically scroll to the bottom
-    # if {#auto_scroll} is enabled.
+    # {StyledString#ellipsize} with span styles preserved across the cut.
+    # Vertical scrolling is via {#top_line}; enable {#auto_scroll} to keep the
+    # bottom in view.
     # 
     # Cursor is supported; call {#cursor=} to change cursor behavior. The
     # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the
@@ -1543,7 +1682,10 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row of
       # {#rect} is painted below (with blank padding past the last item),
       # so the parent contract — "fully draw over your rect" — is met
-      # without an upfront wipe.
+      # without an upfront wipe. Rows go through {Component#draw_line}, so
+      # content *and* blank filler inherit {Component#effective_bg_color}
+      # (a {#bg_color} set here or on an ancestor); the cursor row's
+      # {Theme#active_bg_color} highlight composes on top of it.
       def repaint: () -> void
 
       # Rebuilds pre-padded lines when the wrap width changes. The wrap width
@@ -1860,7 +2002,8 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with pre-padded blanks past the last line), so
       # the "fully draw over your rect" contract is met without an upfront
-      # wipe.
+      # wipe. Rows go through {Component#draw_line}, so the padding and blank
+      # rows inherit {Component#effective_bg_color} when {#bg} is unset.
       def repaint: () -> void
 
       def on_width_changed: () -> void
@@ -1885,9 +2028,11 @@ module Tuile
       # {StyledString}.
       attr_accessor text: (StyledString | String)?
 
-      # _@return_ — background color applied uniformly across every
-      # painted row (including padding past the text). `nil` (default)
-      # leaves whatever bg the text's own styling carries.
+      # _@return_ — a local background laid over *every* span and the
+      # row padding (via {StyledString#with_bg}), overriding the text's own
+      # span bgs — stronger than the inherited {#bg_color}. `nil` (default)
+      # keeps each span's bg and lets the inherited {#effective_bg_color}
+      # fill the rest.
       attr_accessor bg: (Color | Symbol | Integer | ::Array[Integer])?
     end
 
@@ -1907,16 +2052,11 @@ module Tuile
     # 
     # Modal by default: it centers on the screen, grabs focus, eats keys, and
     # blocks clicks beneath it. Pass `modal: false` for a non-modal overlay
-    # that floats above the content (still painted on top) without taking focus
-    # or capturing input — the caller positions it (via {#rect=}) and drives it
-    # from app code. That is the building block for an autocomplete/slash-command
-    # list anchored to a {Component::TextField} or {Component::TextArea} caret:
-    # typing keeps focus (and the cursor) in the input, an
-    # {Component::TextInput#on_change} listener refills the list, and an
-    # {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
-    # Such a caller owns the list data, so it sizes the overlay itself
-    # (`overlay.size = Size.new(longest, [items.size, 8].min)`) — still
-    # caller-decides, top-down.
+    # that floats above the content without taking focus or capturing input —
+    # the caller positions it (via {#rect=}), sizes it, and drives it from app
+    # code. That's the building block for an autocomplete/slash-command list
+    # anchored to a text field's caret: typing keeps focus in the input while
+    # the caller refills and drives the overlay.
     # 
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -1929,10 +2069,11 @@ module Tuile
     # Bare content also works (a {Component::Label}, a {Component::List}…), in
     # which case the popup is borderless.
     # 
-    # `q` and ESC close the popup. Any nested {Component::TextField} that owns
-    # the hardware cursor swallows printable keys first via the standard
-    # cursor-owner suppression in {Component#handle_key}, so typing `q` into a
-    # text field doesn't dismiss the popup.
+    # `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
+    # nested {Component::TextField} doesn't dismiss the popup: the field
+    # consumes it first.
     class Popup < Component
       include Tuile::Component::HasContent
 
@@ -2016,8 +2157,6 @@ module Tuile
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
-      def children: () -> ::Array[Component]
-
       def on_focus: () -> void
 
       # _@return_ — the popup's declared size. See {#size=}.
@@ -2034,10 +2173,14 @@ module Tuile
     # {Component#handle_mouse}.
     # 
     # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
-    # show `[ caption ]` — that natural width is `caption.length + 4`.
+    # show `[ caption ]` — that natural width is `caption.display_width + 4`.
+    # A narrower {#rect} truncates the label with an ellipsis; a wider one leaves
+    # a tail that focuses but doesn't activate (see {#extent}).
     class Button < Component
-      # _@param_ `caption` — the button's label.
-      def initialize: (?String caption) -> void
+      include Tuile::Component::HasCaption
+
+      # _@param_ `caption` — the button's label, coerced the same way {HasCaption#caption=} coerces it.
+      def initialize: (?(String | StyledString)? caption) -> void
 
       def focusable?: () -> bool
 
@@ -2046,13 +2189,35 @@ module Tuile
       # _@param_ `key`
       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
+      # by geometry. Same rule as {Checkbox#extent}, which documents the two
+      # traps behind it.
+      def extent: () -> Rect
+
+      # Fires {#on_click} on a left click within {#extent}; `super` runs first, so
+      # a click anywhere in {#rect} still focuses.
+      # 
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
       def repaint: () -> void
 
-      # _@return_ — the button's label.
-      attr_accessor caption: String
+      # Read through *this* method, never `@caption` — the ivar stays nil until
+      # the first non-empty set ({#caption=} short-circuits when unchanged).
+      # 
+      # _@return_ — the caption; empty when never set.
+      def caption: () -> StyledString
+
+      # Sets the caption and invalidates the component. No-op when unchanged. A
+      # `String` is parsed via {StyledString.parse} (embedded ANSI is honored);
+      # a {StyledString} is used as-is; `nil` clears it.
+      # 
+      # _@param_ `new_caption`
+      def caption=: ((String | StyledString)? new_caption) -> void
 
       # Callback fired when the button is activated (Enter, Space, or
       # left-click). The callable receives no arguments.
@@ -2062,7 +2227,13 @@ module Tuile
     end
 
     # A layout doesn't paint anything by itself: its job is to position child
-    # components.
+    # components. Two families, both top-down (see book ch3):
+    # 
+    # - {Absolute} — you override {Component#rect=} and compute every child's
+    #   rectangle yourself. Total control, and the base for anything unusual.
+    # - {Box} / {Vertical} / {Horizontal} — you declare each child's extent as
+    #   a {Fixed}, {Percent} or {Expand} constraint and the layout does the
+    #   arithmetic. Sugar over the same `rect=` assignment, for the common case.
     # 
     # Children that fully tile the layout's rect repaint themselves and
     # cover everything; children that leave gaps (e.g. a form with widgets
@@ -2070,10 +2241,6 @@ module Tuile
     # the background is cleared and children are re-invalidated so they
     # paint over a clean surface.
     class Layout < Component
-      def initialize: () -> void
-
-      def children: () -> ::Array[Component]
-
       # Layouts are focusable containers — like {Window} and {Popup}, they
       # don't accept input themselves but they need to participate in the
       # {HasContent} focus cascade so a Popup wrapping a Layout wrapping a
@@ -2099,10 +2266,563 @@ module Tuile
 
       def on_focus: () -> void
 
+      # How much space a child gets along one axis of a {Box}: exactly {#cells},
+      # clamped to whatever is still unassigned.
+      # 
+      #   add(prompt, Fixed[4])                    # 4 rows in a Vertical
+      #   add(field, Fixed[1], cross: Fixed[30])   # 1 row, 30 columns wide
+      # 
+      # `Fixed[0]` hides the child — it gets an empty rect and paints nothing.
+      # 
+      # @!attribute [r] cells
+      #   @return [Integer] cell count along the axis.
+      class Fixed
+        # _@param_ `cells` — cell count along the axis; `>= 0`.
+        def initialize: (cells: Integer) -> void
+
+        # _@return_ — cell count along the axis.
+        attr_reader cells: Integer
+      end
+
+      # A percentage of the space *available* along a {Box}'s axis — measured
+      # after {Box#padding} and {Box#spacing} have come off, so two `Percent[50]`
+      # children fit exactly rather than overflowing by the gap between them.
+      # 
+      #   add(left, Percent[60])
+      #   add(right, Percent[40])
+      # 
+      # @!attribute [r] percent
+      #   @return [Numeric] percentage of the available extent, `0..100`.
+      class Percent
+        # _@param_ `percent` — percentage of the available extent, `0..100`.
+        def initialize: (percent: Numeric) -> void
+
+        # _@return_ — percentage of the available extent, `0..100`.
+        attr_reader percent: Numeric
+      end
+
+      # A share of whatever a {Box} has left once its {Fixed} and {Percent}
+      # children have taken theirs, split between the `Expand` children in
+      # proportion to their weights:
+      # 
+      #   add(header, Fixed[1])
+      #   add(body, Expand[2])    # gets twice…
+      #   add(side, Expand[1])    # …what this one gets
+      # 
+      # Main axis only — {Box#add} rejects one passed as `cross:`, where a child
+      # has no siblings to compete with and so nothing for a weight to mean.
+      # 
+      # @!attribute [r] weight
+      #   @return [Integer] relative share of the leftover space.
+      class Expand
+        # _@param_ `weight` — relative share; `>= 1`.
+        def initialize: (weight: Integer) -> void
+
+        # _@return_ — relative share of the leftover space.
+        attr_reader weight: Integer
+      end
+
+      # Per-edge padding for a {Box}, in cells:
+      # 
+      #   Insets[top: 1]                     # one blank row above the children
+      #   Insets[top: 1, left: 2, right: 2]  # unnamed edges default to 0
+      #   Insets.coerce(1)                   # uniform on all four edges
+      # 
+      # Keyword-only: AWT and JavaFX order these same four numbers differently,
+      # so a positional form would be a coin flip.
+      # 
+      # @!attribute [r] top
+      #   @return [Integer] cells inset from the top edge.
+      # @!attribute [r] right
+      #   @return [Integer] cells inset from the right edge.
+      # @!attribute [r] bottom
+      #   @return [Integer] cells inset from the bottom edge.
+      # @!attribute [r] left
+      #   @return [Integer] cells inset from the left edge.
+      class Insets
+        ZERO: Insets
+
+        # _@param_ `positional` — must be empty — see the class doc.
+        # 
+        # _@param_ `kwargs` — any of `top:`/`right:`/`bottom:`/`left:`.
+        def self.new: (*::Array[untyped] positional, **::Hash[Symbol, Integer] kwargs) -> Insets
+
+        # Needed because `Data`'s inherited `[]` never dispatches through a `new`
+        # override, so the guard above alone would miss `Insets[1, 2, 3, 4]`.
+        # 
+        # _@param_ `positional` — must be empty.
+        # 
+        # _@param_ `kwargs` — any of `top:`/`right:`/`bottom:`/`left:`.
+        def self.[]: (*::Array[untyped] positional, **::Hash[Symbol, Integer] kwargs) -> Insets
+
+        # _@param_ `value` — an Integer becomes a uniform inset.
+        def self.coerce: ((Insets | Integer) value) -> Insets
+
+        # _@param_ `top` — cells inset from the top edge; `>= 0`.
+        # 
+        # _@param_ `right` — cells inset from the right edge; `>= 0`.
+        # 
+        # _@param_ `bottom` — cells inset from the bottom edge; `>= 0`.
+        # 
+        # _@param_ `left` — cells inset from the left edge; `>= 0`.
+        def initialize: (
+                          ?_top: Integer,
+                          ?right: Integer,
+                          ?bottom: Integer,
+                          ?left: Integer
+                        ) -> void
+
+        # _@return_ — `left` + `right`.
+        def horizontal: () -> Integer
+
+        # _@return_ — `top` + `bottom`.
+        def vertical: () -> Integer
+
+        # _@return_ — cells inset from the top edge.
+        attr_reader top: Integer
+
+        # _@return_ — cells inset from the right edge.
+        attr_reader right: Integer
+
+        # _@return_ — cells inset from the bottom edge.
+        attr_reader bottom: Integer
+
+        # _@return_ — cells inset from the left edge.
+        attr_reader left: Integer
+      end
+
       # Absolute layout. Extend this class, register any children, and
       # override {Component#rect=} to reposition the children.
       class Absolute < Layout
       end
+
+      # Abstract base of the one-dimensional box layouts. Children are stacked
+      # along a *main* axis in the order they were added, each getting the extent
+      # its constraint asks for; across the *cross* axis they are sized one at a
+      # time, since nothing competes with them there. {Vertical} and {Horizontal}
+      # pick which axis is which.
+      # 
+      #   class LoginForm < Tuile::Component::Layout::Vertical
+      #     def initialize
+      #       super(spacing: 1, padding: Insets[top: 1])
+      #       add(@prompt = Tuile::Component::Label.new, Fixed[4])
+      #       add(@user = Tuile::Component::TextField.new, Fixed[1], cross: Fixed[30])
+      #       add(@log = Tuile::Component::TextView.new, Expand[1])
+      #     end
+      #   end
+      # 
+      # The constraint names need no prefix inside a subclass — Ruby finds them on
+      # `Layout`, an ancestor. Component classes are not on that chain and still do.
+      # 
+      # Children pack from the start edge, so with no {Expand} among them the
+      # slack is simply left at the end: there is no filler component to add.
+      # Nest boxes to vary the gap — a `Vertical.new(spacing: 0)` inside a
+      # `Vertical.new(spacing: 1)` groups two rows tightly within a looser stack.
+      # 
+      # == Implementation details
+      # 
+      # Every child-list mutation re-runs the whole pass, because in a box the
+      # children move: removing one shifts everything after it, and adding one
+      # shrinks every {Expand} share. ({Absolute} can skip this — there, siblings
+      # are independent.)
+      # 
+      # Main-axis resolution order, against
+      # `available = extent - padding - spacing * (children - 1)`:
+      # 
+      # 1. {Fixed} takes its cells, clamped to what is still unassigned.
+      # 2. {Percent} takes its share *of `available`*, likewise clamped.
+      # 3. {Expand} children split the residue by weight; the integer remainder
+      #    goes to the earliest of them, one cell each.
+      # 
+      # So over-subscription starves in declaration order rather than raising:
+      # a child with nothing left gets an empty rect and paints nothing. Padding
+      # wider than the layout does the same to every child.
+      class Box < Layout
+        DEFAULT_PLACEMENT: ::Hash[Symbol, Object]
+        ALIGNMENTS: ::Array[Symbol]
+
+        # _@param_ `spacing` — blank cells between adjacent children; `>= 0`.
+        # 
+        # _@param_ `padding` — inset from this layout's own rect; an Integer is coerced to a uniform {Insets}.
+        def initialize: (?spacing: Integer, ?padding: (Insets | Integer)) -> void
+
+        # Adds a child — or every element of an Enumerable, all with the same
+        # constraints — and re-runs the layout.
+        # 
+        #   add(field, Fixed[1], cross: Fixed[30], align: :center)
+        #   add([ok, cancel], Fixed[1])
+        # 
+        # _@param_ `child`
+        # 
+        # _@param_ `main` — extent along the main axis.
+        # 
+        # _@param_ `cross` — extent across it.
+        # 
+        # _@param_ `align` — one of {ALIGNMENTS} — where a child narrower than the cross extent sits. {Vertical} / {Horizontal} say which edge `:start` is.
+        def add: (
+                   (Component | ::Enumerable[Component]) child,
+                   ?(Fixed | Percent | Expand) main,
+                   ?cross: (Fixed | Percent),
+                   ?align: Symbol
+                 ) -> void
+
+        # Removes the child, forgets its constraints, and closes the gap it left
+        # by re-running the layout.
+        # 
+        # _@param_ `child`
+        def remove: (Component child) -> void
+
+        # _@param_ `new_rect`
+        def rect=: (Rect new_rect) -> void
+
+        # Recomputes and assigns every child's rect. Silent until this layout has
+        # a rect of its own — {#add} runs during construction, long before a
+        # parent assigns one.
+        def relayout: () -> void
+
+        # _@return_ — {#rect} with {#padding} taken off each edge; may be
+        # {Rect#empty? empty}.
+        def inner_rect: () -> Rect
+
+        # _@param_ `inner` — {#inner_rect}, known non-empty.
+        def place_children: (Rect inner) -> void
+
+        # _@param_ `inner` — {#inner_rect}.
+        # 
+        # _@return_ — main-axis extent per child, in child order.
+        def main_sizes: (Rect inner) -> ::Array[Integer]
+
+        # Splits `slack` between the {Expand} children by weight, writing the
+        # results into `sizes`.
+        # 
+        # _@param_ `sizes` — mutated in place.
+        # 
+        # _@param_ `indices` — child indices carrying an {Expand}.
+        # 
+        # _@param_ `slack` — cells left over; a negative value yields zeroes.
+        def distribute_expand: (::Array[Integer] sizes, ::Array[Integer] indices, Integer slack) -> void
+
+        # _@param_ `child`
+        # 
+        # _@param_ `available` — cross extent of {#inner_rect}.
+        # 
+        # _@return_ — offset from `inner`'s start edge, and
+        # extent, along the cross axis.
+        def cross_placement: (Component child, Integer available) -> [Integer, Integer]
+
+        # _@param_ `align` — one of {ALIGNMENTS}.
+        # 
+        # _@param_ `slack` — unused cells across the axis.
+        def align_offset: (Symbol align, Integer slack) -> Integer
+
+        # _@param_ `extent`
+        # 
+        # _@param_ `constraint`
+        def percent_of: (Integer extent, Percent constraint) -> Integer
+
+        # _@param_ `child`
+        # 
+        # _@return_ — the child's `main`/`cross`/`align`.
+        def placement: (Component child) -> ::Hash[Symbol, Object]
+
+        # _@param_ `rect`
+        # 
+        # _@return_ — the extent along the main axis.
+        def main_extent: (Rect rect) -> Integer
+
+        # _@param_ `rect`
+        # 
+        # _@return_ — the extent along the cross axis.
+        def cross_extent: (Rect rect) -> Integer
+
+        # _@param_ `inner` — {#inner_rect}, the origin both offsets are relative to.
+        # 
+        # _@param_ `main_offset` — cells along the main axis.
+        # 
+        # _@param_ `main_size` — extent along the main axis.
+        # 
+        # _@param_ `cross_offset` — cells along the cross axis.
+        # 
+        # _@param_ `cross_size` — extent along the cross axis.
+        # 
+        # _@return_ — absolute screen rect for one child.
+        def build_rect: (
+                          Rect inner,
+                          Integer main_offset,
+                          Integer main_size,
+                          Integer cross_offset,
+                          Integer cross_size
+                        ) -> Rect
+
+        # _@param_ `cells`
+        # 
+        # _@return_ — `cells`.
+        def validate_spacing: (Integer cells) -> Integer
+
+        # _@param_ `constraint`
+        def validate_main: (Object constraint) -> void
+
+        # _@param_ `constraint`
+        def validate_cross: (Object constraint) -> void
+
+        # _@param_ `align`
+        def validate_align: (Object align) -> void
+
+        # _@return_ — blank cells between adjacent children.
+        attr_accessor spacing: Integer
+
+        # _@return_ — inset from this layout's own rect.
+        attr_accessor padding: (Insets | Integer)
+      end
+
+      # Stacks children top to bottom. The main axis is vertical, so a child's
+      # positional constraint is its **height** and `cross:` is its **width**;
+      # `align: :start` is the left edge, `:end` the right.
+      # 
+      #   form = Component::Layout::Vertical.new(spacing: 1)
+      #   form.add(caption, Component::Layout::Fixed[1])
+      #   form.add(field, Component::Layout::Fixed[1], cross: Component::Layout::Fixed[30])
+      #   form.add(log, Component::Layout::Expand[1])   # takes whatever is left below
+      # 
+      # Inside a subclass the constraints need no prefix at all — see {Box}.
+      # 
+      # See {Box} for the constraint vocabulary and how the space is divided.
+      class Vertical < Tuile::Component::Layout::Box
+        DEFAULT_PLACEMENT: ::Hash[Symbol, Object]
+        ALIGNMENTS: ::Array[Symbol]
+
+        # _@param_ `rect`
+        def main_extent: (Rect rect) -> Integer
+
+        # _@param_ `rect`
+        def cross_extent: (Rect rect) -> Integer
+
+        # _@param_ `inner`
+        # 
+        # _@param_ `main_offset` — rows down from `inner`'s top.
+        # 
+        # _@param_ `main_size` — height.
+        # 
+        # _@param_ `cross_offset` — columns right of `inner`'s left.
+        # 
+        # _@param_ `cross_size` — width.
+        def build_rect: (
+                          Rect inner,
+                          Integer main_offset,
+                          Integer main_size,
+                          Integer cross_offset,
+                          Integer cross_size
+                        ) -> Rect
+      end
+
+      # Lays children out left to right. The main axis is horizontal, so a
+      # child's positional constraint is its **width** and `cross:` is its
+      # **height**; `align: :start` is the top edge, `:end` the bottom.
+      # 
+      #   split = Component::Layout::Horizontal.new
+      #   split.add(sidebar, Component::Layout::Fixed[30])
+      #   split.add(main, Component::Layout::Expand[1])   # takes the rest of the row
+      # 
+      # Inside a subclass the constraints need no prefix at all — see {Box}.
+      # 
+      # See {Box} for the constraint vocabulary and how the space is divided.
+      class Horizontal < Tuile::Component::Layout::Box
+        DEFAULT_PLACEMENT: ::Hash[Symbol, Object]
+        ALIGNMENTS: ::Array[Symbol]
+
+        # _@param_ `rect`
+        def main_extent: (Rect rect) -> Integer
+
+        # _@param_ `rect`
+        def cross_extent: (Rect rect) -> Integer
+
+        # _@param_ `inner`
+        # 
+        # _@param_ `main_offset` — columns right of `inner`'s left.
+        # 
+        # _@param_ `main_size` — width.
+        # 
+        # _@param_ `cross_offset` — rows down from `inner`'s top.
+        # 
+        # _@param_ `cross_size` — height.
+        def build_rect: (
+                          Rect inner,
+                          Integer main_offset,
+                          Integer main_size,
+                          Integer cross_offset,
+                          Integer cross_size
+                        ) -> Rect
+      end
+    end
+
+    # A closed-choice field on one row: the selected item's label plus a `▾`
+    # affordance, dropping open a {ListDropdown} of the options. Enter, Space or
+    # Down opens it; the arrows (and PgUp/PgDn) move the highlight; Enter or
+    # Space commits; ESC dismisses without committing.
+    # 
+    #   warn                ▾     <- the face: one row, on a field well
+    #    debug                    <- the dropdown, measured to the widest label
+    #    info                        (the one-column gutters are {List}'s)
+    #    warn                     <- highlighted: the value's row, on open
+    #    error
+    # 
+    #   sel = Component::Select.new(items: LogLevel.all)
+    #   sel.item_label = ->(l) { l.name }          # item -> shown label; default :to_s
+    #   sel.on_value_change = ->(l) { relog(l) }   # fires on commit, with the item
+    #   sel.value = LogLevel::WARN                 # selects it; the face shows its label
+    # 
+    # Use it for an **enum** — labels the developer authored, a closed set known
+    # when the code is written: log level, sort order, line endings, Yes/No/Ask.
+    # For items the app supplies at runtime with labels you don't control
+    # (countries, users, branches) reach for {ComboBox} instead, where filtering
+    # is the navigation. Item count is a symptom, not the criterion; book ch7 has
+    # the widget-choice table.
+    # 
+    # {#value} is the selected *item*, of whatever type {#items} holds, never its
+    # label; `nil` — a blank face — is the initial state and stays legal, so an
+    # optional enum field needs no placeholder. As on {ComboBox}, {#items=} is
+    # chrome: it never touches {#value}, never fires {HasValue#on_value_change},
+    # and a value absent from {#items} survives intact while rendering nothing
+    # selected. Keeping the two in sync is the app's job.
+    # 
+    # == It claims no printable key but Space
+    # Enter, Space, ESC, {ListDropdown::MOVE_KEYS} and the mouse. *Every other*
+    # printable key bubbles past it (key-dispatch rung 3), so a form's `s`-to-save
+    # and a layout's `1`/`2`/`3` pane jumps keep working while a Select has focus
+    # — the one capability no {ComboBox} configuration can offer, since a text
+    # field eats printables unconditionally. Space is the single exception, and it
+    # forecloses nothing: every activatable widget in the gem already claims it.
+    # 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
+    # need no prefix-disambiguation.
+    # 
+    # == Implementation details
+    # A leaf widget: it paints its own row (the face is *derived* from {#value}
+    # each paint, never a synced copy) and owns the dropdown as an overlay, which
+    # is not a child — like {ComboBox}'s. The well is read from
+    # {Screen#theme} at paint time, so it tracks a theme flip with no hook.
+    # 
+    # The dropdown is at least as wide as the face and grows to fit the widest
+    # label, so the labels are never the thing that ellipsizes. It is not opened
+    # at all when {#items} is empty: an item-less Select is a programming bug, and
+    # an empty tinted panel reads as a broken list rather than as "nothing to
+    # pick". Enter/Space/Down are claimed either way.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class Select < Component
+      include Tuile::Component::HasValue
+
+      # _@param_ `items` — the options (any type); also settable via {#items=}.
+      # 
+      # _@param_ `value` — the initially selected item. Seeds the backing ivar directly, so no listener fires and assignment order doesn't matter to a form helper.
+      def initialize: (?items: ::Array[untyped], ?value: Object?) -> void
+
+      def tab_stop?: () -> bool
+
+      def keyboard_hint: () -> String
+
+      # Re-anchors the (open) dropdown after a move or resize.
+      # 
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
+
+      # Closes the dropdown when the Select leaves the focus chain, so tabbing
+      # away doesn't strand an open menu. Safe against re-entrancy: focus never
+      # sits inside the (non-focusable) {ListDropdown}, so closing it repairs no
+      # focus.
+      # 
+      # _@param_ `flag`
+      def active=: (bool flag) -> void
+
+      # Opens the dropdown on Enter, Space or Down; while it is open, forwards
+      # {ListDropdown::MOVE_KEYS} to it, commits the highlight on Enter or Space,
+      # and dismisses on ESC. Everything else — every other printable included —
+      # is left unhandled so it bubbles to an ancestor.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Toggles the dropdown on a left click anywhere in {#rect} — a field's
+      # affordance is its whole row, as the well advertises; `super` runs first,
+      # so the click also focuses.
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # The painted row: the value's label padded across all but the last column,
+      # then the `▾`, all on the field well — {Theme#active_bg_color} while on the
+      # focus chain, {Theme#input_bg_color} otherwise.
+      def face_row: () -> StyledString
+
+      # Rebuilds the dropdown's rows, highlight and geometry, opening it if
+      # needed; closes it instead when there is nothing to show.
+      def refill: () -> void
+
+      def open_menu: () -> void
+
+      def close_menu: () -> void
+
+      # Adopts the item on row `index` as {#value} and closes the dropdown.
+      # 
+      # _@param_ `index`
+      def commit: (Integer index) -> void
+
+      def anchor: () -> void
+
+      # The dropdown's width: the widest label plus {List}'s two row gutters, plus
+      # the scrollbar column when the rows can't all be shown at once — but never
+      # narrower than the Select itself, so both edges line up with the face and
+      # the panel reads as belonging to it. Only a label that needs more pushes it
+      # wider.
+      # 
+      # A dropdown the screen clamps shorter than
+      # {ListDropdown::MAX_VISIBLE_ROWS} scrolls without having bought that
+      # column, ellipsizing its labels one early — the {ComboBox} trade, in the
+      # one case measuring can't predict the height.
+      def menu_width: () -> Integer
+
+      # _@param_ `item`
+      # 
+      # _@return_ — `item`'s label, or empty for `nil` — so {#value}
+      # being unset never reaches an {#item_label} that assumes an item.
+      def label_for: (Object item) -> StyledString
+
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
+
+      # No-op (no repaint, no listener) when equal to the current value.
+      # 
+      # _@param_ `new_value`
+      def value=: (Object new_value) -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # _@return_ — the value {#empty?}/{#clear} treat as empty; `nil`
+      # unless an includer overrides it.
+      def empty_value: () -> Object
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@return_ — the options.
+      attr_accessor items: ::Array[untyped]
+
+      # _@return_ — item -> shown label (a `String` or
+      # {StyledString}); `:to_s` by default. Never called with `nil` — an
+      # unselected Select renders a blank face.
+      attr_accessor item_label: (Proc | Method)
     end
 
     # A window with a frame, a {#caption} and a content {Component}. Doesn't
@@ -2116,14 +2836,13 @@ module Tuile
     # by {Component#invalidate}; subclasses don't need to re-check.)
     class Window < Component
       include Tuile::Component::HasContent
+      include Tuile::Component::HasCaption
 
-      # _@param_ `caption`
-      def initialize: (?String caption) -> void
+      # _@param_ `caption` — the border title, coerced the same way {HasCaption#caption=} coerces it.
+      def initialize: (?(String | StyledString)? caption) -> void
 
       def focusable?: () -> bool
 
-      def children: () -> ::Array[Component]
-
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
@@ -2145,20 +2864,29 @@ module Tuile
       # cycle.
       def repaint: () -> void
 
-      # _@param_ `key`
-      def key_shortcut=: (String? key) -> void
-
       # _@param_ `content`
       def layout: (Component content) -> void
 
-      # Paints the window border into the {Screen#buffer}. Title is clipped to
-      # the inner width so the box never overflows {#rect}; when the window is
-      # active the whole border is drawn in {Theme#active_border_color}.
+      # Paints the window border via {Component#draw_line}/{Component#draw_char},
+      # so the border cells inherit {Component#effective_bg_color} — a
+      # {Component#bg_color} on the window tints border and content alike. Both
+      # border lines are clipped by *display* width, so no caption overflows the
+      # box; when the window is active the whole border — the caption's own
+      # colors included — is drawn in {Theme#active_border_color}.
       def repaint_border: () -> void
 
-      # Builds the bottom border line. The corners take the border color; the
-      # interior is plain dashes when a {#footer} component occupies the row
-      # (it overpaints them) or when there's no chrome, otherwise it carries
+      # Builds the top border line: corners, {#caption} embedded at its own
+      # width, dashes filling the remainder. The caption keeps its own styling
+      # unless `fg` is set — an active window's border claims it.
+      # 
+      # _@param_ `inner_w` — the border's interior width.
+      # 
+      # _@param_ `fg` — the active-border color, or nil when inactive.
+      def top_border: (Integer inner_w, Color? fg) -> StyledString
+
+      # Builds the bottom border line. The corners take the border color; the
+      # interior is plain dashes when a {#footer} component occupies the row
+      # (it overpaints them) or when there's no chrome, otherwise it carries
       # {#footer_text} embedded at its own width — keeping the text's own
       # styling — with dashes filling the remainder up to the inner width.
       # 
@@ -2167,15 +2895,24 @@ module Tuile
       # _@param_ `fg` — the active-border color, or nil when inactive.
       def bottom_border: (Integer inner_w, Color? fg) -> StyledString
 
-      # The caption text as it appears in the rendered border, including the
-      # shortcut prefix when {#key_shortcut} is set.
-      def frame_caption: () -> String
-
       # Positions the footer over the bottom border row, spanning the full
       # inner width (the only dimension a bottom-row widget needs — the window
       # already knows it).
       def layout_footer: () -> void
 
+      # Read through *this* method, never `@caption` — the ivar stays nil until
+      # the first non-empty set ({#caption=} short-circuits when unchanged).
+      # 
+      # _@return_ — the caption; empty when never set.
+      def caption: () -> StyledString
+
+      # Sets the caption and invalidates the component. No-op when unchanged. A
+      # `String` is parsed via {StyledString.parse} (embedded ANSI is honored);
+      # a {StyledString} is used as-is; `nil` clears it.
+      # 
+      # _@param_ `new_caption`
+      def caption=: ((String | StyledString)? new_caption) -> void
+
       def on_focus: () -> void
 
       # _@return_ — optional focusable component occupying the
@@ -2186,9 +2923,346 @@ module Tuile
       # line, mirroring {#caption} on the top line. Empty by default; hidden
       # whenever a {#footer} component is present.
       attr_accessor footer_text: (StyledString | String)?
+    end
+
+    # A boolean input on one row. Space, Enter or a left click toggles it:
+    # 
+    #   [x] Enable syslog forwarding
+    #   [ ] Enable syslog forwarding
+    # 
+    #   cb = Component::Checkbox.new("Enable syslog forwarding", value: true)
+    #   cb.on_value_change = ->(on) { config.syslog = on }
+    #   cb.toggle       # unchecks it, firing the listener with false
+    #   cb.checked?     # => false
+    # 
+    # {#value} is the canonical seam ({HasValue}), always `true`/`false` and
+    # never `nil`; {#checked?} / {#checked=} / {#toggle} are the domain-word face
+    # over it — one piece of state, four names. Unchecked is the
+    # {#empty_value}, so a fresh checkbox is {HasValue#empty? empty} and
+    # {HasValue#clear} unchecks.
+    # 
+    # Space and Enter both toggle — same as a checkable row in a
+    # {Component::List} ({CheckboxGroup}, {RadioGroup}), so the gesture reads the
+    # same standalone and grouped. A focused checkbox therefore *consumes* Enter:
+    # a form's Enter-to-submit on an ancestor won't see it, exactly as with a
+    # focused {Button} or {TextArea}. Which widget lets Enter through is per
+    # widget, never a framework guarantee — book ch5's Enter table is the list.
+    # 
+    # A tab stop, so Tab lands on it, and the widget highlights while on the focus
+    # chain. Assign a {#rect} (typically from the surrounding {Layout}) at least
+    # `caption.display_width + 4` wide; a narrower one ellipsizes the caption, a
+    # wider one leaves a dead tail — see {#extent}.
+    # 
+    # == Implementation details
+    # The glyphs are a house convention rather than constants: three columns plus
+    # a trailing space (`[x] `, `[ ] `), ASCII because `☑`/`☐` are absent from
+    # most monospace fonts and the fallback glyph bleeds over its cell. A widget
+    # painting checkbox-like rows without instantiating a Checkbox — checkable
+    # rows in a {Component::List} — repeats those literals to match.
+    class Checkbox < Component
+      include Tuile::Component::HasValue
+      include Tuile::Component::HasCaption
+
+      # _@param_ `caption` — the label, coerced as {HasCaption#caption=} coerces it.
+      # 
+      # _@param_ `value` — initial state. Assigned through {#value=}, which also seeds the backing ivar — an unseeded checkbox would read `nil` and so report itself non-{HasValue#empty? empty} while fresh.
+      def initialize: (?(String | StyledString)? caption, ?value: bool) -> void
+
+      def tab_stop?: () -> bool
+
+      # _@return_ — `false` — {HasValue#empty?} means unchecked.
+      def empty_value: () -> bool
+
+      # Coerces to `true`/`false` before storing, so the two-state invariant holds
+      # whatever a caller assigns — and `cb.value = nil` on a fresh checkbox is
+      # the no-op it looks like rather than a spurious change event.
+      # 
+      # _@param_ `new_value` — anything; truthiness decides.
+      def value=: (Object new_value) -> void
+
+      # _@return_ — {#value} under its domain word — `license.checked?`
+      # reads better than `license.value`. Not a second piece of state.
+      def checked?: () -> bool
+
+      # {#value=} under its domain word. A delegator rather than an `alias`, so it
+      # keeps routing through the one write path even if a subclass overrides
+      # {#value=} (an `alias` would freeze this onto the body defined here).
+      # 
+      # _@param_ `new_value` — anything; truthiness decides.
+      def checked=: (Object new_value) -> void
+
+      # Flips {#value}.
+      def toggle: () -> void
+
+      # The cells the widget actually paints: one row, `caption.display_width + 4`
+      # columns, clipped to {#rect}. A form column routinely hands a checkbox a
+      # 40-column rect for a 22-column `[ ] Enable syslog forwarding` — the extent
+      # is those 22 columns.
+      # 
+      # 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
+      # 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
+      # tail, but a hit test that silently widened with a background would be a
+      # mode switch invisible in the code and untestable by inspection.
+      def extent: () -> Rect
+
+      # Toggles on Space or Enter. Every other key is left unhandled so it bubbles
+      # to an ancestor.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Toggles on a left click within {#extent}; `super` runs first, so a click
+      # anywhere in {#rect} still focuses.
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # Read through *this* method, never `@caption` — the ivar stays nil until
+      # the first non-empty set ({#caption=} short-circuits when unchanged).
+      # 
+      # _@return_ — the caption; empty when never set.
+      def caption: () -> StyledString
+
+      # Sets the caption and invalidates the component. No-op when unchanged. A
+      # `String` is parsed via {StyledString.parse} (embedded ANSI is honored);
+      # a {StyledString} is used as-is; `nil` clears it.
+      # 
+      # _@param_ `new_caption`
+      def caption=: ((String | StyledString)? new_caption) -> void
+
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+    end
+
+    # A text field with a filtering dropdown: type to narrow the candidates,
+    # arrow to move the highlight, Enter (or click) to accept. Its {#value} is
+    # the *selected item* — of whatever type the items are — not the display
+    # string, so a combo over domain objects hands back the object:
+    # 
+    #   combo = Component::ComboBox.new
+    #   combo.items = User.all                       # Array of any type
+    #   combo.item_label = ->(u) { u.full_name }     # item -> shown text; default :to_s
+    #   combo.on_value_change = ->(u) { open(u) }    # fires on commit, with the item
+    #   combo.value = some_user                       # selects it; field shows its label
+    # 
+    # It's the assembly you'd otherwise wire by hand — a {TextField} plus a
+    # non-modal {Popup} over a {List} — promoted to one component. Give it a
+    # single-row {#rect}; it paints the field across that row with a `▾` in the
+    # last column and floats the dropdown above or below.
+    # 
+    # == The two values
+    # {#value} (the committed selection) and the field's typed text (a transient
+    # *query*) are deliberately distinct. Keystrokes move the query and refilter
+    # the list; only Enter/click commits, and only a commit changes {#value} and
+    # fires {#on_value_change}. An uncommitted query reverts to the current
+    # value's label when the dropdown is dismissed (ESC) or the combo loses
+    # focus. Selecting by list index (not by matching the label back) is what
+    # lets two items share a label and still resolve to the right object.
+    # 
+    # The dropdown is a {ListDropdown}, tinted to read as a floating panel; see
+    # it for the theming knob.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class ComboBox < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+
+      # _@param_ `items` — the candidate items (any type); also settable via {#items=}.
+      def initialize: (?items: ::Array[untyped]) -> void
+
+      # Selects `new_value` programmatically: updates the field to its label
+      # *without* opening the dropdown, then fires {#on_value_change}. `nil`
+      # clears the selection (blank field). The value need not be in {#items}.
+      # 
+      # _@param_ `new_value`
+      def value=: (Object new_value) -> void
+
+      # _@return_ — the field's caret position (the combo delegates the
+      # hardware cursor to its field).
+      def cursor_position: () -> Point?
+
+      def keyboard_hint: () -> String
+
+      # Re-anchors the (open) dropdown after {HasContent#rect=} has resized the
+      # field via {#layout}.
+      # 
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> 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
+      # the (non-focusable) {ListDropdown}, so closing the overlay repairs no
+      # focus.
+      # 
+      # _@param_ `flag`
+      def active=: (bool flag) -> void
 
-      # _@return_ — the current caption, empty by default.
-      attr_accessor caption: String
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # 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
+
+      # The field's key interceptor: while the dropdown is open forwards movement
+      # to it ({ListDropdown#move}), commits on Enter ({ListDropdown#choose}),
+      # and dismisses on ESC (reverting the query); opens it on Down or Enter
+      # when closed. Everything else (printable keys, editing) falls through to
+      # the field, whose {TextField#on_change} refilters.
+      # 
+      # _@param_ `key`
+      # 
+      # _@return_ — true if consumed.
+      def field_key: (String key) -> bool
+
+      # Recomputes the matches for the current query, opening the dropdown when
+      # there are any (and preselecting the current value's row) or closing it
+      # when there are none.
+      def refill: () -> void
+
+      # Items whose label contains `query` (case-insensitive). A query still
+      # equal to the current value's label — the resting state, or a fresh
+      # open — is treated as "show everything", so Down opens the full list.
+      # 
+      # _@param_ `query`
+      def matching: (String query) -> ::Array[untyped]
+
+      # Commits the item at the menu's `index`: closes the dropdown and adopts
+      # it as {#value} (which repaints the field with its label).
+      # 
+      # _@param_ `index`
+      def commit: (Integer index) -> void
+
+      def open_menu: () -> void
+
+      def close_menu: () -> void
+
+      def revert_query: () -> void
+
+      # Sets the field's text without triggering a refilter — for programmatic
+      # value changes and query reverts, which must not spring the dropdown.
+      # Parks the caret at the end: `text=` only *clamps* the caret, so a
+      # shorter query replaced by a longer label would otherwise strand it
+      # mid-word (commit "Go", then pick "Kotlin" → caret after "Ko").
+      # 
+      # _@param_ `text`
+      def sync_field: (String text) -> void
+
+      # _@param_ `item`
+      # 
+      # _@return_ — the plain-text label for `item`, or "" for nil.
+      def display_for: (Object item) -> String
+
+      # Places the dropdown at the combo's own width, so both its edges line up
+      # with the field — at the cost of the scrollbar taking its column from the
+      # labels, which ellipsize a column earlier once the list scrolls. That is
+      # the trade a measuring driver ({Select}) makes the other way.
+      def anchor: () -> void
+
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # _@return_ — the value {#empty?}/{#clear} treat as empty; `nil`
+      # unless an includer overrides it.
+      def empty_value: () -> Object
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> 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)
+    end
+
+    # The value seam every input component shares: a settable/gettable {#value}
+    # of *any* type, an {#on_value_change} listener, {#empty?}, and {#clear}. A
+    # form (a future binder) drives a mix of field types uniformly through it,
+    # not caring that a {TextField}'s value is a `String` while another field's
+    # is a domain object.
+    # 
+    #   field.on_value_change = ->(v) { puts "now: #{v.inspect}" }
+    #   field.value = "hello"   # fires the listener
+    #   field.clear             # value = empty_value, fires again
+    # 
+    # The default {#value=}/{#value} keep the value in `@value` and are enough
+    # for a component with nothing more natural — you get a repaint and the
+    # listener for free. An includer whose value lives elsewhere overrides both
+    # ({AbstractStringField} backs them with its text buffer). Override {#empty_value}
+    # when the empty sentinel isn't `nil` (a text field's is `""`).
+    # 
+    # == Implementation details
+    # Deliberately smaller than Vaadin's `HasValue`: read-only,
+    # required-indicator, the from-client/old-value event payload, and
+    # converters all belong to the not-yet-built form layer, not here.
+    module HasValue
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
+
+      # No-op (no repaint, no listener) when equal to the current value.
+      # 
+      # _@param_ `new_value`
+      def value=: (Object new_value) -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # _@return_ — the value {#empty?}/{#clear} treat as empty; `nil`
+      # unless an includer overrides it.
+      def empty_value: () -> Object
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@return_ — one-arg callable fired with the new value
+      # whenever {#value} actually changes — never on a no-op set.
+      attr_accessor on_value_change: (Proc | Method)?
     end
 
     # A multi-line, word-wrapping text input.
@@ -2199,15 +3273,33 @@ module Tuile
     # follows the caret so the line being edited stays visible. There is no
     # horizontal scrolling.
     # 
-    # The caret is a logical index in `0..text.length`. When the caret falls
+    # The caret is a logical index in `0..text.length`, always on a
+    # grapheme-cluster boundary ({AbstractStringField}). When the caret falls
     # inside a whitespace run that was absorbed by a soft wrap, it displays
     # at the end of the previous row (which is visually identical to the
     # start of the next row in nearly all cases).
     # 
-    # Currently only {#on_change} is wired; Enter inserts a newline as in any
-    # plain `<textarea>` or text editor. A future `on_enter`/`on_submit`
-    # callback may opt out of that by consuming Enter instead.
-    class TextArea < Tuile::Component::TextInput
+    # Enter inserts a newline, as in a plain `<textarea>` or text editor; only
+    # {#on_change} is wired. A pasted line break arrives as `\n`
+    # ({Keys::CTRL_J}) rather than the `\r` a typed Enter sends, so both are
+    # accepted — otherwise a multi-line paste would silently lose its
+    # newlines.
+    # 
+    # == Implementation details
+    # 
+    # The same two axes {TextField} names apply, and the wrap straddles both: an
+    # **index** counts characters into {#text} ({#caret}, a row's `start` and
+    # `length`), a **column** counts terminal cells ({#rect}, a row's `columns`,
+    # {#cursor_position}, a {MouseEvent}). A row therefore carries *both* counts,
+    # and the wrap fills each row to a column budget while recording a character
+    # span. Everything crossing between them goes through the inherited
+    # `columns_of` and the private `chars_for_column`.
+    # 
+    # The wrap walks **grapheme clusters**, not characters — a combining mark must
+    # add no columns and must not be split from its base across a row break. Note
+    # `"\r\n"` is a *single* cluster, so a hard break tests `end_with?("\n")`
+    # rather than equality.
+    class TextArea < Tuile::Component::AbstractStringField
       def initialize: () -> void
 
       def cursor_position: () -> Point?
@@ -2230,30 +3322,98 @@ module Tuile
       # current {Rect#width}. Each entry is `{start:, length:}`.
       def display_rows: () -> ::Array[::Hash[Symbol, Integer]]
 
-      # Greedy word-wrap. Whitespace at a soft-wrap break point is absorbed
-      # (not rendered on either row). A token longer than {Rect#width} hard-
-      # wraps inside the token. Newlines force a hard break and the wrap
-      # restarts on the next character.
+      # _@return_ — one entry per grapheme cluster of
+      # {#text}: `{offset: <text-index>, text: <cluster>, width: <columns>}`.
+      # Rebuilt per wrap and discarded — the wrap is what's cached.
+      def cluster_table: () -> ::Array[::Hash[Symbol, Object]]
+
+      # _@param_ `cluster`
+      # 
+      # _@return_ — true for a space or tab (each exactly one column).
+      def blank?: (::Hash[Symbol, Object] cluster) -> bool
+
+      # _@param_ `cluster`
+      # 
+      # _@return_ — true for a hard line break. Tests the suffix rather
+      # than equality because `"\r\n"` is one grapheme cluster.
+      def newline?: (::Hash[Symbol, Object] cluster) -> bool
+
+      # Greedy word-wrap, filling each row to a **column** budget while recording
+      # the **character** span that produced it. Whitespace at a soft-wrap break
+      # point is absorbed (not rendered on either row). A token wider than
+      # {Rect#width} hard-wraps inside the token. Newlines force a hard break and
+      # the wrap restarts on the next cluster.
       def compute_display_rows: () -> ::Array[::Hash[Symbol, Integer]]
 
+      # _@param_ `clusters`
+      # 
+      # _@param_ `index` — cluster index of the word's first glyph.
+      # 
+      # _@return_ — `[chars, columns, next_index]`
+      # for the run of non-whitespace starting at `index`.
+      def measure_word: (::Array[::Hash[Symbol, Object]] clusters, Integer index) -> [Integer, Integer, Integer]
+
+      # Splits a token too wide for a whole row, taking entire glyphs while they
+      # fit. Consumes at least one glyph even when that single glyph is wider than
+      # the row — otherwise the wrap would not terminate (the row would stay empty
+      # and the same token be reconsidered forever). Such a row reports more
+      # columns than the rect holds and {#padded_row} drops the glyph; a
+      # 2-column glyph in a 1-column area is unpaintable either way.
+      # 
+      # _@param_ `clusters`
+      # 
+      # _@param_ `index`
+      # 
+      # _@param_ `width` — column budget.
+      # 
+      # _@return_ — `[chars, columns, next_index]`
+      def hard_wrap: (::Array[::Hash[Symbol, Object]] clusters, Integer index, Integer width) -> [Integer, Integer, Integer]
+
       # Trims trailing space/tab characters off a row's visible length so the
       # whitespace at a soft-wrap point is absorbed (not rendered) rather than
       # left at the end of the row. Without this, soft-wrapping `"foo bar"`
       # to width 4 would yield row 0 length 4 (`"foo "`) and the natural
       # end-of-row caret position would coincide with row 1's start.
       # 
+      # Both counts drop by one per trimmed character: a space and a tab each
+      # measure exactly one column.
+      # 
       # _@param_ `row_start`
       # 
       # _@param_ `row_chars`
       # 
-      # _@return_ — new row_chars.
-      def trim_trailing_whitespace: (Integer row_start, Integer row_chars) -> Integer
+      # _@param_ `row_cols`
+      # 
+      # _@return_ — `[row_chars, row_cols]`
+      def trim_trailing_whitespace: (Integer row_start, Integer row_chars, Integer row_cols) -> [Integer, Integer]
 
       # _@param_ `caret`
       # 
       # _@return_ — `[row_index, column]` for `caret`.
       def caret_to_display: (Integer caret) -> [Integer, Integer]
 
+      # _@param_ `row`
+      # 
+      # _@param_ `caret`
+      # 
+      # _@return_ — `caret`'s column offset within `row`.
+      def caret_column_in: (::Hash[Symbol, Integer] row, Integer caret) -> Integer
+
+      # _@param_ `row`
+      # 
+      # _@param_ `column` — a column offset within `row`.
+      # 
+      # _@return_ — characters from the row's start. A column landing in a
+      # wide glyph's right half resolves past it, as a click does in
+      # {TextField}.
+      def chars_for_column: (::Hash[Symbol, Integer] row, Integer column) -> Integer
+
+      # _@param_ `row`
+      # 
+      # _@return_ — the row's text padded to `rect.width` columns. A glyph
+      # with no room left is dropped rather than half-painted.
+      def padded_row: (::Hash[Symbol, Integer] row) -> String
+
       # _@param_ `delta` — `+1` for down, `-1` for up.
       def move_caret_vertical: (Integer delta) -> void
 
@@ -2274,41 +3434,31 @@ module Tuile
     end
 
     # A read-only viewer for prose: chunks of formatted text that scroll
-    # vertically. Shape-wise a hybrid between {Label} (string-shaped content
-    # via {#text=}) and {List} (scroll keys, optional scrollbar, auto-scroll).
-    # 
-    # Text is modeled as a {StyledString}: embedded `\n` are hard line breaks,
-    # lines wider than the viewport are word-wrapped via {StyledString#wrap}
-    # (style spans are preserved across wrap boundaries — unlike the older
-    # ANSI-as-bytes wrapping, color does *not* get dropped on continuation
-    # rows). {#text=} accepts a {String} (parsed via {StyledString.parse},
-    # so embedded ANSI is honored) or a {StyledString} directly; {#text}
-    # always returns the {StyledString}.
-    # 
-    # For incremental updates pick the right primitive: {#append} (aliased
-    # as `<<`) is verbatim and stream-friendly — chunks are concatenated
-    # straight onto the buffer, with embedded `\n` becoming hard breaks.
-    # {#add_line} is the "log entry" convenience — it starts the content on
-    # a fresh line by inserting a leading `\n` when the buffer is non-empty.
-    # {#remove_last_n_lines} pops hard lines back off the tail — the
-    # inverse of building up a region with {#append} / {#add_line}, so a
-    # caller streaming reformattable content (e.g. partially-rendered
-    # Markdown that may need to retract its last paragraph) can replace
-    # the tail without rewriting the whole text. Turn on {#auto_scroll}
-    # to keep the latest content in view.
-    # 
-    # TextView is meant to be the content of a {Window} — focus indication and
-    # keyboard-hint surfacing rely on the surrounding window chrome.
+    # vertically. Shape-wise a hybrid between {Label} (string content via
+    # {#text=}) and {List} (scroll keys, optional scrollbar, auto-scroll).
+    # 
+    # Text is a {StyledString}: embedded `\n` are hard line breaks, longer lines
+    # are word-wrapped via {StyledString#wrap} with style spans preserved across
+    # wrap boundaries. {#text=} takes a {String} (parsed via {StyledString.parse},
+    # honoring embedded ANSI) or a {StyledString}; {#text} always returns the
+    # {StyledString}.
+    # 
+    # Pick the right incremental primitive: {#append} (aliased `<<`) concatenates
+    # a chunk verbatim onto the buffer (stream-friendly, `\n` → hard breaks);
+    # {#add_line} starts the chunk on a fresh line (the "log entry" convenience);
+    # {#remove_last_n_lines} pops hard lines off the tail, so a caller streaming
+    # reformattable content can retract and rewrite it; {#replace} / {#insert}
+    # 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.
     class TextView < Component
       def initialize: () -> void
 
-      # _@return_ — the current text. Defaults to an empty
-      # {StyledString}. Internally the text is stored as an array of hard
-      # lines so {#append} can stay O(appended) instead of re-scanning the
-      # whole buffer; the joined {StyledString} returned here is
-      # reconstructed on first read after a mutation and cached, so
-      # repeated reads are O(1) but the first read after {#append} pays
-      # O(total spans).
+      # _@return_ — the current text (empty by default). Rebuilt
+      # lazily on the first read after a mutation (O(total spans)), then
+      # cached — repeated reads are O(1).
       def text: () -> StyledString
 
       # _@return_ — whether {#auto_scroll} is currently tailing. True
@@ -2346,19 +3496,12 @@ module Tuile
       # _@return_ — true iff {#text} is empty (no hard lines).
       def empty?: () -> bool
 
-      # Appends `str` verbatim. Embedded `\n` characters become hard line
-      # breaks; otherwise the text is concatenated onto the current last
-      # hard line. Designed for streaming use (e.g. an LLM chat window
-      # receiving partial messages — feed each chunk straight in). Accepts
-      # the same input forms as {#text=}; empty/`nil` input is a no-op.
-      # 
-      # For the "add an entry on a new line" pattern use {#add_line}.
-      # 
-      # Cost is O(appended + width-of-current-last-hard-line) — the
-      # previously last hard line is re-wrapped (because the extension may
-      # cause it to wrap differently), any additional hard lines created by
-      # embedded `\n` are wrapped fresh. The cached {#text} is invalidated
-      # and rebuilt on demand.
+      # Appends `str` verbatim. Embedded `\n` become hard line breaks; otherwise
+      # the text is concatenated onto the current last hard line. Designed for
+      # streaming use (feed each partial chunk straight in). Accepts the same
+      # input forms as {#text=}; empty/`nil` is a no-op. For the "entry on a new
+      # line" pattern use {#add_line}. Cost is O(appended + width of the last
+      # hard line), which is re-wrapped since the extension may wrap differently.
       # 
       # _@param_ `str`
       def append: ((String | StyledString)? str) -> void
@@ -2378,56 +3521,30 @@ module Tuile
       # _@param_ `str`
       def add_line: ((String | StyledString)? str) -> void
 
-      # Drops the last `n` hard lines from the buffer. The inverse of
-      # building up a tail region with {#append} / {#add_line}: a caller
-      # streaming partially-rendered content whose tail must occasionally
-      # be retracted (e.g. Markdown-to-ANSI where a new token reformats
-      # the table being built) can call `remove_last_n_lines(k)` followed
-      # by `append(new_tail)` to replace the damaged region in place.
-      # 
-      # `n == 0` and the empty-buffer case are no-ops (no invalidation).
-      # `n >= hard-line count` empties the buffer.
-      # 
-      # Operates on **hard lines** (the `\n`-delimited entries the
-      # buffer stores), not on wrapped physical rows — same granularity
-      # as {#add_line}. Cost is O(rendered-rows of the popped lines).
+      # Drops the last `n` hard lines from the buffer — the inverse of building
+      # up a tail with {#append} / {#add_line}, so a caller can `remove` then
+      # `append` to rewrite a damaged tail in place. Operates on **hard lines**
+      # (the `\n`-delimited entries), not wrapped physical rows. `n == 0` and the
+      # empty buffer are no-ops; `n >= hard-line count` empties the buffer.
       # 
       # _@param_ `n` — number of hard lines to drop; must be >= 0.
       def remove_last_n_lines: (Integer n) -> void
 
-      # Replaces a contiguous range of hard lines with the parsed content
-      # of `str`. The replacement is parsed exactly like {#text=} and
-      # {#append}: a {String} is run through {StyledString.parse} (so
-      # embedded ANSI is honored), a {StyledString} is used as-is, `nil`
-      # behaves like an empty replacement (the range is deleted). Embedded
-      # `"\n"` in the replacement produces multiple hard lines, so a single
-      # `replace` can grow or shrink the buffer.
-      # 
-      # `range` selects which hard lines to swap out:
-      # 
-      # - an `Integer` `n` is shorthand for `n..n` (replace one existing
-      #   line — `n` must be in `[0, hard-line count)`);
-      # - a non-empty `Range` of hard-line indices replaces those lines;
-      # - an empty `Range` (e.g. `2...2`, or the canonical end-insertion
-      #   `hard_lines.size...hard_lines.size`) is *insertion* at that
-      #   position — no lines are removed. {#insert} is a thin alias for
-      #   this case.
-      # 
-      # Endpoints must be non-negative integers; `begin` may equal
-      # `hard-line count` (insertion at the end), `end` may not exceed
-      # `hard-line count - 1`. `nil` endpoints (beginless / endless ranges)
-      # are not accepted.
-      # 
-      # Cost is roughly `O(from + length + new content)`: the splice
-      # updates only the affected slice of the physical-row buffer, using
-      # the per-hard-line wrap-count cache to locate the starting offset
-      # without re-wrapping preceding lines. Lines outside the splice are
-      # never re-wrapped. {#top_line} is clamped if the new line count
-      # puts it past the end; {#auto_scroll} pins it to the bottom as
-      # usual. The call is a no-op (no invalidation) when the parsed
-      # replacement equals the covered range (vacuously true for an empty
-      # range plus empty replacement, so `replace(n...n, "")` is a cheap
-      # no-op).
+      # Replaces a contiguous range of hard lines with the parsed content of
+      # `str` (parsed like {#text=}: `String` → {StyledString.parse}, `nil` →
+      # empty, so `nil` deletes the range). Embedded `"\n"` yields multiple hard
+      # lines, so one `replace` can grow or shrink the buffer. `range` selects
+      # which hard lines to swap out:
+      # 
+      # - an `Integer` `n` is shorthand for `n..n` (replace one existing line);
+      # - a non-empty `Range` replaces those lines;
+      # - an empty `Range` (e.g. `2...2`, or `size...size` at the end) is
+      #   *insertion* at that position — nothing removed. {#insert} aliases this.
+      # 
+      # Splices in place — only the affected slice of the physical-row buffer is
+      # touched, no preceding lines re-wrapped (cost O(from + length + new
+      # content)). A no-op when the replacement equals the covered range, so
+      # `replace(n...n, "")` is cheap.
       # 
       # _@param_ `range` — hard-line indices to replace.
       # 
@@ -2463,6 +3580,8 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with padded blanks past the last line), so the
       # "fully draw over your rect" contract is met without an upfront wipe.
+      # Rows go through {Component#draw_line}, so content and blank rows inherit
+      # {Component#effective_bg_color} (a {#bg_color} set here or on an ancestor).
       def repaint: () -> void
 
       # Rewraps the text on width changes. Wrap width depends on
@@ -2547,19 +3666,12 @@ module Tuile
       # _@param_ `region`
       def remove_region: (Region region) -> void
 
-      # Adjusts region line counts after a {@hard_lines} splice that
-      # removed `removed_count` lines at index `from` and inserted
-      # `added_count` in their place. Two passes:
-      # 
-      # 1. Subtract each region's overlap with the removed range (uses
-      #    the original counts to compute positions). Remember the first
-      #    region that lost lines — that's the natural home for the
-      #    replacement content.
-      # 2. Credit `added_count` to that region. For pure insertions (no
-      #    removal), there's no "first overlapping region" to pick from;
-      #    walk regions and credit the latest one starting at `from` (the
-      #    boundary tiebreaker matches the spatial-tail-routing of
-      #    {#append}). Past-the-end inserts fall back to the tail region.
+      # Adjusts region line counts after a {@hard_lines} splice that removed
+      # `removed_count` lines at `from` and inserted `added_count`. Subtracts
+      # each region's overlap with the removed range, then credits the added
+      # lines to the first region that lost lines. Pure insertions have no such
+      # region — they credit the latest region starting at `from`, matching
+      # {#append}'s spatial-tail routing (past-the-end falls back to the tail).
       # 
       # _@param_ `from`
       # 
@@ -2739,14 +3851,9 @@ module Tuile
         def text=: ((String | StyledString)? value) -> void
 
         # Verbatim append into this region's tail. Same semantics as
-        # {TextView#append} but scoped to the region: embedded `"\n"`
-        # creates new hard lines within the region, no-leading-newline
-        # input extends the region's last hard line. Empty / `nil` input
-        # is a no-op (but still raises when detached). When the region is
-        # the spatial tail of the view, this uses the incremental
-        # {TextView#append} path; mid-document regions splice the affected
-        # slice of the physical-row buffer (lines outside the region are
-        # not re-wrapped).
+        # {TextView#append} but scoped: embedded `"\n"` creates new hard lines
+        # within the region, other input extends the region's last hard line.
+        # Empty / `nil` is a no-op (but still raises when detached).
         # 
         # _@param_ `str`
         def append: ((String | StyledString)? str) -> void
@@ -2813,121 +3920,1299 @@ module Tuile
         # _@param_ `n`
         def remove_last_n_lines: (Integer n) -> void
 
-        def detach!: () -> void
+        def detach!: () -> void
+
+        def check_attached: () -> void
+
+        # _@return_ — number of hard lines this region owns. Safe to
+        # read on a detached region (no error raised).
+        attr_accessor line_count: (Integer | untyped)
+      end
+    end
+
+    # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
+    # log lines into this window:
+    # 
+    #   log_window = Tuile::Component::LogWindow.new
+    #   logger = Logger.new(Tuile::Component::LogWindow::IO.new(log_window))
+    # 
+    # Any logger that writes formatted lines to an IO works the same way —
+    # for example `TTY::Logger` configured with the `:console` handler and
+    # `output: LogWindow::IO.new(window)`.
+    class LogWindow < Tuile::Component::Window
+      # _@param_ `caption`
+      def initialize: (?String caption) -> void
+
+      # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
+      # 
+      # _@param_ `string` — the line (or multiple lines) to log.
+      def log: (String? string) -> void
+
+      # IO-shaped adapter that forwards each log line to the owning {LogWindow}.
+      # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
+      # call `output.puts`, e.g. `TTY::Logger`).
+      class IO
+        # _@param_ `window`
+        def initialize: (LogWindow window) -> void
+
+        # _@param_ `string`
+        def write: (String string) -> void
+
+        # _@param_ `string`
+        def puts: (String string) -> void
+
+        # Stdlib `Logger` only treats an object as an IO target when it
+        # responds to both {#write} and {#close}; otherwise it tries to
+        # interpret it as a filename. This is a no-op.
+        def close: () -> void
+      end
+    end
+
+    # A single-line text input with a real hardware caret, scrolling
+    # horizontally to keep that caret in view:
+    # 
+    #   f = TextField.new
+    #   f.rect  = Rect.new(0, 0, 6, 1)   # six columns wide …
+    #   f.text  = "hello world"          # … eleven columns of text, so it scrolls
+    #   f.caret = 11                     # paints "world " — left_column 6, cursor on the last column
+    #   f.caret = 0                      # paints "hello " — left_column 0
+    # 
+    # The field's width never bounds its contents — {#max_text_length} does, and
+    # only for typing.
+    # 
+    # == Implementation details
+    # 
+    # Two axes run through this class and are *not* interchangeable:
+    # 
+    # - an **index** counts characters into {#text} — {#caret},
+    #   {#max_text_length}, `text[i]`, every edit;
+    # - a **column** counts terminal cells — {#rect}, {#left_column},
+    #   {#cursor_position}, a {MouseEvent}.
+    # 
+    # 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
+    # column 6. Every crossing goes through the private `column_at` / `index_at`
+    # pair; adding an index to a column anywhere else is the bug those two exist
+    # to prevent.
+    # 
+    # Indices count characters while widths measure grapheme clusters, but the
+    # caret never falls between the two: {AbstractStringField} keeps it on a
+    # cluster boundary, so a column derived from it always names a real glyph
+    # edge.
+    # 
+    # What gets *painted* is {#display_text}, a third seam that is `text` itself
+    # here and the mask in {PasswordField}. Every column measurement reads it, so
+    # a subclass showing something else overrides that and never {#repaint} —
+    # overriding the paint alone leaves the measurements on the buffer while the
+    # cells show the substitute, and the two drift apart by a growing offset.
+    class TextField < Tuile::Component::AbstractStringField
+      def initialize: () -> void
+
+      def cursor_position: () -> Point?
+
+      # Places the caret at the clicked column. A click on the right half of a
+      # wide glyph lands *after* it, as in any editor.
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # _@param_ `key`
+      def handle_text_input_key: (String key) -> bool
+
+      def on_text_mutated: () -> void
+
+      def on_caret_mutated: () -> void
+
+      def on_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
+      # the rendering of `text[0, i]`, so an override that changes the character
+      # count — or reorders — desynchronizes the caret from the display. Nothing
+      # enforces it at runtime; a subclass pins it with a spec.
+      # 
+      # _@return_ — {#text} itself, unless a subclass substitutes.
+      def display_text: () -> String
+
+      # _@param_ `char`
+      # 
+      # _@return_ — always true — a field at {#max_text_length} swallows the
+      # key rather than declining it, so typing can never fall through to a
+      # scope-wide binding.
+      def insert: (String char) -> bool
+
+      # _@param_ `index` — a {#text} index in `0..text.length`.
+      # 
+      # _@return_ — the column it sits at. An index landing inside a
+      # grapheme cluster measures the whole cluster, putting the caret just
+      # past it.
+      def column_at: (Integer index) -> Integer
+
+      # _@param_ `column` — a text column (0 is the first glyph).
+      # 
+      # _@return_ — the nearest {#text} index — a column falling in a wide
+      # glyph's right half resolves past it.
+      def index_at: (Integer column) -> Integer
+
+      # _@return_ — total display width of {#text}.
+      def text_columns: () -> Integer
+
+      # _@return_ — the windowed text, padded with spaces to `rect.width`.
+      # A wide glyph straddling the right edge is dropped rather than painted
+      # as a half glyph.
+      def visible_text: () -> String
+
+      # Scrolls the minimum needed to keep the caret's column visible.
+      def adjust_left_column: () -> void
+
+      # Snapping *right* is the only safe direction, and not because it shows
+      # more: the caret's own column is always a glyph boundary, so the next
+      # boundary at or after `left_column` can never overshoot it. Snapping left
+      # instead pulls the window's right edge inward, which strands the caret
+      # outside it whenever wide glyphs exactly fill a narrow field.
+      # 
+      # _@param_ `column`
+      # 
+      # _@return_ — the smallest glyph-boundary column `>= column`, so the
+      # window never opens on a wide glyph's right half.
+      def snap_to_glyph_start: (Integer column) -> Integer
+
+      # Optional cap on {#text}'s length **in characters** — a wide glyph counts
+      # once. Typing into a field already at the cap does nothing.
+      # 
+      # Deliberately does not police {#text=}: lowering the cap under an existing
+      # value leaves that value intact rather than silently trimming it.
+      # 
+      # _@return_ — maximum characters, or nil for unbounded (default).
+      attr_accessor max_text_length: Integer?
+
+      # _@return_ — text column drawn in the field's leftmost cell — the
+      # horizontal scroll offset. Follows {#caret}, always on a glyph boundary.
+      attr_reader left_column: Integer
+
+      # Optional callback fired when the UP arrow key is pressed. When set, UP
+      # is consumed by the field; when nil, UP falls through to the parent
+      # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
+      # since `k` is a printable character inserted into {#text}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_key_up: (Proc | Method)?
+
+      # Optional callback fired when the DOWN arrow key is pressed. When set,
+      # DOWN is consumed by the field; when nil, DOWN falls through to the
+      # parent (default behavior). Only triggered by {Keys::DOWN_ARROW}, not by
+      # `j`, since `j` is a printable character inserted into {#text}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_key_down: (Proc | Method)?
+
+      # Optional callback fired when ENTER is pressed. When set, ENTER is
+      # consumed by the field; when nil, ENTER falls through to the parent
+      # (default behavior).
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_enter: (Proc | Method)?
+    end
+
+    # A single-line field whose {#value} is a `Float` (or `nil` when empty) —
+    # the {IntegerField} twin, one Ruby type over. Give it a single-row {#rect}:
+    # 
+    #   field = Component::FloatField.new
+    #   field.on_value_change = ->(x) { puts x.inspect }  # Float or nil, per change
+    #   field.value = 19.99                               # field shows "19.99"
+    #   field.clear                                       # empties it; value => nil
+    # 
+    # Only `0`–`9`, one leading `-` and one `.` can be typed; any other
+    # printable key is dropped without moving the caret. Up/Down step by `1.0`
+    # (an empty field counting as `0.0`). A `Float` is a binary double, so this
+    # is the wrong field for money — hold that as `Integer` cents in an
+    # {IntegerField} — and range checks (`min`/`max`) belong to a forms layer,
+    # not here.
+    # 
+    # == Implementation details
+    # {#value} is a *derived parse*: the buffer is the single source of truth,
+    # recomputed on read and left exactly as typed (`"007"` keeps its zeros).
+    # It reads `nil` for a buffer that isn't a number (`""`, a lone `"-"`) but
+    # `1.0` / `0.5` for a half-typed `"1."` / `".5"`, so reaching for the
+    # decimal point doesn't blink the value to `nil` and back through
+    # {#on_value_change} — which fires per keystroke, but only on a real *value*
+    # change (`"7"`→`"07"` is silent). The parse also accepts the exponent
+    # `Float#to_s` writes for extreme magnitudes, so `value = 1e-5` round-trips
+    # through the `"1.0e-05"` it displays, though no key types an `e`.
+    # 
+    # It *composes* a {TextField} (its single {HasContent} child) rather than
+    # subclassing one, so its face carries only the typed {HasValue} seam, never
+    # the widget's `String`-typed `text`.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class FloatField < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+      NUMERIC: Regexp
+
+      def initialize: () -> void
+
+      # _@return_ — the parsed buffer; `nil` when empty or not a
+      # number (e.g. a lone `"-"`).
+      def value: () -> Float?
+
+      # Writes `new_value` into the buffer and parks the caret at its end; fires
+      # {#on_value_change} only if the value actually changed.
+      # 
+      # _@param_ `new_value` — `nil` empties the field; anything else is coerced with `Float()`, so an `Integer` `3` shows as `"3.0"`.
+      def value=: (Numeric? new_value) -> void
+
+      # `nil`, not `""`: a numeric field with no parseable number is empty.
+      def empty_value: () -> void
+
+      # _@return_ — the field's caret (the hardware cursor is delegated
+      # to the inner field).
+      def cursor_position: () -> Point?
+
+      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      def on_enter: () -> (Proc | Method)?
+
+      # _@param_ `callback`
+      def on_enter=: ((Proc | Method)? callback) -> void
+
+      # Places the wrapped field across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `field`
+      def layout: (Component field) -> void
+
+      # _@param_ `new_value`
+      def coerce: (Numeric new_value) -> Float
+
+      # The field's key interceptor, consulted *before* the field acts on the
+      # key — which is what lets a rejected character be swallowed without the
+      # caret ever moving.
+      # 
+      # _@param_ `key`
+      # 
+      # _@return_ — true to consume the key.
+      def field_key: (String key) -> bool
+
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as
+      # `0.0`.
+      # 
+      # _@param_ `delta`
+      def step: (Float delta) -> void
+
+      # Whether `char` may be inserted. Deliberately shallow: it keeps the
+      # buffer *typeable* rather than always-valid — a transient `"-"` or
+      # `"1."` has to be reachable — and {#value} decides what parses.
+      # 
+      # _@param_ `char` — a single printable character.
+      def accepts?: (String char) -> bool
+
+      # Re-emits {#on_value_change} with the freshly-parsed {#value}, but only
+      # when it differs from the last one fired — so a buffer edit that leaves
+      # the value unchanged (`"7"`→`"07"`) stays silent.
+      def fire_if_changed: () -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+    end
+
+    # The chrome text a component *wears* — a {Window}'s border title, a
+    # {Button}'s label — as opposed to the value it *holds*.
+    # 
+    #   button.caption = "Submit"
+    #   window.caption = StyledString.styled("Settings", fg: Color::RED)
+    # 
+    # Tuile's naming split, which decides what a new component gets:
+    # **caption** is chrome, authored by the app; **text** is the value the
+    # user edits (aliased to {HasValue#value} on {AbstractStringField}). A
+    # component may carry both, hence two mixins.
+    # 
+    # Includers own the *rendering* — clipping, width arithmetic, decoration
+    # such as {Window}'s `[key]-` shortcut prefix; this holds only the text.
+    # 
+    # == Implementation details
+    # Being a mixin is what lets tree-walking code find "the {Button} captioned
+    # Submit" via `is_a?(HasCaption)` plus a caption compare, rather than a
+    # hardcoded list of classes that happen to respond to `caption`. Don't
+    # collapse it back into per-class accessors.
+    module HasCaption
+      # Read through *this* method, never `@caption` — the ivar stays nil until
+      # the first non-empty set ({#caption=} short-circuits when unchanged).
+      # 
+      # _@return_ — the caption; empty when never set.
+      def caption: () -> StyledString
+
+      # Sets the caption and invalidates the component. No-op when unchanged. A
+      # `String` is parsed via {StyledString.parse} (embedded ANSI is honored);
+      # a {StyledString} is used as-is; `nil` clears it.
+      # 
+      # _@param_ `new_caption`
+      def caption=: ((String | StyledString)? new_caption) -> void
+    end
+
+    # A mixin interface for a component with one child tops. The host must
+    # provide a protected `layout(content)` method which repositions the
+    # content component; the mixin manages `@content` itself.
+    module HasContent
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+
+      # _@return_ — the current content component.
+      attr_accessor content: Component?
+    end
+
+    # A {Window} preconfigured with a {List} of static lines. Useful for
+    # showing read-only information.
+    # 
+    # Usable tiled (just add to a {Layout}) or as a popup via {.open}, which
+    # wraps it in a {Popup}.
+    class InfoWindow < Tuile::Component::Window
+      # _@param_ `caption`
+      # 
+      # _@param_ `lines` — initial content; each entry may contain Rainbow formatting.
+      def initialize: (?String caption, ?::Array[String] lines) -> void
+
+      # Opens the info window as a popup.
+      # 
+      # _@param_ `caption`
+      # 
+      # _@param_ `lines` — the content, may contain formatting.
+      # 
+      # _@param_ `size` — the popup's size, applied top-down; the list wraps and scrolls within it. Defaults to {Fraction::HALF}.
+      # 
+      # _@return_ — the opened popup.
+      def self.open: (String caption, ::Array[String] lines, ?size: (Size | Fraction)) -> Popup
+    end
+
+    # Single-select from a set of typed items, one row each. Arrows move a
+    # cursor; Space, Enter or a left click selects the row under it:
+    # 
+    #    (*) Ascending
+    #    ( ) Descending    <- cursor row, highlighted across the full width
+    #    ( ) Unsorted
+    #   ^ the composed {List}'s one-column gutter
+    # 
+    #   rg = Component::RadioGroup.new(items: %w[Ascending Descending Unsorted])
+    #   rg.value = "Descending"                      # or seed it via the ctor
+    #   rg.on_value_change = ->(order) { resort(order) }
+    #   rg.value                                     # => "Descending"
+    #   rg.item_label = ->(o) { o.title }            # default :to_s
+    # 
+    # {#value} is **the selected item itself** — of whatever type {#items}
+    # holds, never its label. `nil` means nothing is selected: that is the
+    # initial state, and assigning it is the only way back, since Space on the
+    # already-selected row is a no-op rather than a deselect.
+    # 
+    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
+    # {HasContent} child, which is where the cursor, scrolling, the scrollbar
+    # and per-row mouse hit-testing come from. `content` is that list, so an app
+    # can tune it (`scrollbar_visibility`, `show_cursor_when_inactive`, …). Rows
+    # beyond {#rect}'s height scroll; the inner list is the tab stop, not the
+    # group.
+    # 
+    # == The cursor is chrome
+    # The cursor and the selection are two independent things, as in
+    # {CheckboxGroup} — arrows roam without changing {#value}, so a listener
+    # that resorts a pane fires once on intent instead of once per row crossed.
+    # {#value=} therefore does *not* move the cursor. An app that wants it
+    # parked on the selection parks it:
+    # 
+    #   rg.content.cursor = List::Cursor.new(position: rg.items.index(rg.value))
+    # 
+    # {#items=} is the one thing that moves it, clamping it back into range.
+    # 
+    # == +items+ is chrome; +value+ is authoritative
+    # {#items=} changes only what is *presented*. It never touches {#value} and
+    # never fires {HasValue#on_value_change}, and a selected item absent from
+    # {#items} renders no marked row while surviving intact — so a form saved
+    # without the user editing anything changes nothing silently. Keeping the
+    # two in sync is the app's job. Same contract as {ComboBox#value} and
+    # {CheckboxGroup#value}.
+    # 
+    # == Implementation details
+    # Two `==`-equal items share one selection, so selecting either marks both
+    # rows; two *distinct* items that merely render the same label stay
+    # independent, because a row resolves to an item by index.
+    # 
+    # Rows are `(*) `/`( ) ` literals, mirroring {Checkbox}'s convention rather
+    # than importing constants from it. ASCII deliberately: `(•)` would measure
+    # two columns in a terminal configured for East-Asian-Ambiguous glyphs and
+    # shift every row's text, which no test would catch.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class RadioGroup < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+
+      # _@param_ `items` — the items to present, one row each; also settable via {#items=}.
+      # 
+      # _@param_ `value` — the initially selected item. Seeds the backing ivar directly, so no listener fires and assignment order doesn't matter to a form helper.
+      def initialize: (?items: ::Array[untyped], ?value: Object?) -> void
+
+      # Selects `new_value`, firing {HasValue#on_value_change} when it really
+      # changed. The cursor stays where it is.
+      # 
+      # _@param_ `new_value` — `nil` selects nothing; an item outside {#items} is kept but renders no marked row.
+      def value=: (Object? new_value) -> void
+
+      # Selects the cursor row on Space. Nothing else is claimed: the composed
+      # {List} — being the focused component — has already had its chance at the
+      # key (its arrows, Home/End, PgUp/PgDn, ^U/^D and Enter), and whatever
+      # neither of us wants bubbles on to an ancestor.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Places the composed list across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `list`
+      def layout: (Component list) -> void
+
+      # Selects the item on row `index`; an index outside {#items} is ignored.
+      # 
+      # _@param_ `index`
+      def select_at: (Integer index) -> void
+
+      # Re-renders every row from the current items, labels and selection.
+      def rebuild_rows: () -> void
+
+      # Pulls an over-range cursor back onto the last row (row 0 when there are
+      # none). {List#lines=} leaves a stale cursor alone, which would strand it
+      # off-content: no highlight, a dead Enter, and a Space that resolves to
+      # `nil` and silently clears the selection.
+      def clamp_cursor: () -> void
+
+      # _@param_ `item`
+      # 
+      # _@return_ — whichever {StyledString#+} accepts on the
+      # right — so a styled label keeps its spans and a plain one is parsed.
+      def label_for: (Object item) -> (StyledString | String)
+
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # _@return_ — the value {#empty?}/{#clear} treat as empty; `nil`
+      # unless an includer overrides it.
+      def empty_value: () -> Object
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+
+      # _@return_ — the presented items.
+      attr_accessor items: ::Array[untyped]
+
+      # _@return_ — item -> row label (a `String`, {StyledString}, or
+      # anything with `#to_s`); `:to_s` by default.
+      attr_accessor item_label: (Proc | Method)
+    end
+
+    # A one-row progress bar: a run of `█` growing left to right across {#rect},
+    # over a `░` track.
+    # 
+    #   ████████░░░░░░░░░░░░
+    # 
+    #   bar   = Component::ProgressBar.new(range: 0..files.size)
+    #   label = Component::Label.new
+    #   add(bar)
+    #   add(label)
+    # 
+    #   def rect=(new_rect)             # the enclosing Layout positions both
+    #     super
+    #     bar.rect   = Rect.new(rect.left, rect.top, rect.width, 1)
+    #     label.rect = Rect.new(rect.left, rect.top + 1, rect.width, 1)
+    #   end
+    # 
+    #   bar.value  = done
+    #   label.text = "#{bar.percent}% — #{done}/#{files.size}"
+    # 
+    # The bar paints no text of its own: put a {Label} beside it and feed it
+    # {#percent} or {#fraction}, so the app words it ("42% — 3/7 files") and
+    # places it freely. Display-only — not focusable, no keys, no mouse.
+    # 
+    # While the total is still unknown, {#indeterminate=} swaps the fill for a
+    # block sliding across the bar:
+    # 
+    #   ░░░░░░░████░░░░░░░░░
+    # 
+    # Both endpoints are exact: the bar is full only at {#max} and empty only at
+    # {#min}, so a full bar always means done. Assign a one-row {#rect}; a taller
+    # one paints the bar on its first row and leaves the rest to the background.
+    # 
+    # == Implementation details
+    # 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
+    # beats a third convention, and if that bet is ever reversed both swap
+    # together.
+    class ProgressBar < Component
+      DEFAULT_RANGE: ::Range[untyped]
+      INDETERMINATE_FPS: Integer
+      BLOCK_DIVISOR: Integer
+
+      # _@param_ `range` — initial {#range=}.
+      # 
+      # _@param_ `value` — initial {#value=}; `nil` starts at the range's lower bound.
+      # 
+      # _@param_ `indeterminate` — initial {#indeterminate=}.
+      def initialize: (?range: ::Range[untyped], ?value: Numeric?, ?indeterminate: bool) -> void
+
+      # _@return_ — the scale {#value} is measured against.
+      def range: () -> ::Range[untyped]
+
+      # Replaces the scale, re-clamping {#value} into it. `min == max` is legal
+      # and reads as complete — a zero-length job has nothing outstanding — so
+      # `bar.range = 0..files.size` needs no special case for an empty list.
+      # 
+      # _@param_ `new_range` — inclusive; endpoints Numeric and finite.
+      def range=: (::Range[untyped] new_range) -> void
+
+      # _@return_ — {#value} as `0.0..1.0`. `1.0` when the range is empty.
+      def fraction: () -> Float
+
+      # _@return_ — {#fraction} as `0..100`, floored — `100` means done and
+      # nothing else does, matching the painted bar exactly.
+      def percent: () -> Integer
+
+      # _@return_ — whether the sliding-block animation is showing.
+      def indeterminate?: () -> bool
+
+      # Switches between the fill and the sliding block. {#value} keeps working
+      # while indeterminate — it is simply not painted — so switching back shows
+      # the progress that accumulated meanwhile.
+      # 
+      # The animation only runs while the bar is {Component#attached? attached},
+      # and stops on detach. It also keeps the event loop awake at
+      # {INDETERMINATE_FPS}, so turn it off (or remove the bar) when the job ends.
+      # 
+      # _@param_ `flag` — coerced; truthiness decides.
+      def indeterminate=: (bool flag) -> void
+
+      def on_attached: () -> void
+
+      def on_detached: () -> void
+
+      # Paints the bar on the first row of {#rect} and blanks the rest.
+      # 
+      # Deliberately not `super`: {Component#repaint}'s default blanks the
+      # *whole* rect, which dirties every cell of the bar's own row before it is
+      # painted over — so {Buffer#flush} re-emits the entire row every frame
+      # instead of the one or two cells that actually moved.
+      def repaint: () -> void
+
+      # Filled cells out of `steps` — the rect width when painting, 100 for
+      # {#percent}, so the bar and a {Label} showing the percentage can never
+      # disagree about being done.
+      # 
+      # _@param_ `steps`
+      def scale: (Integer steps) -> Integer
+
+      # _@param_ `width` — columns available.
+      # 
+      # _@return_ — the row, `width` glyphs wide.
+      def glyphs: (Integer width) -> String
+
+      # Where the sliding block sits this frame: it enters at the left edge and
+      # leaves at the right, one cell per frame, then loops. The period is one
+      # short of `width + block` so at least one cell is always lit — a full
+      # `width + block` blanks the bar for exactly one frame per cycle.
+      # 
+      # _@param_ `width` — columns available.
+      # 
+      # _@return_ — start column and length, clipped.
+      def block_at: (Integer width) -> [Integer, Integer]
+
+      def resolved_bar_color: () -> Color?
+
+      # Brings the ticker in line with "animating and on screen". The sole writer
+      # of `@ticker`, and idempotent, so the attach/detach hooks and
+      # {#indeterminate=} are all the same call and a repeated `indeterminate =
+      # true` cannot start a second one.
+      def sync_ticker: () -> void
+
+      # _@return_ — lower bound of {#range}.
+      attr_reader min: Float
+
+      # _@return_ — upper bound of {#range}.
+      attr_reader max: Float
+
+      # _@return_ — the value as set, so a {Theme::Ref} comes back
+      # unresolved. Both glyphs paint in it; `nil` (the default) is the
+      # terminal's default foreground.
+      attr_accessor bar_color: (Color | Theme::Ref | Symbol | Integer | ::Array[Integer])?
+
+      # _@return_ — the progress, clamped into {#range} when assigned — so
+      # `bar.value = 999` on a `0..250` bar reads back as `250.0`.
+      attr_accessor value: (Float | Numeric)
+    end
+
+    # A single-line field whose {#value} is an `Integer` (or `nil` when empty).
+    # The user may type only `0`–`9` and a single leading `-`; anything else is
+    # silently rejected without moving the caret. Up/Down step the value by one
+    # (an empty field counting as `0`). An empty or otherwise un-parseable
+    # buffer reads back as `nil`:
+    # 
+    #   field = Component::IntegerField.new
+    #   field.on_value_change = ->(n) { puts n.inspect }  # Integer or nil, per change
+    #   field.value = 42                                   # field shows "42"
+    #   field.value                                        # => 42
+    #   field.clear                                        # empties it; value => nil
+    # 
+    # Like {ComboBox}, it *composes* a {TextField} (its single {HasContent}
+    # child) rather than subclassing one — its face carries only the typed
+    # {HasValue} value seam, never the widget's `String`-typed `text`. It's the
+    # same wrapper shape as {ComboBox} minus the dropdown: a digit-filtered text
+    # field re-exposed as a typed input. Give it a single-row {#rect}.
+    # 
+    # == The value is a *derived parse* of the buffer
+    # {#value} is `Integer(buffer, 10)` (or `nil`), recomputed on read — the
+    # buffer is the single source of truth, {#value=} just writes it. So `"-"`
+    # alone and `""` both read as `nil`, and `on_value_change` fires eagerly
+    # once per real *value* change: typing `0`→`7` in `"07"` shifts the buffer
+    # but not the value (`7`), so it does not fire. No normalization — a typed
+    # `"007"` stays `"007"` on screen though its value is `7`.
+    # 
+    # `min`/`max`, a `+` sign, and thousands separators are deliberately out of
+    # scope (range and formatting are a forms concern).
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class IntegerField < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+
+      def initialize: () -> void
+
+      # _@return_ — the parsed buffer; `nil` when empty or not a
+      # valid integer (e.g. a lone `"-"`).
+      def value: () -> Integer?
+
+      # Writes `new_value` into the buffer and parks the caret at its end; fires
+      # {#on_value_change} only if the value actually changed.
+      # 
+      # _@param_ `new_value` — `nil` empties the field.
+      def value=: (Integer? new_value) -> void
+
+      # `nil`, not `""`: an integer field with no parseable number is empty.
+      def empty_value: () -> void
+
+      # _@return_ — the field's caret (the hardware cursor is delegated
+      # to the inner field).
+      def cursor_position: () -> Point?
+
+      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      def on_enter: () -> (Proc | Method)?
+
+      # _@param_ `callback`
+      def on_enter=: ((Proc | Method)? callback) -> void
+
+      # Places the wrapped field across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `field`
+      def layout: (Component field) -> void
+
+      # The field's key interceptor, consulted *before* the field acts on the
+      # key: Up/Down step the value; a printable key the field mustn't accept is
+      # swallowed (so a rejected key never moves the caret); everything else —
+      # digits, the leading sign, and all editing/navigation keys — falls
+      # through.
+      # 
+      # _@param_ `key`
+      # 
+      # _@return_ — true to consume the key.
+      def field_key: (String key) -> bool
+
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as `0`.
+      # 
+      # _@param_ `delta`
+      def step: (Integer delta) -> void
+
+      # A digit anywhere, or a `-` only as the very first character.
+      # 
+      # _@param_ `char` — a single printable character.
+      def accepts?: (String char) -> bool
+
+      # Re-emits {#on_value_change} with the freshly-parsed {#value}, but only
+      # when it differs from the last one fired — so a buffer edit that leaves
+      # the value unchanged (`"7"`→`"07"`) stays silent.
+      def fire_if_changed: () -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+    end
+
+    # A borderless, tinted, non-focusable floating selection list — the dropdown
+    # a *driver* drops open, drives by forwarding movement keys, and commits a
+    # pick from: a non-modal {Popup} wrapping a {List} that never takes focus, so
+    # focus stays on the driver while the caller refills the rows, moves the
+    # highlight, and reads the pick.
+    # 
+    #   drop = Component::ListDropdown.new
+    #   drop.on_item_chosen = ->(index, _line) { commit(index) } # caller commits
+    #   # …then, from the driver's key handler:
+    #   drop.lines = matches.map { |m| render(m) }   # caller filters + renders
+    #   drop.anchor_to(rect, rows: matches.size)     # below the driver, or flipped
+    #   drop.open
+    #   return true if drop.move(key)  # Up/Down/PgUp/PgDn/^U/^D → list scroll
+    #   drop.choose if key == Keys::ENTER            # commit the highlight
+    # 
+    # It owns only what every such dropdown shares — *placement* included, via
+    # {#anchor_to}. What stays with the driver: the width **policy** ({#anchor_to}
+    # measures nothing itself), filtering, row rendering, the commit action, and
+    # ESC/Enter handling. ESC and Enter carry driver-specific tails (ESC may
+    # revert a query; Enter may commit via {#choose} *or* via a separate submit
+    # path), so {#move} claims neither — the driver calls {#choose} and {#close}
+    # from its own branches.
+    # 
+    # == Theming
+    # Borderless, told apart from the content beneath by a background tint —
+    # {Theme#input_bg_color} by default, assigned as a live {Theme::Ref} so it
+    # tracks light/dark flips with no hook. Reassign {Component#bg_color=} for a
+    # different tint (a `Theme.ref(:token)` keeps the flip-tracking).
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class ListDropdown < Tuile::Component::Popup
+      MOVE_KEYS: ::Array[String]
+      MAX_VISIBLE_ROWS: Integer
+
+      def initialize: () -> void
+
+      # _@param_ `lines` — the rows to show; see {List#lines=}.
+      def lines=: (::Array[untyped] lines) -> void
+
+      # _@return_ — the current rows.
+      def lines: () -> ::Array[StyledString]
+
+      # _@param_ `proc` — commit callback; see {List#on_item_chosen}.
+      def on_item_chosen=: ((Proc | Method)? proc) -> void
+
+      # _@param_ `cursor` — the highlight; see {List#cursor=}.
+      def cursor=: (List::Cursor cursor) -> void
+
+      # _@return_ — the list's cursor (the current highlight).
+      def cursor: () -> List::Cursor
+
+      # Sizes and places the dropdown against `anchor`: directly beneath it,
+      # flipped above when `rows` won't fit below, clamped — with the list
+      # scrolling — when neither side has room. Horizontally the left edges line
+      # up, sliding left only far enough to keep the panel on screen.
+      # 
+      #   drop.anchor_to(field.rect, rows: matches.size)            # field width
+      #   drop.anchor_to(rect, rows: items.size, width: measured)   # own width
+      # 
+      # Vertical flips but horizontal slides because covering the driver would
+      # hide what is being chosen, while sharing its columns is the point.
+      # 
+      # _@param_ `anchor` — the driver's rect; the dropdown never covers it.
+      # 
+      # _@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. Defaults to the anchor's, which lines both edges up with a field; a driver that measured its labels passes its own. A label wider than the screen clips — {List} has no horizontal scrolling.
+      # 
+      # _@param_ `max_rows` — rows shown before the list scrolls.
+      def anchor_to: (
+                       Rect anchor,
+                       rows: Integer,
+                       ?width: Integer,
+                       ?max_rows: Integer
+                     ) -> void
+
+      # Forwards a cursor-movement key to the list. The driver calls this from
+      # its own key handler; a truthy return means "consumed — stop here", falsy
+      # means "not mine — proceed with normal editing/dispatch". Only {MOVE_KEYS}
+      # are claimed, and only while open.
+      # 
+      # _@param_ `key`
+      # 
+      # _@return_ — true iff the key was consumed.
+      def move: (String key) -> bool
+
+      # Commits the highlighted row by firing {List#on_item_chosen}, exactly as
+      # pressing Enter on the focused list would — the driver calls this from its
+      # own Enter branch.
+      # 
+      # _@return_ — true iff a row was chosen (false when the cursor is
+      # off-content).
+      def choose: () -> bool
+
+      # The dropdown's {List}. Non-focusable on purpose: the driver forwards keys
+      # while focus stays on it, and a mouse click selects an item without
+      # stealing focus — so a driving text input never loses its caret
+      # mid-interaction.
+      class Menu < Tuile::Component::List
+        def focusable?: () -> bool
+
+        def tab_stop?: () -> bool
+      end
+    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.
+    # 
+    # 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.
+    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
+
+      # Handles an option-key press. Reached by bubbling: the inner {List}
+      # (the focused component) sees the key first and handles cursor/Enter
+      # picks; anything it declines bubbles up here, where a key matching an
+      # option's `key` picks that option.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      def keyboard_hint: () -> String
+
+      # Opens a picker as a popup. Picking an option fires `block`, then
+      # closes the popup; ESC / `q` close without firing `block`.
+      # 
+      # _@param_ `caption`
+      # 
+      # _@param_ `options`
+      # 
+      # _@return_ — the wrapping popup.
+      def self.open: (String caption, ::Array[[String, String]] options) ?{ (String key) -> void } -> Popup
+
+      # _@param_ `key`
+      def select_option: (String key) -> void
+
+      # Callback invoked after the user picks an option (after the block
+      # fires). The {Popup} returned by {.open} sets this to its own `close`.
+      attr_accessor on_pick: Proc?
+
+      # One picker option.
+      # 
+      # @!attribute [r] key
+      #   @return [String] the keyboard key that picks this option.
+      # @!attribute [r] caption
+      #   @return [String] the option caption.
+      class Option
+        # _@return_ — the keyboard key that picks this option.
+        attr_reader key: String
+
+        # _@return_ — the option caption.
+        attr_reader caption: String
+      end
+    end
+
+    # Multi-select from a set of typed items, one checkable row each. Arrows move
+    # a cursor; Space, Enter or a left click toggles the row under it:
+    # 
+    #    [x] Errors
+    #    [ ] Warnings     <- cursor row, highlighted across the full width
+    #    [x] Info
+    #   ^ the composed {List}'s one-column gutter
+    # 
+    #   cg = Component::CheckboxGroup.new(items: %w[Errors Warnings Info])
+    #   cg.value = %w[Errors Info]                    # any Enumerable, stored as a Set
+    #   cg.on_value_change = ->(set) { filter(set) }   # once per toggle
+    #   cg.value                                       # => #<Set: {"Errors", "Info"}>
+    #   cg.item_label = ->(level) { level.name }       # default :to_s
+    # 
+    # {#value} is a **frozen `Set` of the selected items themselves** — of
+    # whatever type {#items} holds, never their labels. Frozen so `cg.value <<
+    # item` fails loudly rather than mutating the selection behind
+    # {HasValue#on_value_change}'s back; assign a new set or an `Array` instead.
+    # Treat it as *unordered*: it iterates in toggle order, so use
+    # `cg.items & cg.value.to_a` when you need {#items} order.
+    # 
+    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
+    # {HasContent} child, which is where the cursor, scrolling, the scrollbar and
+    # per-row mouse hit-testing come from. `content` is that list, so an app can
+    # tune it (`scrollbar_visibility`, `show_cursor_when_inactive`, …). Rows
+    # beyond {#rect}'s height scroll; the inner list is the tab stop, not the
+    # group.
+    # 
+    # == +items+ is chrome; +value+ is authoritative
+    # {#items=} changes only what is *presented*. It never touches {#value} and
+    # never fires {HasValue#on_value_change}, and a selected item absent from
+    # {#items} renders no checked row while surviving intact — so a form saved
+    # without the user editing anything changes nothing silently. Keeping the two
+    # in sync is the app's job: `cg.value &= cg.items.to_set` reconciles them.
+    # Same contract as {ComboBox#value}, one item at a time.
+    # 
+    # There is no select-all — neither a key nor a header row. An app that wants
+    # one writes `cg.value = cg.items` behind its own affordance.
+    # 
+    # == Implementation details
+    # Items need stable `#hash`/`#eql?`, since the selection is a `Set`: an item
+    # mutated after being selected becomes unfindable. Two `==`-equal items also
+    # share one selection — their rows check and uncheck together — whereas two
+    # *distinct* items that merely render the same label toggle independently,
+    # because a row resolves to an item by index.
+    # 
+    # Rows repeat {Checkbox}'s `[x] `/`[ ] ` glyph convention rather than
+    # importing a constant from it.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class CheckboxGroup < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+      EMPTY_SELECTION: ::Set[untyped]
+
+      # _@param_ `items` — the items to present, one row each; also settable via {#items=}.
+      # 
+      # _@param_ `value` — the initial selection. Seeds the backing ivar directly, so no listener fires and assignment order doesn't matter to a form helper.
+      def initialize: (?items: ::Array[untyped], ?value: ::Enumerable[untyped]?) -> void
+
+      # _@return_ — the frozen empty set — {HasValue#empty?} means nothing is
+      # selected.
+      def empty_value: () -> ::Set[untyped]
+
+      # Replaces the selection, firing {HasValue#on_value_change} when it really
+      # changed. Stores a frozen `Set` *copy*, so a set the caller goes on
+      # mutating can't reach in.
+      # 
+      # _@param_ `new_value` — `nil` selects nothing.
+      def value=: (::Enumerable[untyped]? new_value) -> void
+
+      # Toggles the cursor row on Space. Nothing else is claimed: the composed
+      # {List} — being the focused component — has already had its chance at the
+      # key (its arrows, Home/End, PgUp/PgDn, ^U/^D and Enter), and whatever
+      # neither of us wants bubbles on to an ancestor.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Places the composed list across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `list`
+      def layout: (Component list) -> void
+
+      # Flips membership of the item on row `index`; an index outside {#items} is
+      # ignored.
+      # 
+      # _@param_ `index`
+      def toggle_at: (Integer index) -> void
+
+      # Re-renders every row from the current items, labels and selection.
+      def rebuild_rows: () -> void
+
+      # _@param_ `new_value`
+      # 
+      # _@return_ — a frozen copy; `nil` becomes {#empty_value}.
+      def coerce: (::Enumerable[untyped]? new_value) -> ::Set[untyped]
+
+      # _@param_ `item`
+      # 
+      # _@return_ — whichever {StyledString#+} accepts on the
+      # right — so a styled label keeps its spans and a plain one is parsed.
+      def label_for: (Object item) -> (StyledString | String)
+
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
 
-        def check_attached: () -> void
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
 
-        # _@return_ — number of hard lines this region owns. Safe to
-        # read on a detached region (no error raised).
-        attr_accessor line_count: (Integer | untyped)
-      end
+      def on_focus: () -> void
+
+      # _@return_ — the presented items.
+      attr_accessor items: ::Array[untyped]
+
+      # _@return_ — item -> row label (a `String`, {StyledString}, or
+      # anything with `#to_s`); `:to_s` by default.
+      attr_accessor item_label: (Proc | Method)
     end
 
-    # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
-    # log lines into this window:
+    # A {TextField} that paints one mask glyph per character instead of the
+    # text. Editing, caret, clicks and horizontal scrolling are the field's,
+    # unchanged:
     # 
-    #   log_window = Tuile::Component::LogWindow.new
-    #   logger = Logger.new(Tuile::Component::LogWindow::IO.new(log_window))
+    #   pf = Component::PasswordField.new
+    #   pf.rect  = Rect.new(0, 0, 20, 1)
+    #   pf.value                          # => the plaintext String
+    #   pf.mask_char = "•"                # default "*"
+    #   pf.revealed  = true               # show the plaintext, e.g. behind a Checkbox
     # 
-    # Any logger that writes formatted lines to an IO works the same way —
-    # for example `TTY::Logger` configured with the `:console` handler and
-    # `output: LogWindow::IO.new(window)`.
-    class LogWindow < Tuile::Component::Window
-      # _@param_ `caption`
-      def initialize: (?String caption) -> void
+    # A password's value *is* its text, so this subclasses {TextField} rather
+    # than composing one the way {IntegerField} does — the delta is presentation
+    # only, and it lands entirely on {TextField#display_text}.
+    # 
+    # == What it hides, and what it doesn't
+    # The plaintext is an ordinary Ruby `String`: not pinned, not wiped, not
+    # kept out of GC. Anything stronger needs a frozen-buffer type and the
+    # cooperation of every consumer, which is out of scope for a widget.
+    # 
+    # The mask shows the text's *length* — accepted, since a caret has to sit
+    # somewhere. Its *word structure* is hidden: CTRL+LEFT / CTRL+RIGHT jump to
+    # the ends while masked instead of hopping the spaces a watcher could then
+    # read off the caret. They resume word-jumping when {#revealed}.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class PasswordField < Tuile::Component::TextField
+      def initialize: () -> void
 
-      # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
-      # 
-      # _@param_ `string` — the line (or multiple lines) to log.
-      def log: (String? string) -> void
+      # _@return_ — {#revealed} in predicate form.
+      def revealed?: () -> bool
 
-      # IO-shaped adapter that forwards each log line to the owning {LogWindow}.
-      # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
-      # call `output.puts`, e.g. `TTY::Logger`).
-      class IO
-        # _@param_ `window`
-        def initialize: (LogWindow window) -> void
+      # _@return_ — the mask, one glyph per character, unless {#revealed}.
+      def display_text: () -> String
 
-        # _@param_ `string`
-        def write: (String string) -> void
+      # _@param_ `char`
+      def single_cluster?: (String char) -> bool
 
-        # _@param_ `string`
-        def puts: (String string) -> void
+      # _@return_ — caret target for CTRL+LEFT: the start, while masked.
+      def word_left: () -> Integer
 
-        # Stdlib `Logger` only treats an object as an IO target when it
-        # responds to both {#write} and {#close}; otherwise it tries to
-        # interpret it as a filename. This is a no-op.
-        def close: () -> void
-      end
+      # _@return_ — caret target for CTRL+RIGHT: the end, while masked.
+      def word_right: () -> Integer
+
+      # _@return_ — the glyph painted per character; `"*"` by default.
+      attr_accessor mask_char: String
+
+      # _@return_ — whether the plaintext is shown; `false` by default.
+      attr_accessor revealed: (bool | Object)
     end
 
-    # A single-line text input field with hardware-cursor caret.
-    # 
-    # The field does not scroll. Any keystroke that would make {#text} longer
-    # than `rect.width - 1` (the last column is reserved for the caret past the
-    # last char) is rejected.
-    # 
-    # The caret is a logical index in `0..text.length`. The hardware cursor is
-    # positioned by {Screen} after each repaint cycle when this component is
-    # focused; see {Component#cursor_position}.
-    class TextField < Tuile::Component::TextInput
+    # A single-line field whose {#value} is a `BigDecimal` (or `nil` when
+    # empty) — the numeric field for money, where {FloatField}'s binary double
+    # would round. Give it a single-row {#rect}:
+    # 
+    #   price = Component::BigDecimalField.new
+    #   price.on_value_change = ->(d) { total.value = d }   # BigDecimal or nil
+    #   price.value = BigDecimal("19.99")                   # field shows "19.99"
+    #   price.value = 19.99                                 # ArgumentError: a Float can't be exact
+    # 
+    # Only `0`–`9`, one leading `-` and one `.` can be typed; any other
+    # printable key is dropped without moving the caret. Up/Down step by one.
+    # Range checks (`min`/`max`) and a display scale (`19.9` → `19.90`) belong
+    # to a forms layer, not here — nothing rounds or pads what you typed.
+    # 
+    # Requires the `bigdecimal` gem, which Tuile does *not* depend on: it is a
+    # bundled gem from Ruby 3.4 on, so a `Gemfile` naming it is what puts it on
+    # the load path. Referencing this class without it raises `LoadError`.
+    # 
+    # == Implementation details
+    # {#value} is a *derived parse*: the buffer is the single source of truth,
+    # recomputed on read and left exactly as typed (`"19.90"` keeps its zero,
+    # which `BigDecimal#to_s` would not). It reads `nil` for a buffer that
+    # isn't a number (`""`, a lone `"-"`) but `1` / `0.5` for a half-typed
+    # `"1."` / `".5"`, so reaching for the decimal point doesn't blink the
+    # value to `nil` and back through {#on_value_change} — which fires per
+    # keystroke, but only on a real *value* change (`"1.0"`→`"1.00"` is silent,
+    # since the two compare equal).
+    # 
+    # Both ends of that round-trip are written here rather than left to the
+    # library, because `bigdecimal` 3.1 (Ruby 3.3's default gem) and 4.x
+    # disagree about them: 3.1 rejects `BigDecimal("1.")` and `BigDecimal(0.1)`
+    # where 4.x accepts both. So the buffer is normalized before parsing, a
+    # `Float` is refused on both, and display goes through `to_s("F")` — plain
+    # notation, never `BigDecimal#to_s`'s `"0.1999e2"`.
+    # 
+    # It *composes* a {TextField} (its single {HasContent} child) rather than
+    # subclassing one, so its face carries only the typed {HasValue} seam,
+    # never the widget's `String`-typed `text`.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class BigDecimalField < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+      NUMERIC: Regexp
+
       def initialize: () -> void
 
-      def cursor_position: () -> Point?
+      # _@return_ — the parsed buffer; `nil` when empty or not a
+      # number (e.g. a lone `"-"`).
+      def value: () -> ::BigDecimal?
 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      # Writes `new_value` into the buffer in plain notation and parks the
+      # caret at its end; fires {#on_value_change} only if the value actually
+      # changed.
+      # 
+      # _@param_ `new_value` — `nil` empties the field. A `Float` is refused, not converted — see the raise.
+      def value=: ((::BigDecimal | Integer | String)? new_value) -> void
 
-      def repaint: () -> void
+      # `nil`, not `""`: a numeric field with no parseable number is empty.
+      def empty_value: () -> void
 
-      # Truncate to fit `rect.width - 1` — single-line fields can't grow past
-      # their width.
+      # _@return_ — the field's caret (the hardware cursor is delegated
+      # to the inner field).
+      def cursor_position: () -> Point?
+
+      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
       # 
-      # _@param_ `new_text`
-      def preprocess_text: (String new_text) -> String
+      # _@return_ — no-arg callable, or nil.
+      def on_enter: () -> (Proc | Method)?
 
-      # _@param_ `key`
-      def handle_text_input_key: (String key) -> bool
+      # _@param_ `callback`
+      def on_enter=: ((Proc | Method)? callback) -> void
 
-      def on_width_changed: () -> void
+      # Places the wrapped field across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `field`
+      def layout: (Component field) -> void
 
-      # Maximum number of characters {#text} can hold given current width.
-      def max_text_length: () -> Integer
+      # Rewrites the half-typed shapes {NUMERIC} admits into ones every
+      # `bigdecimal` version parses: `".5"` → `"0.5"`, `"1."` → `"1"`.
+      # 
+      # _@param_ `text` — a buffer matching {NUMERIC}.
+      def normalize: (String text) -> String
 
-      # _@param_ `char`
-      def insert: (String char) -> bool
+      # _@param_ `new_value`
+      def coerce: ((::BigDecimal | Integer | String) new_value) -> ::BigDecimal
 
-      # Optional callback fired when the UP arrow key is pressed. When set, UP
-      # is consumed by the field; when nil, UP falls through to the parent
-      # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
-      # since `k` is a printable character inserted into {#text}.
+      # The field's key interceptor, consulted *before* the field acts on the
+      # key — which is what lets a rejected character be swallowed without the
+      # caret ever moving.
       # 
-      # _@return_ — no-arg callable, or nil.
-      attr_accessor on_key_up: (Proc | Method)?
+      # _@param_ `key`
+      # 
+      # _@return_ — true to consume the key.
+      def field_key: (String key) -> bool
 
-      # Optional callback fired when the DOWN arrow key is pressed. When set,
-      # DOWN is consumed by the field; when nil, DOWN falls through to the
-      # parent (default behavior). Only triggered by {Keys::DOWN_ARROW}, not by
-      # `j`, since `j` is a printable character inserted into {#text}.
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as
+      # zero.
       # 
-      # _@return_ — no-arg callable, or nil.
-      attr_accessor on_key_down: (Proc | Method)?
+      # _@param_ `delta`
+      def step: (Integer delta) -> void
 
-      # Optional callback fired when ENTER is pressed. When set, ENTER is
-      # consumed by the field; when nil, ENTER falls through to the parent
-      # (default behavior).
+      # Whether `char` may be inserted. Deliberately shallow: it keeps the
+      # buffer *typeable* rather than always-valid — a transient `"-"` or
+      # `"1."` has to be reachable — and {#value} decides what parses.
       # 
-      # _@return_ — no-arg callable, or nil.
-      attr_accessor on_enter: (Proc | Method)?
+      # _@param_ `char` — a single printable character.
+      def accepts?: (String char) -> bool
+
+      # Re-emits {#on_value_change} with the freshly-parsed {#value}, but only
+      # when it differs from the last one fired — so a buffer edit that leaves
+      # the value unchanged (`"1.0"`→`"1.00"`) stays silent.
+      def fire_if_changed: () -> void
+
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
     end
 
-    # Abstract base for editable text components ({TextField}, {TextArea}).
+    # Abstract base for the **String-valued** editable text components
+    # ({TextField}, {TextArea}): a field whose {HasValue#value} *is* its text.
+    # A field whose value is a different type (an `Integer`, a domain object)
+    # *composes* one of these rather than subclassing it — subclassing would
+    # drag this String-typed `text`/`value` seam onto its face alongside the
+    # real typed one.
     # 
     # Holds the shared state — a mutable {#text} buffer, a {#caret} index,
     # {#on_change} and {#on_escape} callbacks — and the keyboard machinery
     # that single-line and multi-line inputs both need: ESC handling,
     # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, and the
-    # `focusable?`/`tab_stop?` flags.
+    # `tab_stop?` flag (`focusable?` comes from {HasValue}).
+    # 
+    # {#caret} counts *characters* into {#text} but may only sit *between*
+    # grapheme clusters — the glyphs a terminal draws. Both write sites snap it
+    # forward onto the enclosing cluster's end, and every edit steps by a whole
+    # cluster:
+    # 
+    #   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.text                   # => "x": the whole glyph went, not its accent
+    # 
+    # Insertion stays character-native, so `String#insert` merges a typed
+    # combining mark into its base; {#text=}'s snap covers the case where that
+    # re-segments the text around the caret.
     # 
     # Subclasses implement the layout-specific pieces ({#cursor_position},
     # {#repaint}) and add their own keys (HOME/END, ENTER, UP/DOWN,
@@ -2944,13 +5229,22 @@ module Tuile
     # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
-    class TextInput < Component
+    class AbstractStringField < Component
+      include Tuile::Component::HasValue
+
       def initialize: () -> void
 
-      # _@return_ — true iff {#text} is the empty string.
-      def empty?: () -> bool
+      # A text component's value *is* its text: {#value}/{#value=} are the
+      # {HasValue} seam over the same buffer as {#text}/{#text=}, so a form can
+      # drive it alongside typed fields. `text` stays the text-native name.
+      def value: () -> String
 
-      def focusable?: () -> bool
+      # sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS
+      # _@param_ `new_value`
+      def value=: ((String | _ToS) new_value) -> void
+
+      # `""` (not `nil`): a text field is empty when its buffer is blank.
+      def empty_value: () -> String
 
       def tab_stop?: () -> bool
 
@@ -2981,6 +5275,17 @@ module Tuile
       # _@return_ — possibly transformed text.
       def preprocess_text: (String new_text) -> String
 
+      # The one measurement primitive both inputs share: a caret index counts
+      # characters, but every rect, cursor and click counts columns, and only
+      # this converts between them.
+      # 
+      # _@param_ `str`
+      # 
+      # _@return_ — `str`'s width in terminal columns, measured per
+      # grapheme cluster — so a combining mark adds nothing and a fullwidth
+      # glyph adds two.
+      def columns_of: (String str) -> Integer
+
       # 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.
@@ -2993,7 +5298,8 @@ module Tuile
 
       # Dispatch hook for {#handle_key}. Handles ESC and the navigation keys
       # that have identical semantics in single-line and multi-line inputs:
-      # LEFT/RIGHT arrows, CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
+      # LEFT/RIGHT arrows (one grapheme cluster per press, so a press always
+      # moves), CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
       # override to add their own keys (HOME/END, UP/DOWN, ENTER, BACKSPACE/
       # DELETE, printable insertion) and call `super` to fall back to the
       # common navigation handling.
@@ -3003,10 +5309,31 @@ module Tuile
       # _@return_ — true if the key was handled.
       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
+      # Hangul syllable each go whole).
       def delete_before_caret: () -> void
 
+      # Removes the whole grapheme cluster at the caret.
       def delete_at_caret: () -> void
 
+      # _@param_ `index` — a {#text} index in `0..text.length`.
+      # 
+      # _@return_ — the smallest grapheme-cluster boundary `>= index`.
+      def snap_to_cluster: (Integer index) -> Integer
+
+      # _@param_ `index`
+      # 
+      # _@return_ — the greatest grapheme-cluster boundary `< index`, or
+      # 0 at the start of the text.
+      def cluster_boundary_before: (Integer index) -> Integer
+
+      # _@param_ `index`
+      # 
+      # _@return_ — the smallest grapheme-cluster boundary `> index`, or
+      # `text.length` at the end of the text.
+      def cluster_boundary_after: (Integer index) -> Integer
+
       # Default {#on_escape} action: clear focus. Component deactivates; user
       # can re-focus by clicking or tabbing back in.
       def default_on_escape: () -> void
@@ -3021,10 +5348,24 @@ module Tuile
       # end of the text if no further word exists.
       def word_right: () -> Integer
 
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
+
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
+
+      # 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`
+      # `D-integer-field`).
+      def focusable?: () -> bool
+
       # _@return_ — current text contents.
       attr_accessor text: String
 
-      # _@return_ — caret index in `0..text.length`.
+      # _@return_ — caret index in `0..text.length`, counting characters
+      # and always on a grapheme-cluster boundary (see the class doc).
       attr_accessor caret: Integer
 
       # Optional callback fired whenever {#text} changes. Receives the new text
@@ -3058,103 +5399,6 @@ module Tuile
       # _@return_ — no-arg callable, or nil.
       attr_accessor on_escape: (Proc | Method)?
     end
-
-    # A mixin interface for a component with one child tops. The host must
-    # provide a protected `layout(content)` method which repositions the
-    # content component; the mixin manages `@content` itself.
-    module HasContent
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
-      def children: () -> ::Array[Component]
-
-      # _@param_ `rect`
-      def rect=: (Rect rect) -> void
-
-      def on_focus: () -> void
-
-      # _@return_ — the current content component.
-      attr_accessor content: Component?
-    end
-
-    # A {Window} preconfigured with a {List} of static lines. Useful for
-    # showing read-only information.
-    # 
-    # Usable tiled (just add to a {Layout}) or as a popup via {.open}, which
-    # wraps it in a {Popup}.
-    class InfoWindow < Tuile::Component::Window
-      # _@param_ `caption`
-      # 
-      # _@param_ `lines` — initial content; each entry may contain Rainbow formatting.
-      def initialize: (?String caption, ?::Array[String] lines) -> void
-
-      # Opens the info window as a popup.
-      # 
-      # _@param_ `caption`
-      # 
-      # _@param_ `lines` — the content, may contain formatting.
-      # 
-      # _@param_ `size` — the popup's size, applied top-down; the list wraps and scrolls within it. Defaults to {Fraction::HALF}.
-      # 
-      # _@return_ — the opened popup.
-      def self.open: (String caption, ::Array[String] lines, ?size: (Size | Fraction)) -> Popup
-    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.
-    # 
-    # 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.
-    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
-
-      # Handles an option-key press. Reached by bubbling: the inner {List}
-      # (the focused component) sees the key first and handles cursor/Enter
-      # picks; anything it declines bubbles up here, where a key matching an
-      # option's `key` picks that option.
-      # 
-      # _@param_ `key`
-      def handle_key: (String key) -> bool
-
-      def keyboard_hint: () -> String
-
-      # Opens a picker as a popup. Picking an option fires `block`, then
-      # closes the popup; ESC / `q` close without firing `block`.
-      # 
-      # _@param_ `caption`
-      # 
-      # _@param_ `options`
-      # 
-      # _@return_ — the wrapping popup.
-      def self.open: (String caption, ::Array[[String, String]] options) ?{ (String key) -> void } -> Popup
-
-      # _@param_ `key`
-      def select_option: (String key) -> void
-
-      # Callback invoked after the user picks an option (after the block
-      # fires). The {Popup} returned by {.open} sets this to its own `close`.
-      attr_accessor on_pick: Proc?
-
-      # One picker option.
-      # 
-      # @!attribute [r] key
-      #   @return [String] the keyboard key that picks this option.
-      # @!attribute [r] caption
-      #   @return [String] the option caption.
-      class Option
-        # _@return_ — the keyboard key that picks this option.
-        attr_reader key: String
-
-        # _@return_ — the option caption.
-        attr_reader caption: String
-      end
-    end
   end
 
   # An app's theme definition: the {Theme} pair covering both terminal
@@ -3251,24 +5495,18 @@ module Tuile
     def await_empty: () -> void
 
     # Schedules `block` to fire on the event-loop thread every `seconds`,
-    # passing a 0-based monotonically increasing tick counter. The interval is
-    # in **seconds** — the conventional scheduling unit (`sleep`,
-    # `Concurrent::TimerTask#execution_interval`, …) — so `tick(0.2)` fires five
-    # times a second. Use it for periodic UI refresh from a background task
-    # (poll a status, redraw a clock). For animation, where frames-per-second
-    # is the natural unit, {#tick_fps} reads better.
-    # 
-    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
-    # stop it.
+    # passing a 0-based monotonically increasing tick counter — `tick(0.2)`
+    # fires five times a second. Use it for periodic UI refresh (poll a status,
+    # redraw a clock); for animation, {#tick_fps} reads more naturally. The
+    # returned {Ticker} controls the schedule — {Ticker#cancel} stops it.
     # 
     # **Errors:** if `block` raises, the {Ticker} cancels itself and the
-    # exception flows through the normal event-loop error path — i.e.
-    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
-    # broken block from spamming `on_error` at the tick rate.
+    # exception flows through the normal event-loop error path
+    # ({Screen#on_error} by default) — auto-cancel keeps a broken block from
+    # spamming `on_error` at the tick rate.
     # 
-    # Tickers reuse `concurrent-ruby`'s shared timer thread
-    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
-    # threads, just more work on the shared scheduler.
+    # Tickers reuse `concurrent-ruby`'s shared timer thread, so adding more
+    # tickers doesn't add threads.
     # 
     # _@param_ `seconds` — interval between firings, must be positive. Fractional values are fine (`tick(0.05)` ⇒ ~20 firings a second).
     def tick: (Numeric seconds) ?{ (Integer tick) -> void } -> Ticker
@@ -3295,8 +5533,11 @@ module Tuile
     # event-handler error, instead of bypassing it.
     def run_loop: () ?{ (Object event) -> void } -> void
 
-    # _@return_ — true if this thread is running inside an event queue.
-    def locked?: () -> bool
+    # _@return_ — true if a {#run_loop} is in progress on *any* thread.
+    def running?: () -> bool
+
+    # _@return_ — true if this thread is the one running {#run_loop}.
+    def on_loop_thread?: () -> bool
 
     # Stops ongoing {#run_loop}. The stop may not be immediate: {#run_loop} may
     # process a bunch of events before terminating.
@@ -3418,8 +5659,10 @@ module Tuile
     end
   end
 
-  # Testing only — a screen which doesn't paint anything and pretends that the
-  # lock is held. This way, the TTY running the tests is not painted over.
+  # Testing only — a screen which doesn't paint anything, so the TTY running
+  # the tests is not painted over. It runs no event loop, so
+  # {Screen#check_locked} admits the thread that called {Screen.fake}: a spec
+  # mutating the UI from a *spawned* thread raises, exactly as an app would.
   # 
   # Intended for unit-testing individual components: instantiate a component,
   # mutate it, and assert against {#prints} or {#invalidated?}. It does not
@@ -3438,9 +5681,9 @@ module Tuile
   #     assert_includes Screen.instance.prints.join, "hi"
   #   end
   class FakeScreen < Tuile::Screen
-    def initialize: () -> void
+    EDITING_KEYS: ::Array[String]
 
-    def check_locked: () -> void
+    def initialize: () -> void
 
     def clear: () -> void
 
@@ -3543,16 +5786,18 @@ module Tuile
 
     def focusable?: () -> bool
 
-    # Children for tree traversal: content first, popups in stacking order,
-    # status bar last.
-    def children: () -> ::Array[Component]
-
     # Adds a popup and invalidates it for repaint. A modal popup is centered
     # and grabs focus; a non-modal overlay ({Component::Popup#modal?} false) is
     # left wherever the caller positions it and does *not* take focus, so the
     # component that was focused keeps the cursor and keeps receiving keys —
     # the overlay floats above the content, driven from app code.
     # 
+    # The *whole subtree* is invalidated, not just the popup wrapper (which
+    # paints nothing on its own): a reopened popup may land on cells that the
+    # tiled content has since overpainted, and if its rect is unchanged from
+    # last time its content components won't re-invalidate themselves — so
+    # without this the popup's contents would stay blank on reopen.
+    # 
     # _@param_ `window`
     def add_popup: (Component::Popup window) -> void
 
@@ -3563,6 +5808,17 @@ module Tuile
     # _@param_ `window`
     def remove_popup: (Component window) -> void
 
+    # Unmounts everything: each child is detached — firing {Component#on_detached}
+    # down its subtree — and every slot is emptied. Terminal; the pane isn't
+    # reusable afterwards, and {Screen#close} is its only caller.
+    # 
+    # Deliberately not named `close` ({Component::Popup#close} already means
+    # "remove *me* from the pane"), and deliberately not a generic
+    # `Component#remove_all_children`: a slot container calling that would empty
+    # `@children` while `#content` / `#footer` still pointed at detached
+    # components, which is the desync the tree API exists to prevent.
+    def detach_all: () -> void
+
     # _@param_ `window`
     # 
     # _@return_ — true if this pane currently hosts the popup.
@@ -3590,20 +5846,21 @@ module Tuile
     # Pane paints nothing itself; its children paint over the entire rect.
     def repaint: () -> void
 
-    # Dispatches a key in two phases, both scoped to the topmost *modal* popup
-    # (when one is open) or else the tiled {#content}. Non-modal overlays are
-    # never the scope: focus stays in the content beneath them, and the overlay
-    # is driven by app code (which forwards keys to it explicitly), so it
-    # doesn't appear in this path at all.
-    # 
-    # 1. *Capture* — a {Component#key_shortcut} match anywhere in the scope
-    #    focuses that component and consumes the key. Suppressed while a
-    #    cursor-owner ({Screen#cursor_position}) is mid-edit, so typing into a
-    #    {Component::TextField} isn't hijacked by a sibling's shortcut.
-    # 2. *Delivery* — the key is handed to {Screen#focused} and bubbles up its
-    #    ancestor chain to the scope root; the first component to return true
-    #    wins. Focus that is nil or sits outside the scope receives nothing,
-    #    which is what keeps an open modal popup modal.
+    # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
+    # 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
+    # scope receives nothing, which is what keeps an open modal popup modal.
+    # Non-modal overlays are never the scope: focus stays in the content
+    # beneath them, and the overlay is driven by app code (which forwards keys
+    # to it explicitly), so it doesn't appear in this path at all.
+    # 
+    # Because an ancestor sees a key only after every descendant on the chain
+    # declined it, the scope root is the natural home for scope-wide fallbacks
+    # — a form's default button, or a layout's one-key jumps to its panes (a
+    # focused {Component::TextField} consumes the key first, so typing is never
+    # hijacked).
     # 
     # _@param_ `key`
     # 
@@ -3669,14 +5926,11 @@ module Tuile
 
   # An immutable string-with-styling, modeled as a sequence of {Span}s where
   # each span carries a complete {Style} (`fg`, `bg`, `bold`, `italic`,
-  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile the string — every
-  # character has exactly one resolved style, no overlay layers to merge.
-  # 
-  # Where this differs from threading SGR escapes through a plain `String`:
-  # slicing, wrapping, and concatenation operate on the structured spans, so
-  # they never have to "figure out what SGR state is active at column N" —
-  # the answer is just the containing span's `style`. The flip side is one
-  # extra type to construct (or parse) before doing styled-text math.
+  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile
+  # the string — every character has exactly one resolved style, no overlay
+  # layers to merge, so the style at any column is just its span's `style`
+  # rather than a replay of the SGR state machine. The book's chapter 9 is
+  # the long-form *why* (spans vs. a `String` full of escape codes).
   # 
   # ## Constructors
   # 
@@ -3700,31 +5954,17 @@ module Tuile
   # ss.each_char_with_style { |ch, style| ... }
   # ```
   # 
-  # ## Rendering
-  # 
-  # - `#to_s` — plain text, no SGR.
-  # - `#to_ansi` — minimal-diff SGR rendering, ending with `\e[0m` only when
-  #   the last span carried a non-default style. Transitions to the default
-  #   style emit `\e[0m` (shorter than re-emitting every off-code).
-  # 
   # ## Parser
   # 
-  # {.parse} is strict by default: it recognizes only the SGR codes
-  # corresponding to {Style}'s supported attributes (fg/bg/bold/italic/
-  # underline/strikethrough). Anything else — unmodeled attributes (dim, blink,
-  # reverse, conceal, double-underline, overline, ...), unknown SGR codes, or
-  # non-SGR escapes (cursor moves, OSC) — raises {ParseError}. This keeps the
-  # round-trip parse(to_ansi(x)) == x contract honest.
-  # 
-  # Pass `lenient: true` to instead **discard** everything the parser can't
-  # model and keep going — recognized fg/bg/bold/italic/underline/strikethrough codes still
-  # apply, and any unmodeled SGR code, malformed extended color, non-SGR CSI
-  # (cursor moves, `\e[K`), OSC/DCS/string sequence, or stray escape is
-  # silently dropped. This is the mode for piping in colored output you don't
-  # control (e.g. `git --color` through a pager): "give me the colors, throw
-  # the rest away." It is lossy by design — `parse(x, lenient: true)` does not
-  # round-trip back to `x`.
+  # {.parse} is strict by default — it recognizes only the SGR codes for
+  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough) and
+  # raises {ParseError} on anything else, keeping the `parse(to_ansi(x)) == x`
+  # round-trip honest. Pass `lenient: true` to instead discard everything it
+  # can't model (unmodeled SGR, cursor moves, OSC/DCS, stray escapes) and keep
+  # only the recognized colors — lossy by design, for piping in colored output
+  # you don't control. See the book for the full rationale.
   class StyledString
+    EMOJI_WIDTH: Symbol
     EMPTY: StyledString
 
     # sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS
@@ -3752,7 +5992,6 @@ module Tuile
 
     # Total display width in terminal columns, accounting for Unicode wide
     # characters (fullwidth CJK = 2 columns, combining marks = 0, etc.).
-    # Memoized — safe because spans are frozen and immutable.
     def display_width: () -> Integer
 
     def empty?: () -> bool
@@ -3765,7 +6004,7 @@ module Tuile
     # emits `\e[0m` (one code) instead of the longer "turn each attribute
     # off" form. Always closes with `\e[0m` when the last span carried a
     # non-default style, so the styled run doesn't bleed into subsequent
-    # output. Memoized — safe because spans are frozen and immutable.
+    # output.
     def to_ansi: () -> String
 
     # _@param_ `other`
@@ -3814,11 +6053,20 @@ module Tuile
     # wrapped continuations, hard `"\n"` breaks preserved as separate output
     # lines.
     # 
+    # An indent is content, so it survives onto the first row — but there is no
+    # hanging indent:
+    # 
+    #   StyledString.plain("  read config").wrap(20).map(&:to_s)
+    #   # => ["  read config"]        indent kept; the line never wrapped
+    #   StyledString.plain("  read config").wrap(6).map(&:to_s)
+    #   # => ["  read", "config"]     ...but a continuation starts at column 0
+    # 
     # Whitespace runs are space or tab; other characters are treated as word
     # content. When a single character is wider than `width` (e.g. a 2-column
     # CJK character with `width = 1`), it is still emitted on its own line at
     # its natural width. The "no line exceeds `width`" guarantee therefore
-    # holds whenever every character is at most `width` columns wide.
+    # holds whenever every character is at most `width` columns wide. An indent
+    # that alone exceeds `width` is dropped rather than given a row of its own.
     # 
     # _@param_ `width` — target column width. `nil` or `<= 0` skips wrapping and returns each hard-line as-is, so callers can pass a stale viewport width without crashing.
     # 
@@ -3838,6 +6086,15 @@ module Tuile
     # _@param_ `bg` — background color, coerced via {Color.coerce}. `nil` clears bg back to the terminal default.
     def with_bg: ((Color | Symbol | Integer | ::Array[Integer])? bg) -> StyledString
 
+    # Returns a copy with `bg` set **only on spans that have none**; a span with
+    # an explicit bg is left untouched. The fill-unset counterpart of {#with_bg}
+    # (which overrides every span) — it slides a background *under* the content,
+    # so a log line keeps its red error-level bg while its plain text picks up an
+    # inherited panel tint.
+    # 
+    # _@param_ `bg` — background color, coerced via {Color.coerce}. `nil` returns `self` unchanged.
+    def under_bg: ((Color | Symbol | Integer | ::Array[Integer])? bg) -> StyledString
+
     # Returns a new {StyledString} with `fg` applied to every span, preserving
     # each span's text and other style attributes (`bg`, `bold`, `italic`,
     # `underline`, `strikethrough`). The new fg overlays without dropping background colors or
@@ -3872,23 +6129,40 @@ module Tuile
     # _@param_ `width`
     def wrap_one: (StyledString hard_line, Integer width) -> ::Array[StyledString]
 
+    # Splits into whitespace/word tokens by **grapheme cluster**, not character:
+    # a cluster is the unit a terminal draws, so measuring its parts separately
+    # would both mis-total an emoji sequence and let a wrap break a letter away
+    # from its combining mark.
+    # 
     # _@param_ `hard_line`
     # 
-    # _@return_ — tokens shaped `[type, chars, w]` where `type` is
-    # `:space` or `:word`, `chars` is an `Array<[String, Style, Integer]>`
-    # (char, style, display width), and `w` is the token's total width.
+    # _@return_ — tokens shaped `[type, glyphs, w]` where `type` is
+    # `:space` or `:word`, `glyphs` is an `Array<[String, Style, Integer]>`
+    # (grapheme cluster, style, display width), and `w` is the token's total
+    # width.
     def tokenize_for_wrap: (StyledString hard_line) -> ::Array[::Array[untyped]]
 
-    # _@param_ `chars` — `[char, style, width]` triples.
+    # Like {#each_char_with_style} but per grapheme cluster. A cluster spanning a
+    # style boundary takes the style of its first span — pathological input, and
+    # splitting the cluster to honor both styles would paint a headless mark.
+    # 
+    # _@param_ `styled`
+    def each_glyph_with_style: (StyledString styled) ?{ (String glyph, Style style) -> void } -> void
+
+    # _@param_ `glyphs` — `[grapheme cluster, style, width]` triples.
     # 
     # _@param_ `width`
     # 
-    # _@return_ — each inner Array is a `chars`-shaped chunk.
-    def hard_break_chars: (::Array[::Array[untyped]] chars, Integer width) -> ::Array[::Array[::Array[untyped]]]
+    # _@return_ — each inner Array is a `glyphs`-shaped chunk.
+    def hard_break_glyphs: (::Array[::Array[untyped]] glyphs, Integer width) -> ::Array[::Array[::Array[untyped]]]
 
-    # _@param_ `chars` — `[char, style, width]` triples.
-    def chars_to_styled: (::Array[::Array[untyped]] chars) -> StyledString
+    # _@param_ `glyphs` — `[grapheme cluster, style, width]` triples.
+    def glyphs_to_styled: (::Array[::Array[untyped]] glyphs) -> StyledString
 
+    # Walks **grapheme clusters**, so a slice boundary can never fall inside one:
+    # cutting a cluster would strand a combining mark with no base, which the
+    # painter drops outright, silently losing the accent off a letter.
+    # 
     # _@param_ `text`
     # 
     # _@param_ `start_col`
@@ -3958,10 +6232,6 @@ module Tuile
       # (`\e[0m`, one code) when `other` is the default style — shorter than
       # turning each attribute off individually.
       # 
-      # Shared by {StyledString#to_ansi} (diffing span-to-span from the default
-      # style) and {Buffer}'s flush (diffing cell-to-cell against the style the
-      # terminal currently holds), so both emit identical minimal sequences.
-      # 
       # _@param_ `other` — the style to transition to.
       def sgr_to: (Style other) -> String
 
@@ -4074,7 +6344,11 @@ module Tuile
   class FakeEventQueue
     def initialize: () -> void
 
-    def locked?: () -> bool
+    # _@return_ — always false — {#run_loop} raises, so no loop ever runs.
+    def running?: () -> bool
+
+    # _@return_ — always true.
+    def on_loop_thread?: () -> bool
 
     def stop: () -> void
 
@@ -4107,6 +6381,14 @@ module Tuile
     # tests pump N frames by calling this N times.
     def tick_once: () -> void
 
+    # Lets a spec assert that a component started a ticker, and — via
+    # {FakeTicker#cancelled?} — that it cancelled one rather than merely
+    # dropping it. Cancelled tickers stay here until the next {#tick_once}
+    # prunes them.
+    # 
+    # _@return_ — the registered tickers, in creation order.
+    attr_reader tickers: ::Array[FakeTicker]
+
     # Handle returned by {FakeEventQueue#tick}. Mirrors the public surface of
     # {EventQueue::Ticker} (`cancel`, `cancelled?`) but does not auto-fire —
     # the host {FakeEventQueue} drives firing via {FakeEventQueue#tick_once}.