tuile 0.7.0 → 0.9.0

data/sig/tuile.rbs

@@ -23,6 +23,8 @@ module Tuile
   # same form.
   module Ansi
     RESET: String
+    SYNC_BEGIN: String
+    SYNC_END: String
   end
 
   # Constants for keys returned by {.getkey} and helpers for reading them from
@@ -526,6 +528,344 @@ module Tuile
     attr_reader custom: ::Hash[Symbol, Color]
   end
 
+  # An in-memory grid of styled cells mirroring the terminal screen. This is
+  # the back buffer behind flicker-free rendering: components paint into it
+  # (via {#set_line} / {#set_char} / {#fill}) instead of writing escape
+  # sequences straight to the terminal, and {#flush} emits the minimal escape
+  # 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.
+  # 
+  # Coordinates are 0-based `(x, y)` = `(column, row)`, matching
+  # {Component#rect} and `TTY::Cursor.move_to`.
+  # 
+  # ## Dirty tracking
+  # 
+  # Every mutator compares the incoming grapheme+style against what's already
+  # there and records the cell dirty only when it differs — so both mutation
+  # and {#flush} cost scale with what actually changed, never with the buffer
+  # 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
+  # (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.
+  # 
+  # ## Wide characters
+  # 
+  # A 2-column glyph (fullwidth CJK, most emoji) occupies its origin cell plus a
+  # **continuation** cell to its right (an empty-grapheme {Cell} the flush emits
+  # nothing for, since the glyph itself advances the cursor two columns).
+  # Overwriting either half of a wide glyph blanks the orphaned half, so the
+  # grid never holds a dangling continuation or a headless one.
+  # 
+  # ## Future direction
+  # 
+  # Components paint through this drawing surface ({#set_line} / {#set_char})
+  # without knowing whether it is the one global buffer or a private one — that
+  # indirection is deliberate, so per-component back buffers plus a z-order
+  # compositor could drop in without touching component code. It is not worth
+  # doing yet: the diff already drops unchanged cells from the wire, and an
+  # occluded component that didn't change is never repainted at all, so a
+  # compositor would only save residual `repaint` CPU. It pays off in exactly
+  # one regime — high repeat-rate scroll (held arrow / mouse wheel) of a large
+  # component on a large screen, where re-rendering the content each repeat is
+  # the dominant cost.
+  class Buffer
+    DEFAULT_STYLE: StyledString::Style
+    WIDTH_CACHE: ::Hash[String, Integer]
+
+    # 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
+
+    # _@return_ — grid dimensions.
+    def size: () -> Size
+
+    # _@param_ `x` — column.
+    # 
+    # _@param_ `y` — row.
+    # 
+    # _@return_ — the live cell at `(x, y)` (do not mutate — paint via
+    # {#set_char} / {#set_line} so dirty tracking stays correct), or nil when
+    # out of bounds.
+    def cell: (Integer x, Integer y) -> Cell?
+
+    # _@return_ — true if any cell has changed since the last {#flush}.
+    def dirty?: () -> bool
+
+    # Writes one grapheme cluster at `(x, y)`. A 2-column glyph also writes a
+    # continuation cell at `(x + 1, y)`; a wide glyph that would overflow the
+    # last column is replaced by a blank (terminals can't render a half-clipped
+    # wide glyph). Zero-width input (a lone combining mark) is ignored — it has
+    # no cell of its own. Out-of-bounds writes are dropped.
+    # 
+    # _@param_ `x` — column.
+    # 
+    # _@param_ `y` — row.
+    # 
+    # _@param_ `grapheme` — one grapheme cluster.
+    # 
+    # _@param_ `style`
+    def set_char: (
+                    Integer x,
+                    Integer y,
+                    String grapheme,
+                    ?StyledString::Style style
+                  ) -> 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.
+    # 
+    # _@param_ `x` — starting column.
+    # 
+    # _@param_ `y` — row.
+    # 
+    # _@param_ `styled`
+    def set_line: (Integer x, Integer y, StyledString styled) -> void
+
+    # Fills the intersection of `rect` and the buffer with blank cells in
+    # `style` — the cell-grid equivalent of clearing a background. Only `bg`
+    # shows; the grapheme is a space.
+    # 
+    # _@param_ `rect`
+    # 
+    # _@param_ `style`
+    def fill: (Rect rect, ?StyledString::Style style) -> void
+
+    # Blanks the entire buffer in `style`. A flat pass over every cell — no
+    # rect math or nested loops, since it covers the whole grid. Only cells
+    # that actually change are marked dirty (and their rows), so a {#flush}
+    # after clearing an already-blank buffer emits nothing.
+    # 
+    # _@param_ `style`
+    def clear: (?StyledString::Style style) -> void
+
+    # Marks every cell dirty, so the next {#flush} re-emits the whole grid.
+    # Used after a resize and whenever the terminal contents become unknown
+    # (e.g. the screen was cleared underneath us).
+    def mark_all_dirty: () -> void
+
+    # Resizes the grid to `size`, reallocating blank cells and marking the
+    # whole buffer dirty — after a resize the terminal contents are undefined,
+    # so the next flush redraws from scratch.
+    # 
+    # _@param_ `size`
+    def resize: (Size size) -> void
+
+    # Emits the minimal escape sequence that updates a terminal — already
+    # matching this buffer as of the previous flush — to the current contents,
+    # then clears the dirty flags. Returns `""` when nothing changed.
+    # 
+    # Scans only dirty rows; within a row, consecutive dirty cells form one run
+    # (one `TTY::Cursor.move_to` followed by their graphemes), with a running
+    # {StyledString::Style#sgr_to} diff so only changed attributes are sent
+    # (continuation cells emit nothing). The sequence always ends in the default
+    # style ({Ansi::RESET} when needed), the invariant the next flush relies on:
+    # the terminal's SGR state is default at flush boundaries.
+    # 
+    # _@return_ — the escape sequence to write to the terminal.
+    def flush: () -> String
+
+    # _@param_ `y` — row.
+    # 
+    # _@return_ — the plain text of row `y` (continuation cells contribute
+    # nothing, so wide glyphs read as their single cluster). Intended for
+    # tests; see {FakeScreen}.
+    def row_text: (Integer y) -> String
+
+    # _@param_ `y` — row.
+    # 
+    # _@return_ — row `y` rendered to ANSI across its full width — the
+    # minimal-SGR encoding of its cells, equivalent to what a component's
+    # `set_line` of the whole row would have printed. Intended for tests that
+    # assert on styled output (see {FakeScreen}); empty for an out-of-range row.
+    def row_ansi: (Integer y) -> String
+
+    # _@param_ `rect`
+    # 
+    # _@return_ — the plain text of each row within `rect`'s column
+    # range, top to bottom. The region equivalent of {#row_text}, for asserting
+    # what a component painted into its own rect. Intended for tests.
+    def region_text: (Rect rect) -> ::Array[String]
+
+    # _@param_ `rect`
+    # 
+    # _@return_ — each row within `rect` rendered to ANSI, top to
+    # bottom — byte-identical to what a component's per-row `set_line` over
+    # that rect emitted. The region equivalent of {#row_ansi}. Intended for
+    # 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.
+    # 
+    # _@param_ `size`
+    def allocate_grid: (Size size) -> void
+
+    # Emits the dirty cells of row `y` into `out`, breaking a run at each clean
+    # cell, and returns the running style at the end of the row.
+    # 
+    # _@param_ `out` — accumulator.
+    # 
+    # _@param_ `y`
+    # 
+    # _@param_ `style` — style the terminal currently holds.
+    def flush_row: (String _out, Integer y, StyledString::Style style) -> StyledString::Style
+
+    # _@param_ `rect`
+    # 
+    # _@return_ — cells within `rect`, row-major, clamped to
+    # the grid (out-of-bounds positions yield a blank cell).
+    def region_cells: (Rect rect) -> ::Array[::Array[Cell]]
+
+    # _@param_ `x` — column
+    # 
+    # _@param_ `y` — row
+    # 
+    # _@return_ — flat-array index for `(x, y)`.
+    def index: (Integer x, Integer y) -> Integer
+
+    # _@param_ `x` — column
+    # 
+    # _@param_ `y` — row
+    # 
+    # _@return_ — true when `(x, y)` falls within the grid.
+    def in_bounds?: (Integer x, Integer y) -> bool
+
+    # Rewrites the cell at `(x, y)` in place, marking it (and its row) dirty
+    # only when grapheme or style actually changes. Caller guarantees `(x, y)`
+    # is in bounds.
+    # 
+    # _@param_ `x` — column
+    # 
+    # _@param_ `y` — row
+    # 
+    # _@param_ `grapheme` — the new grapheme cluster
+    # 
+    # _@param_ `style` — the new style
+    def write_cell: (
+                      Integer x,
+                      Integer y,
+                      String grapheme,
+                      StyledString::Style style
+                    ) -> void
+
+    # If `(x, y)` holds the right half (continuation) of a wide glyph, blanks the
+    # orphaned left half at `x - 1`. Called before a write lands on `x`, so the
+    # wide glyph to the left isn't left headless.
+    # 
+    # _@param_ `x` — column
+    # 
+    # _@param_ `y` — row
+    def blank_left_partner: (Integer x, Integer y) -> void
+
+    # If the cell just right of `(x, y)` is a continuation (the right half of a
+    # wide glyph whose origin is `(x, y)`), blanks it. Called before a write
+    # lands on `x`, so overwriting a wide origin doesn't strand its continuation.
+    # A continuation can only ever belong to the wide glyph immediately to its
+    # left, so the empty-grapheme test is exact — and cheaper than re-measuring
+    # the origin's width.
+    # 
+    # _@param_ `x` — column
+    # 
+    # _@param_ `y` — row
+    def blank_right_partner: (Integer x, Integer y) -> void
+
+    attr_reader width: Integer
+
+    attr_reader height: Integer
+
+    # One screen cell: a single grapheme cluster, the {StyledString::Style} it's
+    # drawn in, and a dirty flag. Mutable by design (see {Buffer} "Dirty
+    # tracking") — the grid rewrites cells in place. A continuation cell (right
+    # half of a wide glyph) carries an empty grapheme — see {#continuation?}.
+    class Cell
+      # _@param_ `grapheme`
+      # 
+      # _@param_ `style`
+      def initialize: (String grapheme, StyledString::Style style) -> void
+
+      # _@return_ — true if this is the right half of a wide glyph, which
+      # {Buffer#flush} skips (the glyph to the left already moved the cursor
+      # past it).
+      def continuation?: () -> bool
+
+      # Sets the cell's content, flipping {#dirty} on when grapheme or style
+      # actually changes (an already-dirty cell stays dirty). Returns the
+      # resulting dirty flag, so callers can aggregate row/buffer dirty state in
+      # one step. The single mutation path behind {Buffer#set_char} / {#fill} /
+      # {#clear}.
+      # 
+      # _@param_ `grapheme`
+      # 
+      # _@param_ `style`
+      # 
+      # _@return_ — {#dirty} after the write.
+      def set: (String grapheme, StyledString::Style style) -> bool
+
+      # Content equality (grapheme + style); the dirty flag is bookkeeping and
+      # is deliberately excluded.
+      # 
+      # _@param_ `other`
+      def ==: (Object other) -> bool
+
+      # Read-only: mutate content through {#set} so dirty tracking stays correct.
+      # 
+      # _@return_ — one grapheme cluster, `" "` for blank, or `""` for a
+      # wide-glyph continuation.
+      attr_reader grapheme: String
+
+      attr_reader style: StyledString::Style
+
+      # _@return_ — true if this cell changed since the last {Buffer#flush}.
+      # {Buffer} flips it (off as it flushes, on via {Buffer#mark_all_dirty}).
+      attr_accessor dirty: bool
+    end
+  end
+
   # The TTY screen. There is exactly one screen per app.
   # 
   # A screen runs the event loop; call {#run_event_loop} to do that.
@@ -698,23 +1038,12 @@ module Tuile
 
     def self.close: () -> void
 
-    # Prints given strings. While {#repaint} is running, writes are
-    # accumulated into a frame buffer and flushed to the terminal as a
-    # single `$stdout.write` at the end of the cycle. This stops the
-    # emulator from rendering half-finished frames (e.g. a layout's
-    # clear-background pass before its children have re-painted), which
-    # was visible as a brief flicker when the auto-clear path triggers.
-    # 
-    # Outside repaint, writes go straight to stdout. We deliberately
-    # don't raise on a "print outside repaint" — that would be a useful
-    # guardrail against components painting outside the repaint loop,
-    # but it'd force terminal-housekeeping writes (`Screen#clear`,
-    # mouse-tracking start/stop, cursor-show on teardown) to bypass
-    # this method entirely and write directly to `$stdout`. {FakeScreen}
-    # overrides `print` to capture every byte into its `@prints` array,
-    # and tests that exercise `run_event_loop` against a real {Screen}
-    # would otherwise leak escape sequences to the test runner's stdout.
-    # Keeping `print` as the single sink preserves that override seam.
+    # Writes terminal-housekeeping escapes straight to stdout: {#clear},
+    # mouse-tracking start/stop, the color-scheme notify toggles, cursor-show
+    # on teardown. Component painting does *not* go through here anymore — it
+    # writes into {#buffer}, which {#repaint} diffs and {#emit}s. {FakeScreen}
+    # overrides this (and {#emit}) to capture into `@prints` instead of the
+    # test runner's stdout.
     # 
     # _@param_ `args` — stuff to print.
     def print: (*String args) -> void
@@ -757,14 +1086,16 @@ module Tuile
     # _@return_ — true if focus moved.
     def cycle_focus: (forward: bool) -> bool
 
-    # Collects a component and all its descendants in tree order
-    # (parent before children).
-    # 
-    # _@param_ `component`
-    def collect_subtree: (Component component) -> ::Array[Component]
+    # The escape sequence positioning the hardware cursor for the current focus
+    # state: hidden when nothing owns it, else moved to the focused component's
+    # {Component#cursor_position} and shown. Appended to each frame's flush.
+    def cursor_sequence: () -> String
 
-    # Hides or moves the hardware cursor based on the current focus state.
-    def position_cursor: () -> void
+    # Writes an assembled frame (escape string) to the terminal. The single
+    # sink for repaint output; {FakeScreen} overrides it to capture instead.
+    # 
+    # _@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
@@ -781,10 +1112,12 @@ module Tuile
     #      doesn'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 popup is open
-    #      (otherwise the popup receives the key normally).
-    #   3. {ScreenPane#handle_key}, which routes to the topmost popup or
-    #      tiled content.
+    #      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.
     # 
     # _@param_ `key`
     # 
@@ -801,6 +1134,13 @@ 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
+
     # Handler invoked when a {StandardError} escapes an event handler inside
     # the event loop (e.g. a {Component::TextField}'s `on_change` raises).
     # 
@@ -862,50 +1202,39 @@ 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. It exists for exactly one job: sizing a
+  # {Component::Popup} against the screen. A popup has no siblings competing for
+  # space and no rectangle in a tiled layout, so "half the screen, centered" is
+  # the sensible default, and that wants a ratio rather than a hard-coded cell
+  # count that would be wrong on the next terminal size.
   # 
-  # Three policies exist:
+  # Tiled components are *not* sized this way: their parent computes explicit
+  # integer rects in its own `rect=` and hands them down. `Fraction` is
+  # deliberately scoped to {Component::Popup#size=} and is not a general layout
+  # primitive.
   # 
-  # - {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.
+  # Resolve it against a reference {Size} (the screen) to get concrete integer
+  # cells:
   # 
-  # 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.
+  #   Fraction::HALF.resolve(Size.new(80, 24))  # => 40x12
   # 
-  # @!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
@@ -950,20 +1279,23 @@ module Tuile
     # Only called when the component is attached.
     def repaint: () -> void
 
-    # Called when a character is pressed on the keyboard.
+    # 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.
     # 
-    # Also called for inactive components. Inactive component should just return
-    # false.
+    # 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.
     # 
-    # Default implementation searches for a component with {#key_shortcut} and
-    # focuses it. The shortcut search is suppressed while the focused component
-    # owns the hardware cursor (e.g. a {Component::TextField} the user is
-    # typing into) so that hotkeys don't steal printable keys from the editor.
-    # 
-    # _@param_ `key` — a key.
+    # _@param_ `_key` — a key.
     # 
     # _@return_ — true if the key was handled, false if not.
-    def handle_key: (String key) -> bool
+    def handle_key: (String _key) -> bool
 
     # _@param_ `key` — keyboard key to look up.
     # 
@@ -1042,20 +1374,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
@@ -1127,15 +1445,6 @@ module Tuile
     # {#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
@@ -1246,19 +1555,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
@@ -1385,9 +1681,9 @@ module Tuile
       # 
       # _@param_ `scrollbar` — scrollbar instance, or nil if not shown.
       # 
-      # _@return_ — paintable ANSI-encoded line exactly `rect.width`
-      # columns wide; highlighted if cursor is here.
-      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> String
+      # _@return_ — paintable line exactly `rect.width` columns wide;
+      # highlighted if cursor is here.
+      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> StyledString
 
       # _@return_ — callback fired when an item is chosen — by pressing
       # Enter on the cursor's item, or by left-clicking an item. Called as
@@ -1556,7 +1852,8 @@ 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}.
       # 
@@ -1568,17 +1865,12 @@ module Tuile
 
       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, padded with trailing spaces out to
-      # the full width, and pre-rendered to ANSI so {#repaint} is just a
-      # lookup + screen.print per row. {@blank_line} covers rows past the
-      # last text line. When {#bg} is set, every produced line (and the
-      # blank row) has the bg applied uniformly.
+      # 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
+      # row. {@blank_line} covers rows past the last text line. When {#bg} is
+      # set, every produced line (and the blank row) has the bg applied
+      # uniformly.
       def update_clipped_lines: () -> void
 
       # _@param_ `line`
@@ -1599,10 +1891,32 @@ module Tuile
       attr_accessor bg: (Color | Symbol | Integer | ::Array[Integer])?
     end
 
-    # A modal overlay that wraps any {Component} as its content. Popup itself
-    # paints nothing — it's a transparent host that handles modality
-    # ({#open} / {#close} / {#open?}, ESC/q to close), centers itself on the
-    # screen, and auto-sizes to the wrapped content.
+    # 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 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) without taking focus
+    # or capturing input — the caller positions it (via {#rect=}) and drives it
+    # from app code. That is the building block for an autocomplete/slash-command
+    # list anchored to a {Component::TextField} or {Component::TextArea} caret:
+    # typing keeps focus (and the cursor) in the input, an
+    # {Component::TextInput#on_change} listener refills the list, and an
+    # {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
+    # Such a caller owns the list data, so it sizes the overlay itself
+    # (`overlay.size = Size.new(longest, [items.size, 8].min)`) — still
+    # caller-decides, top-down.
     # 
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -1622,8 +1936,15 @@ module Tuile
     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.
-      def initialize: (?content: Component?) -> void
+      # _@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).
+      # 
+      # _@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
 
       def focusable?: () -> bool
 
@@ -1638,17 +1959,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
@@ -1656,31 +1980,29 @@ 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,
-      # defaults to 12. Override in a subclass to allow taller popups.
-      def max_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
 
+      # `q` and ESC close the popup. The popup sits on the focus chain of
+      # whatever it wraps, so the key reaches here by bubbling up from the
+      # focused content after that content declined to handle it.
+      # 
       # _@param_ `key`
       # 
       # _@return_ — true if the key was handled.
@@ -1691,21 +2013,15 @@ 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;
@@ -1718,7 +2034,7 @@ 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.length + 4`.
     class Button < Component
       # _@param_ `caption` — the button's label.
       def initialize: (?String caption) -> void
@@ -1735,9 +2051,6 @@ module Tuile
 
       def repaint: () -> void
 
-      # Natural width is `caption.length + 4` to fit `[ caption ]`; height 1.
-      def natural_size: () -> Size
-
       # _@return_ — the button's label.
       attr_accessor caption: String
 
@@ -1779,20 +2092,11 @@ 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`
       def handle_mouse: (MouseEvent event) -> void
 
-      # Called when a character is pressed on the keyboard.
-      # 
-      # _@param_ `key` — a key.
-      # 
-      # _@return_ — true if the key was handled, false if not.
-      def handle_key: (String key) -> bool
-
       def on_focus: () -> void
 
       # Absolute layout. Extend this class, register any children, and
@@ -1820,9 +2124,6 @@ module Tuile
 
       def children: () -> ::Array[Component]
 
-      # _@param_ `key`
-      def handle_key: (String key) -> bool
-
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
@@ -1832,22 +2133,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
@@ -1866,43 +2151,41 @@ module Tuile
       # _@param_ `content`
       def layout: (Component content) -> void
 
-      # Paints the window border.
+      # 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}.
       def repaint_border: () -> void
 
+      # Builds the bottom border line. The corners take the border color; the
+      # interior is plain dashes when a {#footer} component occupies the row
+      # (it overpaints them) or when there's no chrome, otherwise it carries
+      # {#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
+
       # The caption text as it appears in the rendered border, including the
       # shortcut prefix when {#key_shortcut} is set.
       def frame_caption: () -> String
 
-      # Builds the border as a single string with embedded cursor-positioning
-      # escapes, mirroring the layout {TTY::Box.frame} used to produce. Title
-      # is clipped to fit the inner width so the box never overflows {#rect}.
-      # 
-      # _@param_ `caption`
-      def build_frame: (String 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.
+      # 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
 
       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_ — 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)?
 
       # _@return_ — the current caption, empty by default.
       attr_accessor caption: String
@@ -2351,9 +2634,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.
@@ -2394,11 +2674,10 @@ module Tuile
       # 
       # _@param_ `scrollbar`
       # 
-      # _@return_ — paintable ANSI-encoded line exactly `rect.width`
-      # columns wide. Body lines come pre-padded from {#rewrap}, so this
-      # reduces to a memoized {StyledString#to_ansi} read plus an
-      # ASCII-string concat of the scrollbar glyph when one is present.
-      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> String
+      # _@return_ — paintable line exactly `rect.width` columns wide.
+      # Body lines come pre-padded from {#rewrap}, so this reduces to a lookup
+      # plus a concat of the scrollbar glyph when one is present.
+      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> StyledString
 
       # _@return_ — index of the first visible physical line.
       attr_accessor top_line: Integer
@@ -2413,13 +2692,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
@@ -2682,22 +2954,24 @@ module Tuile
 
       def tab_stop?: () -> bool
 
-      # Handles a key. Returns false when the component is inactive. Otherwise
-      # first runs the {Component#handle_key} shortcut search via `super`, then
-      # delegates to {#handle_text_input_key}.
+      # Handles a key. An {#on_key} interceptor (if set) gets first refusal —
+      # a truthy return consumes the key — otherwise it delegates to
+      # {#handle_text_input_key}. Dispatch ({ScreenPane#handle_key}) only routes
+      # keys here when this input is on the focus chain, so there is no
+      # {#active?} gate.
       # 
       # _@param_ `key`
       def handle_key: (String key) -> bool
 
       # Renders `text` on the field's background well, looked up from the
-      # current {Screen#theme} at paint time: {Theme#active_bg} when this
-      # input is on the active (focus) chain, {Theme#input_bg} otherwise —
+      # current {Screen#theme} at paint time: {Theme#active_bg_color} when this
+      # input is on the active (focus) chain, {Theme#input_bg_color} otherwise —
       # visibly a field either way, distinctly highlighted when active.
       # 
       # _@param_ `text`
       # 
-      # _@return_ — ANSI-rendered text.
-      def background: (String text) -> String
+      # _@return_ — text on the field's background well.
+      def background: (String text) -> StyledString
 
       # Input filter for {#text=}. Subclasses override to truncate or reject
       # invalid input. Default coerces to String.
@@ -2760,6 +3034,21 @@ module Tuile
       # _@return_ — one-arg callable, or nil.
       attr_accessor on_change: (Proc | Method)?
 
+      # Optional interceptor consulted before the input's own key handling.
+      # Receives the pressed key; return a truthy value to consume it (the
+      # input then ignores that key), falsy to let normal editing proceed.
+      # 
+      # The keyboard analog of {#on_change}: it lets app code layer behavior
+      # onto an input without subclassing. The motivating case is an
+      # autocomplete / slash-command overlay (a non-modal {Component::Popup}):
+      # while it is open the interceptor claims Up/Down/Enter/ESC and forwards
+      # them to the overlay's list, but lets ordinary characters fall through
+      # so typing keeps editing the field (and {#on_change} keeps refilling the
+      # list).
+      # 
+      # _@return_ — one-arg callable, or nil.
+      attr_accessor on_key: (Proc | Method)?
+
       # Callback fired when ESC is pressed. Defaults to a closure that clears
       # focus (`screen.focused = nil`) so ESC visibly cancels text entry instead
       # of bubbling to the parent — and, in particular, instead of reaching the
@@ -2774,11 +3063,6 @@ module Tuile
     # provide a protected `layout(content)` method which repositions the
     # content component; the mixin manages `@content` itself.
     module HasContent
-      # _@param_ `key` — a key.
-      # 
-      # _@return_ — true if the key was handled, false if not.
-      def handle_key: (String key) -> bool
-
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
@@ -2810,8 +3094,10 @@ module Tuile
       # 
       # _@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) -> Popup
+      def self.open: (String caption, ::Array[String] lines, ?size: (Size | Fraction)) -> Popup
     end
 
     # A {Window} that lists options identified by single keyboard keys, asks
@@ -2828,6 +3114,11 @@ module Tuile
       # _@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
 
@@ -2959,10 +3250,13 @@ 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.
+    # Schedules `block` to fire on the event-loop thread every `seconds`,
+    # passing a 0-based monotonically increasing tick counter. The interval is
+    # in **seconds** — the conventional scheduling unit (`sleep`,
+    # `Concurrent::TimerTask#execution_interval`, …) — so `tick(0.2)` fires five
+    # times a second. Use it for periodic UI refresh from a background task
+    # (poll a status, redraw a clock). For animation, where frames-per-second
+    # is the natural unit, {#tick_fps} reads better.
     # 
     # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
     # stop it.
@@ -2976,8 +3270,15 @@ module Tuile
     # ({Concurrent}.global_timer_set) — adding more tickers does not add more
     # threads, just more work on the shared scheduler.
     # 
-    # _@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_ `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 (`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
@@ -3098,10 +3399,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
@@ -3148,6 +3449,13 @@ module Tuile
     # _@param_ `args`
     def print: (*String args) -> void
 
+    # Captures the assembled repaint frame instead of writing to the test
+    # runner's TTY. Lands in {#prints} so cursor/sync escapes can be asserted;
+    # painted content is read from {#buffer}.
+    # 
+    # _@param_ `str`
+    def emit: (String str) -> void
+
     # _@param_ `component` — the component to check.
     def invalidated?: (Component component) -> bool
 
@@ -3158,7 +3466,10 @@ module Tuile
     # steal its input) and pin the deterministic default.
     def detect_scheme: () -> Symbol
 
-    # _@return_ — whatever {#print} printed so far.
+    # _@return_ — whatever {#print} / {#emit} produced so far.
+    # Component painting lands in {#buffer}, not here — assert on
+    # {Buffer#row_text} / {Buffer#row_ansi} / {Buffer#cell} for content, and
+    # on `prints` for cursor and housekeeping escapes.
     attr_reader prints: ::Array[String]
   end
 
@@ -3236,7 +3547,11 @@ module Tuile
     # status bar last.
     def children: () -> ::Array[Component]
 
-    # Adds a popup, centers it, focuses it, and invalidates it for repaint.
+    # 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.
     # 
     # _@param_ `window`
     def add_popup: (Component::Popup window) -> void
@@ -3253,26 +3568,54 @@ module Tuile
     # _@return_ — true if this pane currently hosts the popup.
     def has_popup?: (Component window) -> bool
 
+    # _@return_ — the topmost *modal* popup, or nil when
+    # only non-modal overlays (or no popups) are open. This is the "modal
+    # owner": the popup that scopes key dispatch, blocks mouse clicks, owns
+    # the status bar, and confines Tab cycling. Non-modal overlays are
+    # excluded — they float above the content without capturing input.
+    def modal_popup: () -> Component::Popup?
+
     # Re-lays out children whenever the pane's own rect changes.
     # 
     # _@param_ `new_rect`
     def rect=: (Rect new_rect) -> void
 
     # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Popups self-position via {Component::Popup#center}.
+    # (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
 
-    # Topmost popup is modal: it eats keys. Falls through to content only
-    # when no popup is open.
+    # 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.
+    # 
+    # _@param_ `key`
+    # 
+    # _@return_ — true if the key was handled.
     def handle_key: (String key) -> bool
 
     # Mouse events check popups in reverse stacking order (topmost first), and
-    # fall through to content only when no popup is hit *and* there are no
-    # popups open. This preserves modal click-blocking: an open popup eats
-    # clicks even outside its rect.
+    # fall through to content only when no popup is hit *and* no modal popup is
+    # open. This preserves modal click-blocking — an open modal eats clicks
+    # even outside its rect — while a non-modal overlay blocks nothing: clicks
+    # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
+    # content beneath.
     # 
     # _@param_ `event`
     def handle_mouse: (MouseEvent event) -> void
@@ -3280,7 +3623,7 @@ module Tuile
     # Focus repair when a child detaches. Default {Component#on_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
     # Instead, route focus to the first interactable widget in the now-topmost
-    # popup; falling back to the focus snapshotted when this popup was opened
+    # modal popup; falling back to the focus snapshotted when this popup was opened
     # (if still attached and still focusable); then to the first interactable
     # widget in {#content}; then to {#content} itself; then nil.
     # 
@@ -3292,6 +3635,19 @@ module Tuile
     # _@param_ `child`
     def on_child_removed: (Component child) -> void
 
+    # Delivers `key` to {Screen#focused} and bubbles it up the ancestor chain,
+    # stopping at (and including) `scope`. Delivers to no one — returning false
+    # — when focus is nil or sits outside `scope`; the latter is what makes an
+    # open popup modal, since focus is always inside it and content beneath
+    # never receives keys.
+    # 
+    # _@param_ `key`
+    # 
+    # _@param_ `scope` — the modal scope root (topmost popup or content).
+    # 
+    # _@return_ — true if some component on the chain handled the key.
+    def bubble_key: (String key, Component scope) -> bool
+
     # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling
     # back to `root` itself when the subtree has no tab stops. Returns `nil`
     # if `root` is `nil`.
@@ -3302,8 +3658,9 @@ module Tuile
     # _@return_ — the tiled content component.
     attr_accessor content: Component?
 
-    # _@return_ — modal popups in stacking order; last is
-    # topmost. The array must not be mutated by callers.
+    # _@return_ — overlay popups in stacking order; last is
+    # topmost. Holds both modal popups and non-modal overlays
+    # ({Component::Popup#modal?}). The array must not be mutated by callers.
     attr_reader popups: ::Array[Component]
 
     # _@return_ — the bottom status bar.
@@ -3496,19 +3853,6 @@ module Tuile
     # _@param_ `spans`
     def normalize: (::Array[Span] spans) -> ::Array[Span]
 
-    # _@param_ `from`
-    # 
-    # _@param_ `to`
-    def sgr_diff: (Style from, Style to) -> String
-
-    # _@param_ `color`
-    # 
-    # _@param_ `target` — `:fg` or `:bg`.
-    # 
-    # _@return_ — SGR codes; `[39]` / `[49]` for the "default" reset
-    # when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
-    def color_codes: (Color? color, target: Symbol) -> ::Array[Integer]
-
     # _@param_ `start_or_range`
     # 
     # _@param_ `len`
@@ -3608,6 +3952,27 @@ module Tuile
       # _@param_ `overrides`
       def merge: (**::Hash[Symbol, Object] overrides) -> Style
 
+      # Minimal SGR escape that transitions a terminal already showing `self`
+      # into `other`: only the attributes that differ are emitted. Returns
+      # `""` when the styles are identical (nothing to do), and {Ansi::RESET}
+      # (`\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
+
+      # _@param_ `color`
+      # 
+      # _@param_ `target` — either `:fg` or `:bg`.
+      # 
+      # _@return_ — SGR codes; `[39]` / `[49]` for the "default"
+      # reset when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
+      def color_codes: (Color? color, target: Symbol) -> ::Array[Integer]
+
       attr_reader fg: Color?
 
       attr_reader bg: Color?
@@ -3723,12 +4088,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