tuile 0.7.0 → 0.8.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,286 @@ 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. See `ideas/back-buffer.md`.
+  # 
+  # 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.
+  class Buffer
+    DEFAULT_STYLE: StyledString::Style
+
+    # _@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]
+
+    # (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)` is half of a wide glyph, blanks the *other* half, so a write
+    # that lands on either half doesn't strand the remaining one.
+    # 
+    # _@param_ `x` — column
+    # 
+    # _@param_ `y` — row
+    def repair_orphans: (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 +980,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 +1028,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 +1054,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 +1076,10 @@ module Tuile
     # _@return_ — the structural root of the component tree.
     attr_reader pane: ScreenPane
 
+    # _@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).
     # 
@@ -950,20 +1229,23 @@ module Tuile
     # Only called when the component is attached.
     def repaint: () -> void
 
-    # Called when a character is pressed on the keyboard.
-    # 
-    # Also called for inactive components. Inactive component should just return
-    # false.
+    # 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.
     # 
-    # 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.
+    # 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.
     # 
-    # _@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.
     # 
@@ -1069,6 +1351,18 @@ 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?
+
+    # 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 whenever the component width changes. Does nothing by default.
     def on_width_changed: () -> void
 
@@ -1385,9 +1679,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
@@ -1574,11 +1868,11 @@ module Tuile
       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 +1893,20 @@ 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 auto-sizes to the
+    # wrapped content.
+    # 
+    # 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.
     # 
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -1623,7 +1927,12 @@ module Tuile
       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_ `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
+
+      # _@return_ — whether this popup is modal. See {#initialize}.
+      def modal?: () -> bool
 
       def focusable?: () -> bool
 
@@ -1661,10 +1970,21 @@ module Tuile
       # 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.
+      # _@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.
       # 
       # _@param_ `new_content`
@@ -1681,6 +2001,10 @@ module Tuile
       # 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.
@@ -1786,13 +2110,6 @@ module Tuile
       # _@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 +2137,6 @@ module Tuile
 
       def children: () -> ::Array[Component]
 
-      # _@param_ `key`
-      def handle_key: (String key) -> bool
-
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
@@ -1866,20 +2180,15 @@ 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
 
       # 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
@@ -2394,11 +2703,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
@@ -2564,6 +2872,18 @@ module Tuile
       # _@param_ `caption`
       def initialize: (?String caption) -> void
 
+      # 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
+
+      # 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
+
       # 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.
@@ -2682,22 +3002,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 +3082,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 +3111,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
 
@@ -2828,6 +3160,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
 
@@ -3148,6 +3485,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 +3502,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 +3583,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 +3604,52 @@ 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). Modal popups self-recenter via {Component::Popup#center};
+    # non-modal overlays keep the position 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 +3657,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 +3669,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 +3692,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 +3887,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 +3986,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?