tuile 0.8.0 → 0.10.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
@@ -535,7 +555,7 @@ module Tuile
   # string needed to bring a terminal — one that already matches the buffer's
   # state as of the previous flush — up to date. Only cells that actually
   # changed are emitted, so nothing flickers regardless of terminal/multiplexer
-  # synchronized-output support. See `ideas/back-buffer.md`.
+  # synchronized-output support.
   # 
   # Coordinates are 0-based `(x, y)` = `(column, row)`, matching
   # {Component#rect} and `TTY::Cursor.move_to`.
@@ -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
   # 
@@ -569,6 +582,15 @@ module Tuile
   # grid never holds a dangling continuation or a headless one.
   class Buffer
     DEFAULT_STYLE: StyledString::Style
+    WIDTH_CACHE: ::Hash[String, Integer]
+
+    # Memoized {Unicode::DisplayWidth.of}. Use this for every paint-path width
+    # lookup instead of calling the gem directly.
+    # 
+    # _@param_ `grapheme` — one grapheme cluster.
+    # 
+    # _@return_ — its display width in columns (0 for combining marks).
+    def self.display_width: (String grapheme) -> Integer
 
     # _@param_ `size` — grid dimensions in columns × rows.
     def initialize: (Size size) -> void
@@ -609,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.
     # 
@@ -693,6 +714,29 @@ module Tuile
     # tests asserting styled output.
     def region_ansi: (Rect rect) -> ::Array[String]
 
+    # Core of {#set_char} with the grapheme's display width already known.
+    # {#set_line} computes each width once while advancing the column and passes
+    # it straight through, so the paint hot path measures every grapheme exactly
+    # once (and that once is a {.display_width} memo read). See {#set_char} for
+    # the wide-glyph / clipping / out-of-bounds contract.
+    # 
+    # _@param_ `x` — column.
+    # 
+    # _@param_ `y` — row.
+    # 
+    # _@param_ `grapheme` — one grapheme cluster.
+    # 
+    # _@param_ `w` — `grapheme`'s display width (0, 1, or 2).
+    # 
+    # _@param_ `style`
+    def put_char: (
+                    Integer x,
+                    Integer y,
+                    String grapheme,
+                    Integer w,
+                    StyledString::Style style
+                  ) -> void
+
     # (Re)allocates a blank grid of `size` with clean dirty state. Callers
     # follow with {#mark_all_dirty} when the terminal doesn't match the new
     # grid — construction and {#resize} both do.
@@ -748,13 +792,27 @@ module Tuile
                       StyledString::Style style
                     ) -> void
 
-    # If `(x, y)` is half of a wide glyph, blanks the *other* half, so a write
-    # that lands on either half doesn't strand the remaining one.
+    # 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
+
+    # 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
     # 
     # _@param_ `y` — row
-    def repair_orphans: (Integer x, Integer y) -> void
+    def blank_right_partner: (Integer x, Integer y) -> void
 
     attr_reader width: Integer
 
@@ -808,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
   # 
-  # A screen runs the event loop; call {#run_event_loop} to do that.
+  # 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 holds the screen lock; any UI modifications must be called from
-  # the event queue.
+  # ## Repaint model
   # 
-  # 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.
+  # 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.
   # 
-  # Modal popups are supported too, via {Component::Popup#open}. They
-  # auto-size to their wrapped content and are drawn centered over the
-  # tiled content.
+  # ## Thread-safety
   # 
-  # 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.
+  # **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}.
+  # 
+  # 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
 
@@ -844,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.
@@ -879,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
@@ -898,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,
@@ -930,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}.
@@ -976,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
@@ -991,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
@@ -1039,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
@@ -1049,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`
     # 
@@ -1076,6 +1178,9 @@ module Tuile
     # _@return_ — the structural root of the component tree.
     attr_reader pane: ScreenPane
 
+    # _@return_ — `:light` or `:dark`
+    attr_reader color_scheme: Symbol
+
     # _@return_ — the back buffer components paint into
     # ({Buffer#set_line} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader buffer: Buffer
@@ -1141,50 +1246,35 @@ module Tuile
     end
   end
 
-  # A sizing policy for a slot whose position is managed by a parent
-  # component (e.g. {Component::Window#footer}). Resolves one dimension at a
-  # time via {#resolve}, so the same value works for widths and heights.
+  # A width/height ratio, each a float in `0.0..1.0` — the single relational
+  # 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.
   # 
-  # Three policies exist:
+  # Resolve it against a reference {Size} (the screen) to get concrete integer
+  # cells:
   # 
-  # - {FILL} — take everything the slot offers;
-  # - {WRAP_CONTENT} — take the component's natural extent (its
-  #   {Component#content_size}), clamped to the slot;
-  # - {.fixed} — take exactly the given number of cells, clamped to the slot.
+  #   Fraction::HALF.resolve(Size.new(80, 24))  # => 40x12
   # 
-  # Note that {WRAP_CONTENT} only makes sense for components that report a
-  # natural {Component#content_size} ({Component::Label}, {Component::Button},
-  # {Component::List}, …). Input components ({Component::TextField} et al.)
-  # report {Size::ZERO}, so a wrap-content slot collapses to zero width —
-  # i.e. the component becomes invisible. Use {.fixed} or {FILL} for those.
-  # 
-  # @!attribute [r] mode
-  #   @return [Symbol] `:fill`, `:wrap_content` or `:fixed`.
-  # @!attribute [r] amount
-  #   @return [Integer, nil] the cell count for `:fixed`; `nil` otherwise.
-  class Sizing
-    FILL: Sizing
-    WRAP_CONTENT: Sizing
+  # Integer arguments are coerced to float, so `Fraction.new(1, 1) == FULL`.
+  class Fraction
+    HALF: Fraction
+    FULL: Fraction
 
-    # _@param_ `amount` — the number of cells to occupy; 0 or greater.
+    # _@param_ `width` — fraction of the reference width, `0.0..1.0`.
     # 
-    # _@return_ — a fixed-size policy.
-    def self.fixed: (Integer amount) -> Sizing
+    # _@param_ `height` — fraction of the reference height, `0.0..1.0`.
+    def initialize: (width: Numeric, height: Numeric) -> void
 
-    # Resolves one dimension of a slot.
-    # 
-    # _@param_ `available` — cells the slot offers; 0 or greater.
+    # Resolves this fraction against a reference size, rounding each axis to the
+    # nearest cell and flooring at 1 — so a fraction never yields a zero-size
+    # result on a tiny terminal.
     # 
-    # _@param_ `content` — the component's natural extent on this axis (one dimension of its {Component#content_size}).
-    # 
-    # _@return_ — the resolved extent, always in `0..available`.
-    def resolve: (Integer available, Integer content) -> Integer
-
-    # _@return_ — `:fill`, `:wrap_content` or `:fixed`.
-    attr_reader mode: Symbol
-
-    # _@return_ — the cell count for `:fixed`; `nil` otherwise.
-    attr_reader amount: Integer?
+    # _@param_ `reference` — the size to take a fraction of (usually the screen).
+    def resolve: (Size reference) -> Size
   end
 
   # A UI component which is positioned on the screen and draws characters into
@@ -1203,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?}).
     # 
@@ -1268,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
@@ -1298,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
@@ -1324,20 +1391,6 @@ module Tuile
     # _@param_ `child` — the just-detached child.
     def on_child_removed: (Component child) -> void
 
-    # Called by a child component whose {#content_size} just changed (fired
-    # from the child's {#content_size=}). Does nothing by default — a plain
-    # container is not size-coupled to its children. Containers that derive
-    # their own natural size or child layout from a child's natural size
-    # override this (e.g. {Component::Window} re-lays-out a
-    # {Sizing::WRAP_CONTENT} footer and recomputes its own size from content;
-    # {Component::Popup} re-self-sizes). If the receiver's own
-    # {#content_size} changes as a consequence, its {#content_size=} notifies
-    # *its* parent in turn — so the event bubbles exactly as far as geometry
-    # keeps changing, and stops where it doesn't.
-    # 
-    # _@param_ `child` — the resized direct child.
-    def on_child_content_size_changed: (Component child) -> void
-
     # Where the hardware terminal cursor should sit when this component is the
     # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
     # {Screen} positions the hardware cursor after each repaint cycle by
@@ -1351,17 +1404,85 @@ module Tuile
     # topmost popup. Empty by default; override to advertise shortcuts.
     def keyboard_hint: () -> String
 
-    # Advice to a wrapping {Component::Popup} on the minimum height this
-    # component prefers to occupy when shown in a popup. `nil` (the default)
-    # means no preference — the popup uses its own {Component::Popup#min_height}.
-    # Override in a content component that should not collapse to a couple of
-    # rows when sparse (e.g. {Component::LogWindow}).
-    def popup_min_height: () -> Integer?
+    # 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
 
-    # Advice to a wrapping {Component::Popup} on the maximum height this
-    # component may grow to when shown in a popup. `nil` (the default) means
-    # no preference — the popup uses its own {Component::Popup#max_height}.
-    def popup_max_height: () -> Integer?
+    # 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
@@ -1385,60 +1506,93 @@ 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?
 
-    # The {Size} big enough to show the entire component contents without
-    # scrolling. Plain components have no intrinsic content and report
-    # {Size::ZERO}; content-bearing components (e.g. {Label}, {List},
-    # {TextView}, {Window}) maintain it eagerly via {#content_size=} from
-    # their mutators, so reads are O(1). Used by callers like
-    # {Component::Popup} to auto-size to whatever content was assigned,
-    # regardless of its concrete type, and by {Sizing::WRAP_CONTENT} slots.
-    attr_accessor content_size: Size
-
     # A scrollable list of items with cursor support.
     # 
     # 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
@@ -1528,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
@@ -1540,19 +1697,6 @@ module Tuile
       # is one, so the list snaps to the bottom on first paint.
       def on_width_changed: () -> void
 
-      # Natural size from scratch: longest line's display width plus the two
-      # single-space gutters {#pad_to_row} adds, × line count. An empty list
-      # is {Size::ZERO} (no gutters for no content).
-      def compute_content_size: () -> Size
-
-      # Incremental {#content_size} update for appends: folds just the
-      # appended lines into the running maximum, keeping {#add_lines}
-      # O(appended) instead of re-scanning the whole list (LogWindow appends
-      # a line per log statement).
-      # 
-      # _@param_ `appended` — the just-appended lines (already concatenated onto {@lines}).
-      def grow_content_size: (::Array[StyledString] appended) -> void
-
       # Coerces and flattens a list of input entries into trimmed
       # {StyledString} lines. Each entry becomes a {StyledString} (String
       # via {StyledString.parse}, StyledString passed through, anything else
@@ -1850,23 +1994,20 @@ module Tuile
     # embedded ANSI is honored) or a {StyledString} directly. {#text}
     # always returns the {StyledString}.
     class Label < Component
-      def initialize: () -> void
+      # _@param_ `text` — initial text, coerced the same way {#text=} coerces it (a `String` is parsed via {StyledString.parse}; `nil` is an empty label). Equivalent to constructing empty and assigning {#text=}.
+      def initialize: (?(String | StyledString)? text) -> void
 
       # Paints the text into {#rect}.
       # 
       # 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
 
-      # Natural size: longest hard-line's display width × number of hard
-      # lines. Computed on the *unclipped* text — sizing is intrinsic to the
-      # content, not the viewport. Empty text yields {Size::ZERO}.
-      def compute_content_size: () -> Size
-
       # Recomputes {@clipped_lines} for the current text and rect width.
       # Each line is ellipsized to fit and padded with trailing spaces out to
       # the full width, so {#repaint} is just a lookup + {Buffer#set_line} per
@@ -1887,26 +2028,35 @@ 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
 
     # An overlay that wraps any {Component} as its content. Popup itself
     # paints nothing — it's a transparent host that handles its lifecycle
-    # ({#open} / {#close} / {#open?}, ESC/q to close) and auto-sizes to the
-    # wrapped content.
+    # ({#open} / {#close} / {#open?}, ESC/q to close) and holds a top-down
+    # {#size} the {Screen} applies.
+    # 
+    # The popup does *not* size itself to its content. Its box is declared by
+    # {#size} — a {Fraction} (resolved against the screen every layout pass, so
+    # it tracks resize) or an absolute {Size} (clamped to the screen). The
+    # default is {Fraction::HALF}: half the screen, centered. The wrapped
+    # content then fills that box and handles its own overflow by wrapping and
+    # scrolling, so use content that can — a {Component::TextView} or
+    # {Component::TextArea} — for anything longer than fits. A
+    # {Component::Label} only truncates.
     # 
     # 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, still auto-sized)
-    # 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.
+    # 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
@@ -1919,17 +2069,20 @@ 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
 
-      # _@param_ `content` — initial content; can be set later via {#content=}. When provided here, the popup auto-sizes to fit.
+      # _@param_ `content` — initial content; can be set later via {#content=}. The content fills the popup's {#rect}; it does not determine the popup's size.
       # 
       # _@param_ `modal` — true (default) for a centered, focus-grabbing, input-capturing modal; false for a non-modal overlay the caller positions and drives (see the class docs).
-      def initialize: (?content: Component?, ?modal: bool) -> void
+      # 
+      # _@param_ `size` — the popup's size, applied top-down. A {Fraction} is resolved against the screen each layout pass; a {Size} is clamped to the screen. Defaults to {Fraction::HALF}.
+      def initialize: (?content: Component?, ?modal: bool, ?size: (Size | Fraction)) -> void
 
       # _@return_ — whether this popup is modal. See {#initialize}.
       def modal?: () -> bool
@@ -1947,17 +2100,20 @@ module Tuile
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
 
-      # Mounts this popup on the {Screen}. Recomputes the popup's size from
-      # the current content first, so reopening a popup whose content has
-      # grown or shrunk while closed picks up the new size.
+      # Mounts this popup on the {Screen}, re-resolving its {#size} against the
+      # current screen first.
       def open: () -> void
 
       # Constructs and opens a popup in one call.
       # 
       # _@param_ `content`
       # 
+      # _@param_ `modal` — see {#initialize}.
+      # 
+      # _@param_ `size` — see {#initialize}.
+      # 
       # _@return_ — the opened popup.
-      def self.open: (?content: Component?) -> Popup
+      def self.open: (?content: Component?, ?modal: bool, ?size: (Size | Fraction)) -> Popup
 
       # Removes this popup from the {Screen}. No-op if not currently open.
       def close: () -> void
@@ -1965,38 +2121,21 @@ module Tuile
       # _@return_ — true if this popup is currently mounted on the screen.
       def open?: () -> bool
 
-      # Recenters the popup on the screen, preserving its current width/height.
-      # Called automatically by the screen's layout pass and by {#content=}
-      # when the popup is open.
-      def center: () -> void
-
-      # _@return_ — max height the popup will grow to fit its content.
-      # Defers to the content's {Component#popup_max_height} advice when it
-      # gives one, else defaults to 12. Override in a subclass to allow
-      # taller popups regardless of content.
-      def max_height: () -> Integer
-
-      # _@return_ — min height the popup occupies even when its content
-      # is shorter. Defers to the content's {Component#popup_min_height}
-      # advice when it gives one, else defaults to 0 (size purely to
-      # content) — so a {Component::LogWindow} stays readable while only a
-      # few lines are in without callers wiring up a subclass. Override in a
-      # subclass to keep any popup from collapsing to a couple of rows.
-      # Capped at the same 4/5-of-screen ceiling {#update_rect} applies.
-      def min_height: () -> Integer
-
-      # Sets the popup's content and auto-sizes the popup to fit.
+      # Re-resolves {#size} against the current screen and repositions the popup
+      # *itself* (this is not laying out content — the popup's own rect): a
+      # modal popup recenters; a non-modal overlay keeps its caller-assigned
+      # top-left (only its size follows the screen). Called on {#open}, on
+      # {#size=}, and by the screen's layout pass (so a {Fraction} size tracks
+      # SIGWINCH).
       # 
-      # _@param_ `new_content`
-      def content=: (Component? new_content) -> void
+      # The final rect is computed and assigned in one step rather than sizing
+      # at the origin and then centering: the intermediate origin rect rarely
+      # covers the previous one, which would make {#rect=}'s shrink/move
+      # detection fire a full repaint on every resize.
+      def reposition: () -> void
 
-      # Re-sizes (and recenters, when open) whenever the wrapped content's
-      # natural size changes — e.g. a {Label}'s `text=`, a {List}'s
-      # `add_line`, or a nested {Window} whose own content grew (the window
-      # recomputes its {Component#content_size} and the change bubbles here).
-      # 
-      # _@param_ `_child`
-      def on_child_content_size_changed: (Component _child) -> void
+      # Recenters the popup on the screen, preserving its current width/height.
+      def center: () -> void
 
       # Hint for the status bar: own "q Close" plus the wrapped content's hint.
       def keyboard_hint: () -> String
@@ -2015,21 +2154,13 @@ module Tuile
       # _@param_ `content`
       def layout: (Component content) -> void
 
-      # Recompute width/height from {#content}'s natural size and recenter
-      # if currently open. Called whenever content is (re)assigned.
-      # 
-      # Computes the final (centered) rect and assigns it in one step rather
-      # than positioning at the origin and then centering: the intermediate
-      # origin rect rarely covers the previous one, which would make
-      # {#rect=}'s shrink/move detection fire a full repaint on every resize.
-      def update_rect: () -> void
-
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
-      def children: () -> ::Array[Component]
-
       def on_focus: () -> void
+
+      # _@return_ — the popup's declared size. See {#size=}.
+      attr_accessor size: (Size | Fraction)
     end
 
     # A clickable button. Activated by Enter, Space, or a left mouse click;
@@ -2042,10 +2173,14 @@ module Tuile
     # {Component#handle_mouse}.
     # 
     # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
-    # show `[ caption ]`; {#content_size} reports that natural width.
+    # 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
 
@@ -2054,16 +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
 
-      # Natural width is `caption.length + 4` to fit `[ caption ]`; height 1.
-      def natural_size: () -> Size
+      # 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
 
-      # _@return_ — the button's label.
-      attr_accessor caption: String
+      # 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.
@@ -2081,10 +2235,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
@@ -2103,8 +2253,6 @@ module Tuile
       # _@param_ `child`
       def remove: (Component child) -> void
 
-      def content_size: () -> Size
-
       # Dispatches the event to the child under the mouse cursor.
       # 
       # _@param_ `event`
@@ -2129,14 +2277,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
 
@@ -2146,22 +2293,6 @@ module Tuile
       # _@param_ `value`
       def scrollbar=: (bool value) -> void
 
-      # Sets the new content. Also recomputes the window's natural size.
-      # 
-      # _@param_ `new_content`
-      def content=: (Component? new_content) -> void
-
-      # Re-lays-out a {Sizing::WRAP_CONTENT} footer when the footer's natural
-      # size changes, and folds a content resize into the window's own
-      # natural size (whose change then bubbles to the window's parent — e.g.
-      # a {Popup} re-self-sizes). The footer deliberately does *not*
-      # participate in the window's {#content_size}: it is decoration
-      # overlaying the border, and must not drive the window's size — if it
-      # doesn't fit, it is clipped to the inner width.
-      # 
-      # _@param_ `child`
-      def on_child_content_size_changed: (Component child) -> void
-
       # Fully repaints the window: both frame and contents.
       # 
       # Window deliberately paints over its entire rect (border around the
@@ -2174,167 +2305,599 @@ 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
 
-      # The caption text as it appears in the rendered border, including the
-      # shortcut prefix when {#key_shortcut} is set.
-      def frame_caption: () -> String
-
-      # Recomputes the window's natural size: content's natural size (or the
-      # caption, whichever is wider) plus the 2-character border. The footer
-      # is deliberately excluded — see {#on_child_content_size_changed}. A
-      # window with no content or caption sizes to `Size.new(2, 2)` (bare
-      # border).
-      def update_content_size: () -> void
-
-      # Positions the footer over the bottom border row, with its width
-      # resolved by {#footer_sizing} against the inner width. A
-      # {Sizing::WRAP_CONTENT} footer with zero natural width gets an empty
-      # rect — i.e. it is invisible, as if never assigned.
+      # 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.
+      # 
+      # _@param_ `inner_w` — the border's interior width.
+      # 
+      # _@param_ `fg` — the active-border color, or nil when inactive.
+      def bottom_border: (Integer inner_w, Color? fg) -> StyledString
+
+      # 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 component overlaying the bottom border
-      # row.
+      # _@return_ — optional focusable component occupying the
+      # bottom border row, always spanning the full inner width.
       attr_accessor footer: Component?
 
-      # _@return_ — how the footer's width is computed from the window's
-      # inner width; defaults to {Sizing::FILL} (the footer spans the full
-      # inner width). The footer's height is always 1 (the border row).
-      attr_accessor footer_sizing: Sizing
-
-      # _@return_ — the current caption, empty by default.
-      attr_accessor caption: String
+      # _@return_ — optional chrome embedded into the bottom border
+      # 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 multi-line, word-wrapping text input.
+    # A boolean input on one row. Space or a left click toggles it:
     # 
-    # Sized by the caller — {#rect} is fixed; the area does not grow with
-    # content. Text is wrapped to {Rect#width} columns and any text that
-    # doesn't fit vertically is reached by scrolling: {#top_display_row}
-    # follows the caret so the line being edited stays visible. There is no
-    # horizontal scrolling.
+    #   [x] Enable syslog forwarding
+    #   [ ] Enable syslog forwarding
     # 
-    # The caret is a logical index in `0..text.length`. 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).
+    #   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
     # 
-    # 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
-      def initialize: () -> void
+    # {#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 toggles. Enter is unhandled — unlike {Button} — simply because a
+    # checkbox has no default action to confirm, so it bubbles to an ancestor;
+    # treat that as this widget declining a key, not as a guarantee the framework
+    # makes (a {TextArea} claims Enter for newline, and a checkable row in a
+    # {Component::List} toggles on it).
+    # 
+    # 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
 
-      def cursor_position: () -> Point?
+      # _@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. Every other key — Enter included — 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
 
-      def on_text_mutated: () -> 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
 
-      def on_caret_mutated: () -> void
+      # 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
 
-      # _@param_ `key`
-      def handle_text_input_key: (String key) -> bool
+      # _@return_ — the current value; `nil` until first set.
+      def value: () -> Object
 
-      def on_width_changed: () -> void
+      # _@return_ — true iff {#value} equals {#empty_value}.
+      def empty?: () -> bool
 
-      # _@return_ — cached wrap of {#text} for the
-      # current {Rect#width}. Each entry is `{start:, length:}`.
-      def display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+      # Resets {#value} to {#empty_value}.
+      def clear: () -> void
 
-      # 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.
-      def compute_display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+      # 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
 
-      # 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.
-      # 
-      # _@param_ `row_start`
+    # 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
+      MAX_VISIBLE_ROWS: Integer
+
+      # _@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_ `row_chars`
+      # _@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}.
       # 
-      # _@return_ — new row_chars.
-      def trim_trailing_whitespace: (Integer row_start, Integer row_chars) -> Integer
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
 
-      # _@param_ `caret`
+      # 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.
       # 
-      # _@return_ — `[row_index, column]` for `caret`.
-      def caret_to_display: (Integer caret) -> [Integer, Integer]
+      # _@param_ `flag`
+      def active=: (bool flag) -> void
 
-      # _@param_ `delta` — `+1` for down, `-1` for up.
-      def move_caret_vertical: (Integer delta) -> void
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
 
-      def move_caret_to_row_start: () -> void
+      def repaint: () -> void
 
-      def move_caret_to_row_end: () -> void
+      # Field spans the row bar the last column, which the `▾` occupies
+      # ({HasContent} layout hook).
+      # 
+      # _@param_ `field`
+      def layout: (Component field) -> void
 
-      # _@param_ `char`
+      # 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.
       # 
-      # _@return_ — always true.
-      def insert_char: (String char) -> bool
+      # _@param_ `key`
+      # 
+      # _@return_ — true if consumed.
+      def field_key: (String key) -> bool
 
-      # Keeps the caret visible by scrolling vertically.
-      def adjust_top_display_row: () -> void
+      # 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
 
-      # _@return_ — index of the topmost display row currently visible.
-      attr_reader top_display_row: Integer
-    end
+      # 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]
 
-    # 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.
-    class TextView < Component
-      def initialize: () -> void
+      # 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
 
-      # _@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).
+      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
+
+      # Sizes and positions the dropdown against the field: full combo width,
+      # `min(matches, 10)` rows, below the field — flipped above when it won't
+      # fit beneath, clamped (with the list scrolling) when it fits neither.
+      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.
+    # 
+    # Sized by the caller — {#rect} is fixed; the area does not grow with
+    # content. Text is wrapped to {Rect#width} columns and any text that
+    # doesn't fit vertically is reached by scrolling: {#top_display_row}
+    # 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`, 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).
+    # 
+    # 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?
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      def on_text_mutated: () -> void
+
+      def on_caret_mutated: () -> void
+
+      # _@param_ `key`
+      def handle_text_input_key: (String key) -> bool
+
+      def on_width_changed: () -> void
+
+      # _@return_ — cached wrap of {#text} for the
+      # current {Rect#width}. Each entry is `{start:, length:}`.
+      def display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+
+      # _@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`
+      # 
+      # _@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
+
+      def move_caret_to_row_start: () -> void
+
+      def move_caret_to_row_end: () -> void
+
+      # _@param_ `char`
+      # 
+      # _@return_ — always true.
+      def insert_char: (String char) -> bool
+
+      # Keeps the caret visible by scrolling vertically.
+      def adjust_top_display_row: () -> void
+
+      # _@return_ — index of the topmost display row currently visible.
+      attr_reader top_display_row: Integer
+    end
+
+    # A read-only viewer for prose: chunks of formatted text that scroll
+    # 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 (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
@@ -2372,19 +2935,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
@@ -2404,56 +2960,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.
       # 
@@ -2489,6 +3019,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
@@ -2573,19 +3105,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`
       # 
@@ -2660,9 +3185,6 @@ module Tuile
       # reader when the cache is cold. Cost is O(total spans).
       def build_text: () -> StyledString
 
-      # _@return_ — {#content_size} computed from {@hard_lines}.
-      def compute_content_size: () -> Size
-
       # _@return_ — column width available for wrapped text — viewport
       # width minus the scrollbar gutter (when visible). `0` when {#rect}'s
       # width is non-positive, which yields a degenerate "no wrap" result.
@@ -2721,13 +3243,6 @@ module Tuile
       # bottom and tailing resumes. Default `false`.
       attr_accessor auto_scroll: bool
 
-      # _@return_ — longest hard-line's display width × number of hard
-      # lines. Reported on the *unwrapped* text — wrap-aware sizing would
-      # be circular (width depends on width). Empty text returns
-      # `Size.new(0, 0)`. Maintained incrementally by {#text=} and
-      # {#append}, so reads are O(1).
-      attr_reader content_size: Size
-
       # A logical section of a {TextView}'s text — a contiguous run of
       # hard lines the app wants to address as a unit (e.g. an LLM's
       # "thinking" output vs. its assistant message). The view always
@@ -2775,14 +3290,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
@@ -2853,129 +3363,1012 @@ module Tuile
 
         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)
+        # _@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
+
+    # 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 text input drops open, drives by forwarding movement keys, and commits a
+    # pick from: a non-modal {Popup} wrapping a {List} that never takes focus, so
+    # the caret stays in the driving input 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, per keystroke in the driving input's key handler:
+    #   drop.lines = matches.map { |m| render(m) }  # caller filters + renders
+    #   drop.rect  = Rect.new(...)                   # caller anchors + sizes it
+    #   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; everything that varies stays
+    # with the driver: geometry/anchoring, 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]
+
+      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
+
+      # 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 (and the caret) stay in its input, and a mouse click selects
+      # an item without stealing focus — so the input never loses the cursor
+      # 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
 
-    # 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
+    # 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]
 
-      # Keep the log pane at least half the screen tall even when only a few
-      # lines have been logged: a {Component::Popup} sizes to its content, which
-      # would collapse a near-empty log to two or three rows. Advice consulted
-      # by {Component::Popup#min_height} when this window is a popup's content.
-      def popup_min_height: () -> Integer
+      # _@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
 
-      # Let a busy log grow past the popup's base 12-row cap (up to the
-      # 4/5-of-screen ceiling {Component::Popup#update_rect} applies) so the
-      # diagnostic stream stays scrollable in a tall window. Advice consulted
-      # by {Component::Popup#max_height} when this window is a popup's content.
-      def popup_max_height: () -> Integer
+      # _@return_ — the frozen empty set — {HasValue#empty?} means nothing is
+      # selected.
+      def empty_value: () -> ::Set[untyped]
 
-      # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
+      # 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_ `string` — the line (or multiple lines) to log.
-      def log: (String? string) -> void
+      # _@param_ `new_value` — `nil` selects nothing.
+      def value=: (::Enumerable[untyped]? new_value) -> 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
+      # 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
 
-        # _@param_ `string`
-        def write: (String string) -> void
+      # Places the composed list across the whole rect ({HasContent} hook).
+      # 
+      # _@param_ `list`
+      def layout: (Component list) -> void
 
-        # _@param_ `string`
-        def puts: (String string) -> void
+      # Flips membership of the item on row `index`; an index outside {#items} is
+      # ignored.
+      # 
+      # _@param_ `index`
+      def toggle_at: (Integer index) -> 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
+      # Re-renders every row from the current items, labels and selection.
+      def rebuild_rows: () -> void
 
-    # 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
-      def initialize: () -> void
+      # _@param_ `new_value`
+      # 
+      # _@return_ — a frozen copy; `nil` becomes {#empty_value}.
+      def coerce: (::Enumerable[untyped]? new_value) -> ::Set[untyped]
 
-      def cursor_position: () -> Point?
+      # _@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 repaint: () -> void
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
 
-      # Truncate to fit `rect.width - 1` — single-line fields can't grow past
-      # their width.
-      # 
-      # _@param_ `new_text`
-      def preprocess_text: (String new_text) -> String
+      def on_focus: () -> void
 
-      # _@param_ `key`
-      def handle_text_input_key: (String key) -> bool
+      # _@return_ — the presented items.
+      attr_accessor items: ::Array[untyped]
 
-      def on_width_changed: () -> void
+      # _@return_ — item -> row label (a `String`, {StyledString}, or
+      # anything with `#to_s`); `:to_s` by default.
+      attr_accessor item_label: (Proc | Method)
+    end
+
+    # A {TextField} that paints one mask glyph per character instead of the
+    # text. Editing, caret, clicks and horizontal scrolling are the field's,
+    # unchanged:
+    # 
+    #   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
+    # 
+    # 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
 
-      # Maximum number of characters {#text} can hold given current width.
-      def max_text_length: () -> Integer
+      # _@return_ — {#revealed} in predicate form.
+      def revealed?: () -> bool
+
+      # _@return_ — the mask, one glyph per character, unless {#revealed}.
+      def display_text: () -> String
 
       # _@param_ `char`
-      def insert: (String char) -> bool
+      def single_cluster?: (String char) -> bool
 
-      # 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)?
+      # _@return_ — caret target for CTRL+LEFT: the start, while masked.
+      def word_left: () -> Integer
 
-      # 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)?
+      # _@return_ — caret target for CTRL+RIGHT: the end, while masked.
+      def word_right: () -> Integer
 
-      # 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)?
+      # _@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
 
-    # 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,
@@ -2992,13 +4385,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
 
@@ -3029,6 +4431,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.
@@ -3041,7 +4454,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.
@@ -3051,10 +4465,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
@@ -3069,10 +4504,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
@@ -3106,101 +4555,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.
-      # 
-      # _@return_ — the opened popup.
-      def self.open: (String caption, ::Array[String] lines) -> 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
@@ -3296,25 +4650,29 @@ module Tuile
     # Awaits until the event queue is empty (all events have been processed).
     def await_empty: () -> void
 
-    # Schedules `block` to fire on the event-loop thread roughly `fps` times
-    # per second, passing a 0-based monotonically increasing tick counter. Use
-    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
-    # periodic UI refresh from a background task.
-    # 
-    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
-    # stop it.
+    # Schedules `block` to fire on the event-loop thread every `seconds`,
+    # 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, so adding more
+    # tickers doesn't add threads.
     # 
-    # 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.
+    # _@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
+
+    # Frames-per-second convenience over {#tick}: `tick_fps(15)` is exactly
+    # `tick(1.0 / 15)`. Reads naturally for animation (a `/-\|` spinner, a
+    # progress pulse) where you think in frames, not intervals.
     # 
-    # _@param_ `fps` — firings per second, must be positive. Fractional values are fine (`fps: 0.5` ⇒ one tick every two seconds).
-    def tick: (Numeric fps) ?{ (Integer tick) -> void } -> Ticker
+    # _@param_ `fps` — firings per second, must be positive. Fractional values are fine (`tick_fps(0.5)` ⇒ one firing every two seconds).
+    def tick_fps: (Numeric fps) ?{ (Integer tick) -> void } -> Ticker
 
     # Runs the event loop and blocks. Must be run from at most one thread at the
     # same time. Blocks until some thread calls {#stop}. Calls block for all
@@ -3331,8 +4689,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.
@@ -3435,10 +4796,10 @@ module Tuile
     class Ticker
       # _@param_ `event_queue` — queue to dispatch tick calls onto.
       # 
-      # _@param_ `fps` — firings per second (positive).
+      # _@param_ `interval` — seconds between firings (positive).
       # 
       # _@param_ `block` — called as `block.call(tick_count)` on each fire.
-      def initialize: (EventQueue event_queue, Numeric fps, Proc block) -> void
+      def initialize: (EventQueue event_queue, Numeric interval, Proc block) -> void
 
       # _@return_ — true once {#cancel} has been called.
       def cancelled?: () -> bool
@@ -3454,8 +4815,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
@@ -3474,9 +4837,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
 
@@ -3579,16 +4942,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
 
@@ -3599,6 +4964,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.
@@ -3617,27 +4993,30 @@ module Tuile
     def rect=: (Rect new_rect) -> void
 
     # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Modal popups self-recenter via {Component::Popup#center};
-    # non-modal overlays keep the position their owner assigned.
+    # (bottom row). Each popup re-resolves its {Component::Popup#size} against
+    # the new screen via {Component::Popup#reposition} — so a {Fraction} size
+    # tracks resize — repositioning itself (modal popups recenter; non-modal
+    # overlays keep the top-left their owner assigned).
     def layout: () -> void
 
     # 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`
     # 
@@ -3703,14 +5082,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
   # 
@@ -3734,31 +5110,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
@@ -3786,7 +5148,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
@@ -3799,7 +5160,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`
@@ -3872,6 +5233,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
@@ -3906,23 +5276,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`
@@ -3992,10 +5379,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
 
@@ -4108,7 +5491,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
 
@@ -4122,12 +5509,18 @@ module Tuile
     def post: (Object event) -> void
 
     # Mirrors {EventQueue#tick} but timeless: returns a {FakeTicker} that
-    # only fires when a test calls {#tick_once}. The `fps` argument is
+    # only fires when a test calls {#tick_once}. The `seconds` argument is
     # validated the same way the real queue validates it, then discarded —
     # the fake has no clock, so frame cadence is up to the test.
     # 
-    # _@param_ `fps` — firings per second, must be positive. Validated for parity with {EventQueue#tick}; otherwise unused.
-    def tick: (Numeric fps) ?{ (Integer tick) -> void } -> FakeTicker
+    # _@param_ `seconds` — interval between firings, must be positive. Validated for parity with {EventQueue#tick}; otherwise unused.
+    def tick: (Numeric seconds) ?{ (Integer tick) -> void } -> FakeTicker
+
+    # Mirrors {EventQueue#tick_fps}: validates `fps` for parity, then delegates
+    # to {#tick} (the fake discards the interval regardless).
+    # 
+    # _@param_ `fps` — firings per second, must be positive.
+    def tick_fps: (Numeric fps) ?{ (Integer tick) -> void } -> FakeTicker
 
     # Test helper: fires every live ticker's user block once and prunes
     # cancelled tickers. No-op when no tickers are registered. Pumps once
@@ -4135,6 +5528,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}.