tuile 0.1.0

data/sig/tuile.rbs

@@ -0,0 +1,1502 @@
+# Tuile is a small component-oriented terminal UI framework, built on top of
+# the TTY toolkit. The name is French for a roof tile — a small piece that
+# composes into a larger whole, which mirrors how Tuile UIs are built from
+# {Component}s nested under a single {Screen}.
+module Tuile
+  VERSION: String
+
+  def self.logger: () -> Logger
+
+  # The logger Tuile writes to. Defaults to a null logger, so the gem is
+  # silent unless the host app opts in via `Tuile.logger = ...`. Any object
+  # duck-typing the stdlib `Logger` interface (`debug/info/warn/error/fatal`
+  # taking a string) works — including `TTY::Logger`.
+  def self.logger=: (Logger value) -> Logger
+
+  class Error < StandardError
+  end
+
+  # Constants for keys returned by {.getkey} and helpers for reading them from
+  # stdin. The constants are the raw escape sequences emitted by the terminal;
+  # see https://en.wikipedia.org/wiki/ANSI_escape_code for the encoding.
+  module Keys
+    DOWN_ARROW: String
+    UP_ARROW: String
+    DOWN_ARROWS: ::Array[String]
+    UP_ARROWS: ::Array[String]
+    LEFT_ARROW: String
+    RIGHT_ARROW: String
+    ESC: String
+    HOME: String
+    END_: String
+    PAGE_UP: String
+    PAGE_DOWN: String
+    BACKSPACE: String
+    DELETE: String
+    CTRL_H: String
+    BACKSPACES: ::Array[String]
+    CTRL_U: String
+    CTRL_D: String
+    ENTER: String
+
+    # Grabs a key from stdin and returns it. Blocks until the key is obtained.
+    # Reads a full ESC key sequence; see constants above for some values returned
+    # by this function.
+    # 
+    # _@return_ — key, such as {DOWN_ARROW}.
+    def self.getkey: () -> String
+  end
+
+  # A rectangle, with integer `left`, `top`, `width` and `height`, all 0-based.
+  # 
+  # @!attribute [r] left
+  #   @return [Integer] left edge, 0-based.
+  # @!attribute [r] top
+  #   @return [Integer] top edge, 0-based.
+  # @!attribute [r] width
+  #   @return [Integer] width.
+  # @!attribute [r] height
+  #   @return [Integer] height.
+  class Rect
+    def to_s: () -> String
+
+    # _@return_ — true if either {#width} or {#height} is zero or negative.
+    def empty?: () -> bool
+
+    # _@param_ `point` — new top-left corner.
+    # 
+    # _@return_ — positioned at the new `left`/`top`.
+    def at: (Point point) -> Rect
+
+    # Centers the rectangle — keeps {#width} and {#height} but modifies
+    # {#top} and {#left} so that the rectangle is centered on a screen.
+    # 
+    # _@param_ `screen_size` — screen size
+    # 
+    # _@return_ — moved rectangle.
+    def centered: (Size screen_size) -> Rect
+
+    # Clamp both width and height and return a rectangle.
+    # 
+    # _@param_ `max_size` — the max size
+    def clamp: (Size max_size) -> Rect
+
+    # _@param_ `point`
+    def contains?: (Point point) -> bool
+
+    def size: () -> Size
+
+    def top_left: () -> Point
+
+    # _@return_ — left edge, 0-based.
+    attr_reader left: Integer
+
+    # _@return_ — top edge, 0-based.
+    attr_reader top: Integer
+
+    # _@return_ — width.
+    attr_reader width: Integer
+
+    # _@return_ — height.
+    attr_reader height: Integer
+  end
+
+  # A size with integer `width` and `height`.
+  # 
+  # @!attribute [r] width
+  #   @return [Integer] width.
+  # @!attribute [r] height
+  #   @return [Integer] height.
+  class Size
+    ZERO: Size
+
+    def to_s: () -> String
+
+    # _@return_ — true if either {#width} or {#height} is zero or negative.
+    def empty?: () -> bool
+
+    # _@param_ `width`
+    # 
+    # _@param_ `height`
+    def plus: (Integer width, Integer height) -> Size
+
+    # Clamp both width and height and return a size.
+    # 
+    # _@param_ `max_size` — the max size
+    def clamp: (Size max_size) -> Size
+
+    # Clamp height and return a size.
+    # 
+    # _@param_ `max_height` — the max height
+    def clamp_height: (Integer max_height) -> Size
+
+    # _@return_ — width.
+    attr_reader width: Integer
+
+    # _@return_ — height.
+    attr_reader height: Integer
+  end
+
+  # A point with `x` and `y` integer coordinates, both 0-based.
+  # 
+  # @!attribute [r] x
+  #   @return [Integer] x coordinate, 0-based.
+  # @!attribute [r] y
+  #   @return [Integer] y coordinate, 0-based.
+  class Point
+    def to_s: () -> String
+
+    # _@return_ — x coordinate, 0-based.
+    attr_reader x: Integer
+
+    # _@return_ — y coordinate, 0-based.
+    attr_reader y: Integer
+  end
+
+  # The TTY screen. There is exactly one screen per app.
+  # 
+  # A screen runs the event loop; call {#run_event_loop} to do that.
+  # 
+  # A screen holds the screen lock; any UI modifications must be called from
+  # the event queue.
+  # 
+  # All UI lives under a single {ScreenPane} owned by the screen. Set tiled
+  # content via {#content=}; the pane fills the entire terminal and is
+  # responsible for laying out its children.
+  # 
+  # Modal popups are supported too, via {Component::Popup#open}. They
+  # auto-size to their wrapped content and are drawn centered over the
+  # tiled content.
+  # 
+  # The drawing procedure is very simple: when a window needs repaint, it
+  # invalidates itself, but won't draw immediately. After the keyboard press
+  # event processing is done in the event loop, {#repaint} is called which
+  # then repaints all invalidated windows. This prevents repeated paintings.
+  class Screen
+    # rubocop:disable Style/ClassVars
+    def initialize: () -> void
+
+    # _@return_ — the singleton instance.
+    def self.instance: () -> Screen
+
+    # _@return_ — tiled content (forwarded to {ScreenPane}).
+    def content: () -> Component?
+
+    # _@param_ `content`
+    def content=: (Component content) -> void
+
+    # _@return_ — currently active popup components (forwarded
+    # to {ScreenPane}). The array must not be modified!
+    def popups: () -> ::Array[Component]
+
+    # Checks that the UI lock is held and the current code runs in the "UI
+    # thread".
+    def check_locked: () -> void
+
+    # Clears the TTY screen.
+    def clear: () -> void
+
+    # Invalidates a component: causes the component to be repainted on next
+    # call to {#repaint}.
+    # 
+    # _@param_ `component`
+    def invalidate: (Component component) -> void
+
+    # Internal — use {Component::Popup#open} instead. Adds the popup to
+    # {#pane}, centers and focuses it.
+    # 
+    # _@param_ `window`
+    def add_popup: (Component::Popup window) -> void
+
+    # Runs event loop – waits for keys and sends them to active window. The
+    # function exits when the 'ESC' or 'q' key is pressed.
+    def run_event_loop: () -> void
+
+    # _@return_ — current active tiled component.
+    def active_window: () -> Component?
+
+    # Internal — use {Component::Popup#close} instead. Removes the popup
+    # from {#pane}, repairs focus, and repaints the scene.
+    # 
+    # Does nothing if the window is not open on this screen.
+    # 
+    # _@param_ `window`
+    def remove_popup: (Component::Popup window) -> void
+
+    # Internal — use {Component::Popup#open?} instead.
+    # 
+    # _@param_ `window`
+    # 
+    # _@return_ — true if this popup is currently mounted.
+    def has_popup?: (Component::Popup window) -> bool
+
+    # Testing only — creates new screen, locks the UI, and prevents any
+    # redraws, so that test TTY is not painted over. {FakeScreen#initialize}
+    # self-installs as the singleton, so subsequent {Screen.instance} calls
+    # return the same object.
+    def self.fake: () -> FakeScreen
+
+    def close: () -> void
+
+    def self.close: () -> void
+
+    # Prints given strings.
+    # 
+    # _@param_ `args` — stuff to print.
+    def print: (*String args) -> void
+
+    # Repaints the screen; tries to be as effective as possible, by only
+    # considering invalidated windows.
+    def repaint: () -> void
+
+    # Returns the absolute screen coordinates where the hardware cursor should
+    # sit, or nil if it should be hidden. Only the {#focused} component owns
+    # the cursor: there can be multiple active components (the focus path),
+    # but only one focused.
+    def cursor_position: () -> Point?
+
+    # Collects a component and all its descendants in tree order
+    # (parent before children).
+    # 
+    # _@param_ `component`
+    def collect_subtree: (Component component) -> ::Array[Component]
+
+    # Hides or moves the hardware cursor based on the current focus state.
+    def position_cursor: () -> void
+
+    # Recalculates positions of all windows, and repaints the scene.
+    # Automatically called whenever terminal size changes. Call when the app
+    # starts. {#size} provides correct size of the terminal.
+    def layout: () -> void
+
+    # Called after a popup is closed. Since a popup can cover any window,
+    # top-level component or other popups, we need to redraw everything.
+    def needs_full_repaint: () -> void
+
+    # A key has been pressed on the keyboard. Handle it, or forward to active
+    # window.
+    # 
+    # _@param_ `key`
+    # 
+    # _@return_ — true if the key was handled by some window.
+    def handle_key: (String key) -> bool
+
+    # Finds target window and calls {Component::Window#handle_mouse}.
+    # 
+    # _@param_ `event`
+    def handle_mouse: (MouseEvent event) -> void
+
+    def event_loop: () -> void
+
+    # _@return_ — the structural root of the component tree.
+    attr_reader pane: ScreenPane
+
+    # Handler invoked when a {StandardError} escapes an event handler inside
+    # the event loop (e.g. a {Component::TextField}'s `on_change` raises).
+    # 
+    # The default re-raises, so the exception propagates out of
+    # {#run_event_loop} and crashes the script with a stacktrace — unhandled
+    # exceptions are bugs and should be surfaced loudly.
+    # 
+    # Replace it when the host has somewhere visible to put errors, e.g. a
+    # {Component::LogWindow} wired to {Tuile.logger}:
+    # 
+    #   screen.on_error = lambda do |e|
+    #     Tuile.logger.error("#{e.class}: #{e.message}\n#{e.backtrace&.join("\n")}")
+    #   end
+    # 
+    # The handler runs on the event-loop thread with the UI lock held.
+    # Returning normally keeps the loop alive; raising from within the handler
+    # tears the loop down and propagates out of {#run_event_loop}.
+    # 
+    # _@return_ — one-arg callable receiving the {StandardError} instance.
+    attr_accessor on_error: Proc
+
+    # _@return_ — current screen size.
+    attr_reader size: Size
+
+    # _@return_ — the event queue.
+    attr_reader event_queue: EventQueue
+
+    # _@return_ — currently focused component.
+    attr_accessor focused: Component?
+  end
+
+  # A UI component which is positioned on the screen and draws characters into
+  # its bounding rectangle (in {#repaint}).
+  # 
+  # Component is considered invisible if {#rect} is empty or one of left/top is
+  # negative. The component won't draw when invisible.
+  class Component
+    def initialize: () -> void
+
+    # _@return_ — the screen which owns this component.
+    def screen: () -> Screen
+
+    # Focuses this component. Equivalent to `screen.focused = self`.
+    def focus: () -> void
+
+    # Repaints the component. Default implementation does nothing.
+    # 
+    # The component must fully draw over {#rect}, and must not draw outside of
+    # {#rect}.
+    # 
+    # Tip: use {#clear_background} to clear component background before painting.
+    def repaint: () -> void
+
+    # Called when a character is pressed on the keyboard.
+    # 
+    # Also called for inactive components. Inactive component should just return
+    # false.
+    # 
+    # 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.
+    # 
+    # _@return_ — true if the key was handled, false if not.
+    def handle_key: (String key) -> bool
+
+    # _@param_ `key` — keyboard key to look up.
+    # 
+    # _@return_ — the component whose {#key_shortcut} matches `key`,
+    # or nil.
+    def find_shortcut_component: (String key) -> Component?
+
+    # Handles mouse event. Default implementation focuses this component when
+    # clicked (if {#focusable?}).
+    # 
+    # _@param_ `event`
+    def handle_mouse: (MouseEvent event) -> void
+
+    # _@return_ — true if the component is on the active chain — i.e. it
+    # is the focused component or an ancestor of it. Set by {Screen#focused=}.
+    def active?: () -> bool
+
+    # _@param_ `active` — true if active. Set by {Screen#focused=} as it marks the focus chain (root → focused); not meant to be called directly.
+    def active=: (bool active) -> void
+
+    # Whether this component is a valid focus target. `false` by default —
+    # passive components like {Label} are decoration and don't accept focus.
+    # The flag gates click-to-focus ({#handle_mouse}) and the focus-cascade
+    # in container components ({HasContent#on_focus}, {Layout#on_focus}).
+    # Independent from {#active?}: every component carries the active flag, but
+    # only focusable ones can become a focus target that puts themselves and
+    # their ancestors on the active chain.
+    # 
+    # _@return_ — true if this component can be focused.
+    def focusable?: () -> bool
+
+    # _@return_ — the distance from the root component; 0 if {#parent}
+    # is nil.
+    def depth: () -> Integer
+
+    # _@return_ — the root component of this component hierarchy.
+    def root: () -> Component
+
+    # List of child components, defaults to an empty array.
+    # 
+    # _@return_ — child components. Must not be mutated! May be
+    # empty.
+    def children: () -> ::Array[Component]
+
+    # Calls block for this component and for every descendant component.
+    def on_tree: () ?{ (Component component) -> void } -> void
+
+    # Called when the component receives focus.
+    def on_focus: () -> void
+
+    # _@return_ — true if this component's tree is currently mounted on
+    # the {Screen}, i.e. its root is the {ScreenPane}.
+    def attached?: () -> bool
+
+    # Called by container components after `child` has been detached from
+    # `self.children` (its `parent` is already nil and it is no longer in the
+    # children list). Default behavior repairs dangling focus: if the focused
+    # component lived inside the removed subtree, focus shifts to `self` so the
+    # cursor doesn't dangle on a detached component. No-op if `self` is not
+    # attached to the screen — focus state in a detached subtree is moot.
+    # 
+    # _@param_ `child` — the just-detached child.
+    def on_child_removed: (Component child) -> void
+
+    # The {Size} big enough to show the entire component contents without
+    # scrolling. Plain components have no intrinsic content and report
+    # {Size::ZERO}; container/decorative components (e.g. {Label}, {List},
+    # {Layout}, {Window}) override this to fold in their content's natural
+    # extent. Used by callers like {Component::Popup} to auto-size to
+    # whatever content was assigned, regardless of its concrete type.
+    def content_size: () -> Size
+
+    # 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
+    # consulting the {Screen#focused} component only.
+    # 
+    # _@return_ — absolute screen coordinates, or nil to hide.
+    def cursor_position: () -> Point?
+
+    # _@return_ — formatted keyboard hint surfaced in the status bar by
+    # {Screen} when this component is the active tiled window or the
+    # topmost popup. Empty by default; override to advertise shortcuts.
+    def keyboard_hint: () -> String
+
+    # Called whenever the component width changes. Does nothing by default.
+    def on_width_changed: () -> void
+
+    # Invalidates the component: {Screen} records this component as
+    # needs-repaint and once all events are processed, will call {#repaint}.
+    def invalidate: () -> void
+
+    # Clears the background: prints spaces into all characters occupied by the
+    # component's rect.
+    def clear_background: () -> void
+
+    # _@return_ — the rectangle the component occupies on screen.
+    attr_accessor rect: Rect
+
+    # A global keyboard shortcut. When pressed, will focus this component.
+    # 
+    # _@return_ — shortcut, `nil` by default.
+    attr_accessor key_shortcut: String?
+
+    # _@return_ — the parent component or nil if the component has
+    # no parent.
+    attr_accessor parent: Component?
+
+    # A scrollable list of String items with cursor support.
+    # 
+    # Items are lines painted directly into the component's {#rect}. Lines are
+    # automatically clipped horizontally. Vertical scrolling is supported via
+    # {#top_line}; the list can also automatically scroll to the bottom if
+    # {#auto_scroll} is enabled.
+    # 
+    # Cursor is supported; call {#cursor=} to change cursor behavior. The
+    # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the list
+    # automatically.
+    class List < Component
+      def initialize: () -> void
+
+      # Sets new lines. Each entry is coerced via `#to_s`, split on `\n` into
+      # separate lines, and trailing whitespace stripped — symmetric with
+      # {#add_lines}, so the stored `@lines` is always `Array<String>`.
+      # 
+      # _@param_ `lines` — new lines. Entries need only respond to `#to_s`.
+      def lines=: (::Array[untyped] lines) -> void
+
+      # Without a block, returns the current lines. With a block, fully
+      # re-populates the list:
+      # ```ruby
+      # list.lines do |buffer|
+      #   buffer << "Hello!"
+      # end
+      # ```
+      # 
+      # _@return_ — current lines (when called without a block).
+      def lines: () ?{ (::Array[String] buffer) -> void } -> ::Array[String]
+
+      # Adds a line.
+      # 
+      # _@param_ `line`
+      def add_line: (String line) -> void
+
+      # Appends given lines. Each entry is coerced via `#to_s`, split on `\n`
+      # into separate lines, and trailing whitespace stripped — symmetric with
+      # {#lines=}.
+      # 
+      # _@param_ `lines` — entries need only respond to `#to_s`.
+      def add_lines: (::Array[untyped] lines) -> void
+
+      def content_size: () -> Size
+
+      def focusable?: () -> bool
+
+      # _@param_ `key` — a key.
+      # 
+      # _@return_ — true if the key was handled.
+      def handle_key: (String key) -> bool
+
+      # Moves the cursor to the next line whose text contains `query`
+      # (case-insensitive substring match). Search wraps around the end of the
+      # list. Only lines reachable by the current {#cursor} are considered.
+      # 
+      # _@param_ `query` — substring to match. Empty query never matches.
+      # 
+      # _@param_ `include_current` — when true, the current cursor position is eligible (useful when the query has just changed and the current line may still match); when false, the search starts after the current position (useful for "find next" key bindings that should advance past the current).
+      # 
+      # _@return_ — true if a match was found.
+      def select_next: (String query, ?include_current: bool) -> bool
+
+      # Mirror of {#select_next} that walks the list backwards.
+      # 
+      # _@param_ `query`
+      # 
+      # _@param_ `include_current`
+      # 
+      # _@return_ — true if a match was found.
+      def select_prev: (String query, ?include_current: bool) -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # Paints the list items into {#rect}.
+      def repaint: () -> void
+
+      # _@return_ — true if the cursor sits on a real content line.
+      def cursor_on_item?: () -> bool
+
+      # Calls {#on_item_chosen} with the cursor's current `(index, line)`.
+      # Caller must ensure {#cursor_on_item?}.
+      def fire_item_chosen: () -> void
+
+      # _@param_ `query`
+      # 
+      # _@param_ `include_current`
+      # 
+      # _@param_ `reverse`
+      def search_and_go: (String query, include_current: bool, reverse: bool) -> bool
+
+      # Rotates `candidates` (sorted ascending) so iteration starts from the
+      # position appropriate for "find next" / "find prev" with optional
+      # inclusion of the current.
+      # 
+      # _@param_ `candidates`
+      # 
+      # _@param_ `current`
+      # 
+      # _@param_ `include_current`
+      # 
+      # _@param_ `reverse`
+      def order_for_search: (
+                              ::Array[Integer] candidates,
+                              Integer current,
+                              include_current: bool,
+                              reverse: bool
+                            ) -> ::Array[Integer]
+
+      # Scrolls the viewport so the cursor is visible.
+      def move_viewport_to_cursor: () -> void
+
+      # _@return_ — the max value of {#top_line}.
+      def top_line_max: () -> Integer
+
+      # _@return_ — the number of visible lines.
+      def viewport_lines: () -> Integer
+
+      # Scrolls the list.
+      # 
+      # _@param_ `delta` — negative scrolls up, positive scrolls down.
+      def move_top_line_by: (Integer delta) -> void
+
+      # If auto-scrolling, recalculate the top line.
+      def update_top_line_if_auto_scroll: () -> void
+
+      # _@return_ — whether the scrollbar should be drawn right now.
+      def scrollbar_visible?: () -> bool
+
+      # Trims string exactly to `width` columns.
+      # 
+      # _@param_ `str`
+      # 
+      # _@param_ `width`
+      def trim_to: (String str, Integer width) -> String
+
+      # _@param_ `index` — 0-based index into {#lines}.
+      # 
+      # _@param_ `row_in_viewport` — 0-based row within the viewport.
+      # 
+      # _@param_ `width` — number of columns the line should occupy.
+      # 
+      # _@param_ `scrollbar` — scrollbar instance, or nil if not shown.
+      # 
+      # _@return_ — paintable line exactly `width` columns wide;
+      # highlighted if cursor is here.
+      def paintable_line: (
+                            Integer index,
+                            Integer row_in_viewport,
+                            Integer width,
+                            VerticalScrollBar? scrollbar
+                          ) -> String
+
+      # _@return_ — callback fired when an item is chosen — by pressing
+      # Enter on the cursor's item, or by left-clicking an item. Called as
+      # `proc.call(index, line)` with the chosen 0-based index and its line.
+      # Never fires when the cursor's position is outside the content (e.g.
+      # {Cursor::None}, or empty content).
+      attr_accessor on_item_chosen: Proc?
+
+      # _@return_ — if true and a line is added or new content is set,
+      # auto-scrolls to the bottom.
+      attr_accessor auto_scroll: bool
+
+      # _@return_ — top line of the viewport. 0 or positive.
+      attr_accessor top_line: Integer
+
+      # _@return_ — the list's cursor.
+      attr_accessor cursor: Cursor
+
+      # _@return_ — scrollbar visibility: `:gone` or `:visible`.
+      attr_accessor scrollbar_visibility: Symbol
+
+      # _@return_ — when true, the cursor highlight is painted even while
+      # the list is inactive (e.g. when focus is on a sibling search field).
+      # Defaults to false.
+      attr_accessor show_cursor_when_inactive: bool
+
+      # Tracks cursor position within the list.
+      class Cursor
+        # _@param_ `position` — the initial cursor position.
+        def initialize: (?position: Integer) -> void
+
+        # _@param_ `line_count` — number of lines in the list.
+        # 
+        # _@return_ — positions the cursor can land on, in
+        # ascending order.
+        def candidate_positions: (Integer line_count) -> ::Array[Integer]
+
+        # _@param_ `key` — pressed keyboard key.
+        # 
+        # _@param_ `line_count` — number of lines in the list.
+        # 
+        # _@param_ `viewport_lines` — number of visible lines.
+        # 
+        # _@return_ — true if the cursor moved.
+        def handle_key: (String key, Integer line_count, Integer viewport_lines) -> bool
+
+        # _@param_ `line` — cursor is hovering over this line.
+        # 
+        # _@param_ `event` — the event.
+        # 
+        # _@param_ `line_count` — number of lines in the list.
+        # 
+        # _@return_ — true if the event was handled.
+        def handle_mouse: (Integer line, MouseEvent event, Integer line_count) -> bool
+
+        # Moves the cursor to the new position. Public only because of testing.
+        # 
+        # _@param_ `new_position` — new 0-based cursor position.
+        # 
+        # _@return_ — true if the position changed.
+        def go: (Integer new_position) -> bool
+
+        # _@param_ `lines`
+        # 
+        # _@param_ `line_count`
+        def go_down_by: (Integer lines, Integer line_count) -> bool
+
+        # _@param_ `lines`
+        def go_up_by: (Integer lines) -> bool
+
+        def go_to_first: () -> bool
+
+        # _@param_ `line_count`
+        def go_to_last: (Integer line_count) -> bool
+
+        # _@return_ — 0-based line index of the current cursor position.
+        attr_reader position: Integer
+
+        # No cursor — cursor is disabled.
+        class None < Cursor
+          def initialize: () -> void
+
+          # _@param_ `_key`
+          # 
+          # _@param_ `_line_count`
+          # 
+          # _@param_ `_viewport_lines`
+          def handle_key: (String _key, Integer _line_count, Integer _viewport_lines) -> bool
+
+          # _@param_ `_line`
+          # 
+          # _@param_ `_event`
+          # 
+          # _@param_ `_line_count`
+          def handle_mouse: (Integer _line, MouseEvent _event, Integer _line_count) -> bool
+
+          # _@param_ `_line_count`
+          def candidate_positions: (Integer _line_count) -> ::Array[Integer]
+        end
+
+        # Cursor which can only land on specific allowed lines.
+        class Limited < Cursor
+          # _@param_ `positions` — allowed positions. Must not be empty.
+          # 
+          # _@param_ `position` — initial position.
+          def initialize: (::Array[Integer] positions, ?position: Integer) -> void
+
+          # _@param_ `line`
+          # 
+          # _@param_ `event`
+          # 
+          # _@param_ `_line_count`
+          def handle_mouse: (Integer line, MouseEvent event, Integer _line_count) -> bool
+
+          # _@param_ `line_count`
+          def candidate_positions: (Integer line_count) -> ::Array[Integer]
+
+          # _@param_ `lines`
+          # 
+          # _@param_ `line_count`
+          def go_down_by: (Integer lines, Integer line_count) -> bool
+
+          # _@param_ `lines`
+          def go_up_by: (Integer lines) -> bool
+
+          def go_to_first: () -> bool
+
+          # _@param_ `_line_count`
+          def go_to_last: (Integer _line_count) -> bool
+        end
+      end
+    end
+
+    # A label which shows static text. No word-wrapping; clips long lines.
+    class Label < Component
+      def initialize: () -> void
+
+      # _@param_ `text` — draws this text. May contain ANSI formatting. Clipped automatically.
+      def text=: (String? text) -> void
+
+      def content_size: () -> Size
+
+      def repaint: () -> void
+
+      def on_width_changed: () -> void
+
+      def update_clipped_text: () -> void
+    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.
+    # 
+    # The wrapped content fills the popup's full {#rect}; if you want a frame
+    # and caption, wrap a {Component::Window} (or any subclass — including
+    # {Component::LogWindow}) and let it draw its own border:
+    # 
+    #   window = Component::Window.new("Help")
+    #   window.content = Component::List.new.tap { _1.lines = lines }
+    #   Component::Popup.new(content: window).open
+    # 
+    # Bare content also works (a {Component::Label}, a {Component::List}…), in
+    # which case the popup is borderless.
+    # 
+    # `q` and ESC close the popup. Any nested {Component::TextField} that owns
+    # the hardware cursor swallows printable keys first via the standard
+    # cursor-owner suppression in {Component#handle_key}, so typing `q` into a
+    # text field doesn't dismiss the popup.
+    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
+
+      def focusable?: () -> bool
+
+      # Mounts this popup on the {Screen}.
+      def open: () -> void
+
+      # Constructs and opens a popup in one call.
+      # 
+      # _@param_ `content`
+      # 
+      # _@return_ — the opened popup.
+      def self.open: (?content: Component?) -> Popup
+
+      # Removes this popup from the {Screen}. No-op if not currently open.
+      def close: () -> void
+
+      # _@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.
+      # 
+      # _@param_ `new_content`
+      def content=: (Component? new_content) -> void
+
+      # Hint for the status bar: own "q Close" plus the wrapped content's hint.
+      def keyboard_hint: () -> String
+
+      # _@param_ `key`
+      # 
+      # _@return_ — true if the key was handled.
+      def handle_key: (String key) -> bool
+
+      # Content fills the popup's full rect — Popup has no border to subtract.
+      # 
+      # _@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.
+      def update_rect: () -> void
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def children: () -> ::Array[Component]
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+    end
+
+    # A layout doesn't paint anything by itself: its job is to position child
+    # components.
+    # 
+    # All children must completely cover the contents of a layout: that way,
+    # the layout itself doesn't have to draw and no clipping algorithm is
+    # necessary.
+    class Layout < Component
+      def initialize: () -> void
+
+      def children: () -> ::Array[Component]
+
+      # Adds a child component to this layout.
+      # 
+      # _@param_ `child`
+      def add: ((Component | ::Array[Component]) child) -> void
+
+      # _@param_ `child`
+      def remove: (Component child) -> void
+
+      def content_size: () -> Size
+
+      def repaint: () -> void
+
+      # 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
+      # override {Component#rect=} to reposition the children.
+      class Absolute < Layout
+      end
+    end
+
+    # A window with a frame, a {#caption} and a content {Component}. Doesn't
+    # support overlapping with other windows: it paints its entire contents and
+    # doesn't clip if there are other overlapping windows.
+    # 
+    # The window's `content` is unset by default; assign one via {#content=}.
+    # 
+    # Window is considered invisible if {#rect} is empty or one of left/top is
+    # negative. The window won't draw when invisible.
+    class Window < Component
+      include Tuile::Component::HasContent
+
+      # _@param_ `caption`
+      def initialize: (?String caption) -> void
+
+      def focusable?: () -> bool
+
+      def children: () -> ::Array[Component]
+
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
+
+      # _@param_ `value`
+      def scrollbar=: (bool value) -> void
+
+      # _@return_ — the size needed to fit the window's content, footer
+      # (width only — footer overlays the bottom border), and caption,
+      # plus the 2-character border. Returns {Size}`.new(2, 2)` when the
+      # window has no content, footer, or caption.
+      def content_size: () -> Size
+
+      # _@return_ — true if {#rect} is off screen and the window won't
+      # paint.
+      def visible?: () -> bool
+
+      # Fully repaints the window: both frame and contents.
+      def repaint: () -> void
+
+      # _@param_ `key`
+      def key_shortcut=: (String? key) -> void
+
+      # _@param_ `content`
+      def layout: (Component content) -> void
+
+      # Paints the window border.
+      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
+
+      def layout_footer: () -> void
+
+      def on_focus: () -> void
+
+      # _@return_ — optional component overlaying the bottom border
+      # row.
+      attr_accessor footer: Component?
+
+      # _@return_ — the current caption, empty by default.
+      attr_accessor caption: String
+    end
+
+    # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
+    # log lines into this window:
+    # 
+    #   log_window = Tuile::Component::LogWindow.new
+    #   logger = Logger.new(Tuile::Component::LogWindow::IO.new(log_window))
+    # 
+    # Any logger that writes formatted lines to an IO works the same way —
+    # for example `TTY::Logger` configured with the `:console` handler and
+    # `output: LogWindow::IO.new(window)`.
+    class LogWindow < Tuile::Component::Window
+      # _@param_ `caption`
+      def initialize: (?String caption) -> void
+
+      # IO-shaped adapter that forwards each log line to the owning {LogWindow}.
+      # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
+      # call `output.puts`, e.g. `TTY::Logger`).
+      class IO
+        # _@param_ `window`
+        def initialize: (LogWindow window) -> void
+
+        # _@param_ `string`
+        def write: (String string) -> void
+
+        # _@param_ `string`
+        def puts: (String string) -> void
+
+        # Stdlib `Logger` only treats an object as an IO target when it
+        # responds to both {#write} and {#close}; otherwise it tries to
+        # interpret it as a filename. This is a no-op.
+        def close: () -> void
+      end
+    end
+
+    # A single-line text input field with hardware-cursor caret.
+    # 
+    # The field does not scroll. Any keystroke that would make {#text} longer
+    # than `rect.width - 1` (the last column is reserved for the caret past the
+    # last char) is rejected.
+    # 
+    # The caret is a logical index in `0..text.length`. The hardware cursor is
+    # positioned by {Screen} after each repaint cycle when this component is
+    # focused; see {Component#cursor_position}.
+    class TextField < Component
+      def initialize: () -> void
+
+      def focusable?: () -> bool
+
+      def cursor_position: () -> Point?
+
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      def on_width_changed: () -> void
+
+      # Maximum number of characters {#text} can hold given current width.
+      def max_text_length: () -> Integer
+
+      # _@param_ `char`
+      def insert: (String char) -> bool
+
+      def delete_before_caret: () -> void
+
+      def delete_at_caret: () -> void
+
+      # _@param_ `key`
+      def printable?: (String key) -> bool
+
+      # _@return_ — current text contents.
+      attr_accessor text: String
+
+      # _@return_ — caret index in `0..text.length`.
+      attr_accessor caret: Integer
+
+      # Optional callback fired when ESC is pressed. When set, ESC is consumed
+      # by the field; when nil, ESC falls through to the parent (default
+      # behavior).
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_escape: (Proc | Method)?
+
+      # Optional callback fired whenever {#text} changes. Receives the new text
+      # as a single argument. Not fired by {#caret=} (text unchanged) and not
+      # fired when a setter is a no-op.
+      # 
+      # _@return_ — one-arg callable, or nil.
+      attr_accessor on_change: (Proc | Method)?
+
+      # Optional callback fired when the UP arrow key is pressed. When set, UP
+      # is consumed by the field; when nil, UP falls through to the parent
+      # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
+      # since `k` is a printable character inserted into {#text}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_key_up: (Proc | Method)?
+
+      # Optional callback fired when the DOWN arrow key is pressed. When set,
+      # DOWN is consumed by the field; when nil, DOWN falls through to the
+      # parent (default behavior). Only triggered by {Keys::DOWN_ARROW}, not by
+      # `j`, since `j` is a printable character inserted into {#text}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_key_down: (Proc | Method)?
+
+      # Optional callback fired when ENTER is pressed. When set, ENTER is
+      # consumed by the field; when nil, ENTER falls through to the parent
+      # (default behavior).
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_enter: (Proc | Method)?
+    end
+
+    # A mixin interface for a component with one child tops. The host must
+    # provide a protected `layout(content)` method which repositions the
+    # content component; the mixin manages `@content` itself.
+    module HasContent
+      # _@param_ `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
+
+      def children: () -> ::Array[Component]
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+
+      # _@return_ — the current content component.
+      attr_accessor content: Component?
+    end
+
+    # A {Window} preconfigured with a {List} of static lines. Useful for
+    # showing read-only information.
+    # 
+    # Usable tiled (just add to a {Layout}) or as a popup via {.open}, which
+    # wraps it in a {Popup}.
+    class InfoWindow < Tuile::Component::Window
+      # _@param_ `caption`
+      # 
+      # _@param_ `lines` — initial content; each entry may contain Rainbow formatting.
+      def initialize: (?String caption, ?::Array[String] lines) -> void
+
+      # Opens the info window as a popup.
+      # 
+      # _@param_ `caption`
+      # 
+      # _@param_ `lines` — the content, may contain formatting.
+      # 
+      # _@return_ — the opened popup.
+      def self.open: (String caption, ::Array[String] lines) -> Popup
+    end
+
+    # A {Window} that lists options identified by single keyboard keys, asks
+    # the user to pick one, and fires a callback with the picked key.
+    # 
+    # Usable tiled (just add to a {Layout} and read picks via the block) or
+    # as a popup via {.open}, which wraps it in a {Popup} that closes itself
+    # after a pick. ESC / `q` close without firing the callback.
+    class PickerWindow < Tuile::Component::Window
+      MAX_ITEMS: Integer
+
+      # _@param_ `caption` — the window caption.
+      # 
+      # _@param_ `options` — pairs of keyboard key and option caption. No Rainbow formatting must be used.
+      def initialize: (String caption, ::Array[[String, String]] options) ?{ (String key) -> void } -> void
+
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      def keyboard_hint: () -> String
+
+      # Opens a picker as a popup. Picking an option fires `block`, then
+      # closes the popup; ESC / `q` close without firing `block`.
+      # 
+      # _@param_ `caption`
+      # 
+      # _@param_ `options`
+      # 
+      # _@return_ — the wrapping popup.
+      def self.open: (String caption, ::Array[[String, String]] options) ?{ (String key) -> void } -> Popup
+
+      # _@param_ `key`
+      def select_option: (String key) -> void
+
+      # Callback invoked after the user picks an option (after the block
+      # fires). The {Popup} returned by {.open} sets this to its own `close`.
+      attr_accessor on_pick: Proc?
+
+      # One picker option.
+      # 
+      # @!attribute [r] key
+      #   @return [String] the keyboard key that picks this option.
+      # @!attribute [r] caption
+      #   @return [String] the option caption.
+      class Option
+        # _@return_ — the keyboard key that picks this option.
+        attr_reader key: String
+
+        # _@return_ — the option caption.
+        attr_reader caption: String
+      end
+    end
+  end
+
+  # An event queue. The idea is that all UI-related updates run from the thread
+  # which runs the event queue only; this removes any need for locking and/or
+  # need for thread-safety mechanisms.
+  # 
+  # Any events (keypress, timer, term resize – WINCH) are captured in background
+  # threads; instead of processing the events directly the events are pushed
+  # into the event queue: this causes the events to be processed centrally,
+  # by a single thread only.
+  class EventQueue
+    # _@param_ `listen_for_keys` — if true, fires {KeyEvent}.
+    def initialize: (?listen_for_keys: bool) -> void
+
+    # Posts event into the event queue. The event may be of any type. Since the
+    # event is passed between threads, the event object should be frozen.
+    # 
+    # The function may be called from any thread.
+    # 
+    # _@param_ `event` — the event to post to the queue, should be frozen.
+    def post: (Object event) -> void
+
+    # Submits block to be run in the event queue. Returns immediately.
+    # 
+    # The function may be called from any thread.
+    def submit: () -> void
+
+    # Awaits until the event queue is empty (all events have been processed).
+    def await_empty: () -> void
+
+    # 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
+    # events submitted via {#post}; the block is always called from the thread
+    # running this function.
+    # 
+    # Any exception raised by block is re-thrown, causing this function to
+    # terminate.
+    def run_loop: () ?{ (Object event) -> void } -> void
+
+    # _@return_ — true if this thread is running inside an event queue.
+    def locked?: () -> bool
+
+    # Stops ongoing {#run_loop}. The stop may not be immediate: {#run_loop} may
+    # process a bunch of events before terminating.
+    # 
+    # Can be called from any thread, including the thread which runs the event
+    # loop.
+    def stop: () -> void
+
+    def event_loop: () -> void
+
+    # Starts listening for stdin, firing {KeyEvent} on keypress.
+    def start_key_thread: () -> void
+
+    # Trap the WINCH signal (TTY resize signal) and fire {TTYSizeEvent}.
+    def trap_winch: () -> void
+
+    # A keypress event. See {Keys} for a list of key codes.
+    # 
+    # @!attribute [r] key
+    #   @return [String] key code.
+    class KeyEvent
+      # _@return_ — key code.
+      attr_reader key: String
+    end
+
+    # An error event, causes {EventQueue#run_loop} to throw `StandardError` with
+    # {#error} as its origin.
+    # 
+    # @!attribute [r] error
+    #   @return [StandardError] the underlying error.
+    class ErrorEvent
+      # _@return_ — the underlying error.
+      attr_reader error: StandardError
+    end
+
+    # TTY has been resized. Contains the current width and height of the TTY
+    # terminal.
+    # 
+    # @!attribute [r] width
+    #   @return [Integer] terminal width in columns.
+    # @!attribute [r] height
+    #   @return [Integer] terminal height in rows.
+    class TTYSizeEvent
+      # _@param_ `width`
+      # 
+      # _@param_ `height`
+      def initialize: (width: Integer, height: Integer) -> void
+
+      # _@return_ — event with current TTY size.
+      def self.create: () -> TTYSizeEvent
+
+      def size: () -> Size
+
+      # _@return_ — terminal width in columns.
+      attr_reader width: Integer
+
+      # _@return_ — terminal height in rows.
+      attr_reader height: Integer
+    end
+
+    # Emitted once when the queue is cleared, all messages are processed and the
+    # event loop will block waiting for more messages. Perfect time for
+    # repainting windows.
+    class EmptyQueueEvent
+      include Singleton
+    end
+  end
+
+  # Testing only — a screen which doesn't paint anything and pretends that the
+  # lock is held. This way, the TTY running the tests is not painted over.
+  # 
+  # Intended for unit-testing individual components: instantiate a component,
+  # mutate it, and assert against {#prints} or {#invalidated?}. It does not
+  # run an event loop, so it is *not* suitable for system-testing whole apps
+  # — for that, drive the real script through a PTY (see `spec/examples/`).
+  # 
+  # Call {Screen.fake} to initialize the fake screen easily. Typical usage:
+  # 
+  #   before { Screen.fake }
+  #   after  { Screen.close }
+  # 
+  #   it "paints its content" do
+  #     label = Component::Label.new.tap { |l| l.text = "hi" }
+  #     Screen.instance.content = Component::Window.new("Greeting").tap { |w| w.content = label }
+  #     Screen.instance.repaint
+  #     assert_includes Screen.instance.prints.join, "hi"
+  #   end
+  class FakeScreen < Tuile::Screen
+    def initialize: () -> void
+
+    def check_locked: () -> void
+
+    def clear: () -> void
+
+    # Doesn't print anything: collects all strings in {#prints}.
+    # 
+    # _@param_ `args`
+    def print: (*String args) -> void
+
+    # _@param_ `component` — the component to check.
+    def invalidated?: (Component component) -> bool
+
+    def invalidated_clear: () -> void
+
+    # _@return_ — whatever {#print} printed so far.
+    attr_reader prints: ::Array[String]
+  end
+
+  # A mouse event.
+  # 
+  # @!attribute [r] button
+  #   @return [Symbol, nil] one of `:left`, `:middle`, `:right`, `:scroll_up`,
+  #     `:scroll_down`; `nil` if not known.
+  # @!attribute [r] x
+  #   @return [Integer] x coordinate, 0-based.
+  # @!attribute [r] y
+  #   @return [Integer] y coordinate, 0-based.
+  class MouseEvent
+    # _@return_ — the event's position.
+    def point: () -> Point
+
+    # Checks whether given key is a mouse event key
+    # 
+    # _@param_ `key` — key read via {Keys.getkey}
+    # 
+    # _@return_ — true if it is a mouse event
+    def self.mouse_event?: (String key) -> bool
+
+    # _@param_ `key` — key read via {Keys.getkey}
+    def self.parse: (String key) -> MouseEvent?
+
+    def self.start_tracking: () -> String
+
+    def self.stop_tracking: () -> String
+
+    # _@return_ — one of `:left`, `:middle`, `:right`, `:scroll_up`,
+    # `:scroll_down`; `nil` if not known.
+    attr_reader button: Symbol?
+
+    # _@return_ — x coordinate, 0-based.
+    attr_reader x: Integer
+
+    # _@return_ — y coordinate, 0-based.
+    attr_reader y: Integer
+  end
+
+  # The structural root of the {Screen}'s component tree.
+  # 
+  # {Screen} is a singleton runtime owner (event loop, lock, terminal IO,
+  # invalidation set). All actual UI lives under a {ScreenPane}: the tiled
+  # {#content}, the modal {#popups} stack, and the bottom {#status_bar}.
+  # Putting them under a single Component parent gives focus traversal a real
+  # root, makes {Component#attached?} a one-liner, and lets popup-focus repair
+  # fall out of the standard {Component#on_child_removed} hook.
+  # 
+  # The pane is not a {Component::Layout}: popups deliberately overlap content
+  # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
+  # modal-popup rules rather than active-child dispatch.
+  class ScreenPane < Tuile::Component
+    def initialize: () -> void
+
+    def focusable?: () -> bool
+
+    # Children for tree traversal: content first, popups in stacking order,
+    # status bar last.
+    def children: () -> ::Array[Component]
+
+    # Adds a popup, centers it, focuses it, and invalidates it for repaint.
+    # 
+    # _@param_ `window`
+    def add_popup: (Component::Popup window) -> void
+
+    # Removes a popup. If the popup held focus, focus shifts to the now-topmost
+    # remaining popup, falling back to the focus snapshotted when the popup
+    # was opened (if still attached), then to {#content}, then to nil.
+    # 
+    # _@param_ `window`
+    def remove_popup: (Component window) -> void
+
+    # _@param_ `window`
+    # 
+    # _@return_ — true if this pane currently hosts the popup.
+    def has_popup?: (Component window) -> bool
+
+    # 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}.
+    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.
+    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.
+    # 
+    # _@param_ `event`
+    def handle_mouse: (MouseEvent event) -> void
+
+    # 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 now-topmost popup, then to the prior focus
+    # snapshotted when this popup was opened (if still attached), then to
+    # content, then nil.
+    # 
+    # _@param_ `child`
+    def on_child_removed: (Component child) -> void
+
+    # _@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.
+    attr_reader popups: ::Array[Component]
+
+    # _@return_ — the bottom status bar.
+    attr_reader status_bar: Component::Label
+  end
+
+  # A "synchronous" event queue – no loop is run, submitted blocks are run right
+  # away and submitted events are thrown away. Intended for testing only.
+  class FakeEventQueue
+    def locked?: () -> bool
+
+    def stop: () -> void
+
+    def run_loop: () -> void
+
+    def await_empty: () -> void
+
+    def submit: () -> void
+
+    # _@param_ `event`
+    def post: (Object event) -> void
+  end
+
+  # A vertical scrollbar that computes which character to draw at each row.
+  # 
+  # Uses `█` for the handle (filled track) and `░` for the empty track. There
+  # are no up/down arrows; the full height is used as the track. Handle
+  # geometry is precomputed in the constructor as {#handle_height},
+  # {#handle_start}, and {#handle_end}.
+  class VerticalScrollBar
+    # _@param_ `height` — number of rows in the scrollbar (== viewport height).
+    # 
+    # _@param_ `line_count` — total number of content lines.
+    # 
+    # _@param_ `top_line` — index of the first visible content line.
+    def initialize: (Integer height, line_count: Integer, top_line: Integer) -> void
+
+    # Returns the scrollbar character for the given viewport row.
+    # 
+    # _@param_ `row_in_viewport` — 0-based row index within the viewport.
+    # 
+    # _@return_ — single scrollbar character.
+    def scrollbar_char: (Integer row_in_viewport) -> String
+
+    # _@return_ — number of track rows the handle occupies (height >= 1
+    # only).
+    attr_reader handle_height: Integer
+
+    # _@return_ — 0-based row where the handle starts (height >= 1 only).
+    attr_reader handle_start: Integer
+
+    # _@return_ — 0-based row where the handle ends (height >= 1 only).
+    attr_reader handle_end: Integer
+  end
+end