tuile 0.8.0 → 0.9.0

data/sig/tuile.rbs

@@ -535,7 +535,7 @@ module Tuile
   # string needed to bring a terminal — one that already matches the buffer's
   # state as of the previous flush — up to date. Only cells that actually
   # changed are emitted, so nothing flickers regardless of terminal/multiplexer
-  # synchronized-output support. See `ideas/back-buffer.md`.
+  # synchronized-output support.
   # 
   # Coordinates are 0-based `(x, y)` = `(column, row)`, matching
   # {Component#rect} and `TTY::Cursor.move_to`.
@@ -567,8 +567,30 @@ module Tuile
   # nothing for, since the glyph itself advances the cursor two columns).
   # Overwriting either half of a wide glyph blanks the orphaned half, so the
   # grid never holds a dangling continuation or a headless one.
+  # 
+  # ## Future direction
+  # 
+  # Components paint through this drawing surface ({#set_line} / {#set_char})
+  # without knowing whether it is the one global buffer or a private one — that
+  # indirection is deliberate, so per-component back buffers plus a z-order
+  # compositor could drop in without touching component code. It is not worth
+  # doing yet: the diff already drops unchanged cells from the wire, and an
+  # occluded component that didn't change is never repainted at all, so a
+  # compositor would only save residual `repaint` CPU. It pays off in exactly
+  # one regime — high repeat-rate scroll (held arrow / mouse wheel) of a large
+  # component on a large screen, where re-rendering the content each repeat is
+  # the dominant cost.
   class Buffer
     DEFAULT_STYLE: StyledString::Style
+    WIDTH_CACHE: ::Hash[String, Integer]
+
+    # 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
@@ -693,6 +715,29 @@ module Tuile
     # tests asserting styled output.
     def region_ansi: (Rect rect) -> ::Array[String]
 
+    # Core of {#set_char} with the grapheme's display width already known.
+    # {#set_line} computes each width once while advancing the column and passes
+    # it straight through, so the paint hot path measures every grapheme exactly
+    # once (and that once is a {.display_width} memo read). See {#set_char} for
+    # the wide-glyph / clipping / out-of-bounds contract.
+    # 
+    # _@param_ `x` — column.
+    # 
+    # _@param_ `y` — row.
+    # 
+    # _@param_ `grapheme` — one grapheme cluster.
+    # 
+    # _@param_ `w` — `grapheme`'s display width (0, 1, or 2).
+    # 
+    # _@param_ `style`
+    def put_char: (
+                    Integer x,
+                    Integer y,
+                    String grapheme,
+                    Integer w,
+                    StyledString::Style style
+                  ) -> void
+
     # (Re)allocates a blank grid of `size` with clean dirty state. Callers
     # follow with {#mark_all_dirty} when the terminal doesn't match the new
     # grid — construction and {#resize} both do.
@@ -748,13 +793,26 @@ module Tuile
                       StyledString::Style style
                     ) -> void
 
-    # If `(x, y)` is half of a wide glyph, blanks the *other* half, so a write
-    # that lands on either half doesn't strand the remaining one.
+    # If `(x, y)` holds 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 repair_orphans: (Integer x, Integer y) -> void
+    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
 
@@ -1076,6 +1134,9 @@ module Tuile
     # _@return_ — the structural root of the component tree.
     attr_reader pane: ScreenPane
 
+    # _@return_ — `:light` or `:dark`
+    attr_reader color_scheme: Symbol
+
     # _@return_ — the back buffer components paint into
     # ({Buffer#set_line} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader buffer: Buffer
@@ -1141,50 +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.
-    # 
-    # _@param_ `content` — the component's natural extent on this axis (one dimension of its {Component#content_size}).
+    # 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.
     # 
-    # _@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
@@ -1324,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
@@ -1351,18 +1387,6 @@ 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
 
@@ -1421,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
@@ -1540,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
@@ -1850,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}.
       # 
@@ -1862,11 +1865,6 @@ 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 and padded with trailing spaces out to
       # the full width, so {#repaint} is just a lookup + {Buffer#set_line} per
@@ -1895,18 +1893,30 @@ module Tuile
 
     # An overlay that wraps any {Component} as its content. Popup itself
     # paints nothing — it's a transparent host that handles its lifecycle
-    # ({#open} / {#close} / {#open?}, ESC/q to close) and auto-sizes to the
-    # wrapped content.
+    # ({#open} / {#close} / {#open?}, ESC/q to close) and holds a top-down
+    # {#size} the {Screen} applies.
+    # 
+    # The popup does *not* size itself to its content. Its box is declared by
+    # {#size} — a {Fraction} (resolved against the screen every layout pass, so
+    # it tracks resize) or an absolute {Size} (clamped to the screen). The
+    # default is {Fraction::HALF}: half the screen, centered. The wrapped
+    # content then fills that box and handles its own overflow by wrapping and
+    # scrolling, so use content that can — a {Component::TextView} or
+    # {Component::TextArea} — for anything longer than fits. A
+    # {Component::Label} only truncates.
     # 
     # Modal by default: it centers on the screen, grabs focus, eats keys, and
     # blocks clicks beneath it. Pass `modal: false` for a non-modal overlay
-    # that floats above the content (still painted on top, still auto-sized)
-    # without taking focus or capturing input — the caller positions it (via
-    # {#rect=}) and drives it from app code. That is the building block for an
-    # autocomplete/slash-command list anchored to a {Component::TextField} or
-    # {Component::TextArea} caret: typing keeps focus (and the cursor) in the
-    # input, an {Component::TextInput#on_change} listener refills the list, and
-    # an {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
+    # that floats above the content (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
@@ -1926,10 +1936,12 @@ 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.
+      # _@param_ `content` — initial content; can be set later via {#content=}. The content fills the popup's {#rect}; it does not determine the popup's size.
       # 
       # _@param_ `modal` — true (default) for a centered, focus-grabbing, input-capturing modal; false for a non-modal overlay the caller positions and drives (see the class docs).
-      def initialize: (?content: Component?, ?modal: bool) -> void
+      # 
+      # _@param_ `size` — the popup's size, applied top-down. A {Fraction} is resolved against the screen each layout pass; a {Size} is clamped to the screen. Defaults to {Fraction::HALF}.
+      def initialize: (?content: Component?, ?modal: bool, ?size: (Size | Fraction)) -> void
 
       # _@return_ — whether this popup is modal. See {#initialize}.
       def modal?: () -> bool
@@ -1947,17 +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
@@ -1965,38 +1980,21 @@ module Tuile
       # _@return_ — true if this popup is currently mounted on the screen.
       def open?: () -> bool
 
-      # Recenters the popup on the screen, preserving its current width/height.
-      # Called automatically by the screen's layout pass and by {#content=}
-      # when the popup is open.
-      def center: () -> void
-
-      # _@return_ — max height the popup will grow to fit its content.
-      # Defers to the content's {Component#popup_max_height} advice when it
-      # gives one, else defaults to 12. Override in a subclass to allow
-      # taller popups regardless of content.
-      def max_height: () -> Integer
-
-      # _@return_ — min height the popup occupies even when its content
-      # is shorter. Defers to the content's {Component#popup_min_height}
-      # advice when it gives one, else defaults to 0 (size purely to
-      # content) — so a {Component::LogWindow} stays readable while only a
-      # few lines are in without callers wiring up a subclass. Override in a
-      # subclass to keep any popup from collapsing to a couple of rows.
-      # Capped at the same 4/5-of-screen ceiling {#update_rect} applies.
-      def min_height: () -> Integer
-
-      # Sets the popup's content and auto-sizes the popup to fit.
+      # Re-resolves {#size} against the current screen and repositions the popup
+      # *itself* (this is not laying out content — the popup's own rect): a
+      # modal popup recenters; a non-modal overlay keeps its caller-assigned
+      # top-left (only its size follows the screen). Called on {#open}, on
+      # {#size=}, and by the screen's layout pass (so a {Fraction} size tracks
+      # SIGWINCH).
       # 
-      # _@param_ `new_content`
-      def content=: (Component? new_content) -> void
+      # The final rect is computed and assigned in one step rather than sizing
+      # at the origin and then centering: the intermediate origin rect rarely
+      # covers the previous one, which would make {#rect=}'s shrink/move
+      # detection fire a full repaint on every resize.
+      def reposition: () -> void
 
-      # Re-sizes (and recenters, when open) whenever the wrapped content's
-      # natural size changes — e.g. a {Label}'s `text=`, a {List}'s
-      # `add_line`, or a nested {Window} whose own content grew (the window
-      # recomputes its {Component#content_size} and the change bubbles here).
-      # 
-      # _@param_ `_child`
-      def on_child_content_size_changed: (Component _child) -> void
+      # Recenters the popup on the screen, preserving its current width/height.
+      def center: () -> void
 
       # Hint for the status bar: own "q Close" plus the wrapped content's hint.
       def keyboard_hint: () -> String
@@ -2015,21 +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;
@@ -2042,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
@@ -2059,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
 
@@ -2103,8 +2092,6 @@ module Tuile
       # _@param_ `child`
       def remove: (Component child) -> void
 
-      def content_size: () -> Size
-
       # Dispatches the event to the child under the mouse cursor.
       # 
       # _@param_ `event`
@@ -2146,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
@@ -2185,33 +2156,36 @@ module Tuile
       # 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
 
-      # 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
@@ -2660,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.
@@ -2721,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
@@ -2872,18 +2836,6 @@ 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.
@@ -3142,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
@@ -3296,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.
@@ -3313,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
@@ -3435,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
@@ -3617,8 +3581,10 @@ module Tuile
     def rect=: (Rect new_rect) -> void
 
     # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Modal popups self-recenter via {Component::Popup#center};
-    # non-modal overlays keep the position their owner assigned.
+    # (bottom row). Each popup re-resolves its {Component::Popup#size} against
+    # the new screen via {Component::Popup#reposition} — so a {Fraction} size
+    # tracks resize — repositioning itself (modal popups recenter; non-modal
+    # overlays keep the top-left their owner assigned).
     def layout: () -> void
 
     # Pane paints nothing itself; its children paint over the entire rect.
@@ -4122,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