tuile 0.4.0 → 0.5.0

data/sig/tuile.rbs

@@ -188,6 +188,70 @@ module Tuile
     attr_reader height: Integer
   end
 
+  # An immutable terminal color. Accepts the three forms ANSI/SGR understands:
+  # 
+  # - a Symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright named colors
+  #   (SGR 30..37 / 90..97 for fg, 40..47 / 100..107 for bg)
+  # - an Integer 0..255 — the 256-color palette (SGR 38;5;N / 48;5;N)
+  # - an Array of three Integers 0..255 — 24-bit RGB (SGR 38;2;R;G;B / 48;2;R;G;B)
+  # 
+  # A constant per named color is pre-defined (`Color::RED`, `Color::BRIGHT_BLUE`,
+  # …) so callers can reach for `Color::RED` instead of building one each time.
+  # {.coerce} accepts anything {.new} accepts plus `nil` (terminal default) and
+  # an existing {Color} (returned as-is), so APIs that accept colors typically
+  # take `[Color, nil]` and pass through {.coerce}.
+  # 
+  # ```ruby
+  # Color.new(:red)              # named
+  # Color.new(42)                # 256-color palette
+  # Color.new([255, 100, 0])     # RGB
+  # Color::RED                   # constant
+  # Color.coerce(:red)           # accepts raw forms, returns Color
+  # Color.coerce(nil)            # nil → nil
+  # ```
+  # 
+  # {#to_ansi} renders a full SGR escape (`"\e[31m"`); {#sgr_codes} returns the
+  # raw numeric codes so callers (notably {StyledString}) can combine them with
+  # other SGR attributes in a single sequence.
+  class Color
+    COLOR_SYMBOLS: ::Array[Symbol]
+
+    # Coerces the input to a {Color}. `nil` passes through unchanged (callers
+    # use `nil` for the terminal default); an existing {Color} is returned
+    # as-is; otherwise the value is fed to {.new}.
+    # 
+    # _@param_ `value`
+    def self.coerce: ((Color | Symbol | Integer | ::Array[Integer])? value) -> Color?
+
+    # _@param_ `value` — see class-level docs for the three accepted forms.
+    def initialize: ((Symbol | Integer | ::Array[Integer]) value) -> void
+
+    # SGR parameter codes for emitting this color as either a foreground
+    # (`target: :fg`) or background (`target: :bg`). Returned as an array so
+    # callers can splice them into a multi-attribute SGR (e.g. bold + color).
+    # 
+    # _@param_ `target` — `:fg` or `:bg`.
+    def sgr_codes: (?Symbol target) -> ::Array[Integer]
+
+    # Full SGR escape sequence for this color (e.g. `"\e[31m"`). Useful for
+    # `print`-style direct emission; for composing with other attributes use
+    # {#sgr_codes} instead.
+    # 
+    # _@param_ `target` — `:fg` or `:bg`.
+    def to_ansi: (?Symbol target) -> String
+
+    # _@param_ `other`
+    def ==: (Object other) -> bool
+
+    def hash: () -> Integer
+
+    def inspect: () -> String
+
+    # The underlying raw representation — a Symbol, Integer, or frozen
+    # Array<Integer>.
+    attr_reader value: (Symbol | Integer | ::Array[Integer])
+  end
+
   # A point with `x` and `y` integer coordinates, both 0-based.
   # 
   # @!attribute [r] x
@@ -1109,9 +1173,13 @@ module Tuile
       # 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.
+      # 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`
+      def apply_bg: (StyledString line) -> StyledString
+
       # _@param_ `line`
       # 
       # _@param_ `width`
@@ -1120,6 +1188,11 @@ module Tuile
       # _@return_ — the current text. Defaults to an empty
       # {StyledString}.
       attr_accessor text: (StyledString | String)?
+
+      # _@return_ — background color applied uniformly across every
+      # painted row (including padding past the text). `nil` (default)
+      # leaves whatever bg the text's own styling carries.
+      attr_accessor bg: (Color | Symbol | Integer | ::Array[Integer])?
     end
 
     # A modal overlay that wraps any {Component} as its content. Popup itself
@@ -1513,9 +1586,27 @@ module Tuile
       # honored); a `StyledString` is used as-is; `nil` is coerced to an
       # empty {StyledString}.
       # 
+      # Detaches every existing {Region} (including the original default)
+      # and installs a fresh internal default region that owns all the new
+      # hard lines. Any handle the caller was holding becomes detached and
+      # raises on use — see {Region#attached?}. The no-op short-circuit
+      # (matching value, same {StyledString}) preserves existing regions.
+      # 
       # _@param_ `value`
       def text=: ((String | StyledString)? value) -> void
 
+      # Creates a new empty {Region} at the spatial tail of the document
+      # and returns its handle. Subsequent {#append} / {#<<} / {#add_line}
+      # calls route through this new region (since it is now the spatial
+      # tail). Earlier regions keep their content and their handles stay
+      # valid; their {Region#range} shifts as later regions grow.
+      # 
+      # Apps streaming logically-distinct sections (e.g. an LLM's "thinking"
+      # vs. "assistant" output) create one region per section, hold the
+      # handles, and call `region.append` / `region.text=` directly when
+      # they need to grow or rewrite an earlier section.
+      def create_region: () -> Region
+
       # _@return_ — true iff {#text} is empty (no hard lines).
       def empty?: () -> bool
 
@@ -1568,6 +1659,56 @@ module Tuile
       # _@param_ `n` — number of hard lines to drop; must be >= 0.
       def remove_last_n_lines: (Integer n) -> void
 
+      # Replaces a contiguous range of hard lines with the parsed content
+      # of `str`. The replacement is parsed exactly like {#text=} and
+      # {#append}: a {String} is run through {StyledString.parse} (so
+      # embedded ANSI is honored), a {StyledString} is used as-is, `nil`
+      # behaves like an empty replacement (the range is deleted). Embedded
+      # `"\n"` in the replacement produces multiple hard lines, so a single
+      # `replace` can grow or shrink the buffer.
+      # 
+      # `range` selects which hard lines to swap out:
+      # 
+      # - an `Integer` `n` is shorthand for `n..n` (replace one existing
+      #   line — `n` must be in `[0, hard-line count)`);
+      # - a non-empty `Range` of hard-line indices replaces those lines;
+      # - an empty `Range` (e.g. `2...2`, or the canonical end-insertion
+      #   `hard_lines.size...hard_lines.size`) is *insertion* at that
+      #   position — no lines are removed. {#insert} is a thin alias for
+      #   this case.
+      # 
+      # Endpoints must be non-negative integers; `begin` may equal
+      # `hard-line count` (insertion at the end), `end` may not exceed
+      # `hard-line count - 1`. `nil` endpoints (beginless / endless ranges)
+      # are not accepted.
+      # 
+      # Cost is roughly `O(from + length + new content)`: the splice
+      # updates only the affected slice of the physical-row buffer, using
+      # the per-hard-line wrap-count cache to locate the starting offset
+      # without re-wrapping preceding lines. Lines outside the splice are
+      # never re-wrapped. {#top_line} is clamped if the new line count
+      # puts it past the end; {#auto_scroll} pins it to the bottom as
+      # usual. The call is a no-op (no invalidation) when the parsed
+      # replacement equals the covered range (vacuously true for an empty
+      # range plus empty replacement, so `replace(n...n, "")` is a cheap
+      # no-op).
+      # 
+      # _@param_ `range` — hard-line indices to replace.
+      # 
+      # _@param_ `str` — replacement content.
+      def replace: ((::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+      # Inserts `str` at hard-line index `at`. Equivalent to
+      # `replace(at...at, str)` — a no-removal splice that grows the buffer
+      # by the parsed line count. `at == hard-line count` is allowed and
+      # appends at the end; for that case {#append} / {#add_line} are
+      # usually more idiomatic.
+      # 
+      # _@param_ `at` — 0-based hard-line index in `[0, hard-line count]`.
+      # 
+      # _@param_ `str` — content to insert.
+      def insert: (Integer at, (String | StyledString)? str) -> void
+
       # Clears the text. Equivalent to `text = ""`.
       def clear: () -> void
 
@@ -1593,41 +1734,164 @@ module Tuile
       # this hook.
       def on_width_changed: () -> void
 
+      # Validates and unpacks a {#replace}-style range argument into
+      # inclusive `[from, to]` line indices. An `Integer` `n` becomes
+      # `[n, n]` (which must point at an existing line — `Integer` is
+      # never insertion sugar). A `Range` is normalized for
+      # `exclude_end?`; `to == from - 1` is a valid empty range
+      # (insertion at `from`), and `from` may equal `size` for
+      # end-insertion. Shared by {#replace} and {Region#replace};
+      # `size` is the buffer or region line count, and `what` is the
+      # entity name woven into error messages.
+      # 
+      # _@param_ `range`
+      # 
+      # _@param_ `size`
+      # 
+      # _@param_ `what`
+      def normalize_replace_range: ((::Range[untyped] | Integer) range, ?Integer size, ?String what) -> [Integer, Integer]
+
+      # Hard-line index where `region` begins in {@hard_lines} — derived
+      # by summing the line counts of all regions that precede it.
+      # 
+      # _@param_ `region`
+      def region_start_index: (Region region) -> Integer
+
+      # Joined {StyledString} of the hard lines that `region` owns. Mirrors
+      # {#text} but scoped to one region.
+      # 
+      # _@param_ `region`
+      def text_for_region: (Region region) -> StyledString
+
+      # Replaces all of `region`'s hard lines with the parsed content of
+      # `value`. Symmetric with {#text=}, scoped to one region. Empty/nil
+      # content empties the region (no visible blank line). Works on
+      # already-empty regions (insertion at the region's position).
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `value`
+      def set_region_text: (Region region, (String | StyledString)? value) -> void
+
+      # Region-scoped {#replace}. Validates `range` against
+      # `region.line_count`, translates region-relative indices to
+      # absolute buffer indices, splices, and updates the region's count.
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `range`
+      # 
+      # _@param_ `str`
+      def replace_in_region: (Region region, (::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+      # Verbatim append into `region`.
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `str`
+      def append_to_region: (Region region, (String | StyledString)? str) -> void
+
+      # Drops the last `n` hard lines from `region`'s tail via
+      # {#splice_hard_lines}. `n` is clamped to the region's current
+      # line count; callers guarantee `n > 0` and the region is
+      # non-empty (the {Region#remove_last_n_lines} guard handles the
+      # no-op cases).
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `n`
+      def remove_last_n_from_region: (Region region, Integer n) -> void
+
+      # Drops `region` from {@regions}: its hard lines are removed via
+      # {#splice_hard_lines}, the handle is detached, and the always-one
+      # default is restored if the removal would have left zero regions.
+      # Skips the rewrap / invalidate work when the region was empty
+      # (the buffer didn't change), but always detaches.
+      # 
+      # _@param_ `region`
+      def remove_region: (Region region) -> void
+
+      # Adjusts region line counts after a {@hard_lines} splice that
+      # removed `removed_count` lines at index `from` and inserted
+      # `added_count` in their place. Two passes:
+      # 
+      # 1. Subtract each region's overlap with the removed range (uses
+      #    the original counts to compute positions). Remember the first
+      #    region that lost lines — that's the natural home for the
+      #    replacement content.
+      # 2. Credit `added_count` to that region. For pure insertions (no
+      #    removal), there's no "first overlapping region" to pick from;
+      #    walk regions and credit the latest one starting at `from` (the
+      #    boundary tiebreaker matches the spatial-tail-routing of
+      #    {#append}). Past-the-end inserts fall back to the tail region.
+      # 
+      # _@param_ `from`
+      # 
+      # _@param_ `removed_count`
+      # 
+      # _@param_ `added_count`
+      def update_region_counts: (Integer from, Integer removed_count, Integer added_count) -> void
+
       # _@return_ — number of visible lines.
       def viewport_lines: () -> Integer
 
       # _@return_ — the max value of {#top_line} for scroll-key clamping.
       def top_line_max: () -> Integer
 
-      # Recomputes {@physical_lines} for the current text and wrap width,
-      # pre-padding every line to `wrap_width` so {#paintable_line} is just
-      # a lookup + optional scrollbar-char append at paint time (and the
-      # rendered ANSI is cached on each line via {StyledString#to_ansi}'s
-      # memoization, so re-painting on scroll is near-free). Clamps
-      # {@top_line} if the new line count puts it out of range.
+      # Full rebuild of {@physical_lines} and {@hard_line_wrap_counts}
+      # from {@hard_lines}. Called when wrap width changes (which
+      # invalidates every cached row count) and from {#text=} (which
+      # replaces the whole logical model). Mid-buffer mutators splice
+      # incrementally via {#splice_hard_lines} and do *not* go through
+      # here. Clamps {@top_line} if the new line count puts it out of
+      # range.
       def rewrap: () -> void
 
-      # Wraps `hard_line` at `width` and appends the padded physical lines
-      # to {@physical_lines}. Empty hard lines (e.g. from a `"\n\n"` run)
-      # and degenerate `width <= 0` both emit a single {@blank_line} row,
-      # matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
-      # would have produced for those cases.
+      # Wraps `hard_line` at `width` and returns the padded physical rows
+      # alongside the row count. Empty hard lines (e.g. from a `"\n\n"`
+      # run) and degenerate `width <= 0` both emit a single {@blank_line}
+      # row, matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
+      # would have produced.
       # 
-      # _@param_ `hard_line` — one hard-broken line (no embedded `"\n"`).
+      # _@param_ `hard_line`
       # 
       # _@param_ `width`
-      def append_physical_lines: (StyledString hard_line, Integer width) -> void
+      def wrap_hard_line: (StyledString hard_line, Integer width) -> [::Array[StyledString], Integer]
 
-      # Pops from {@physical_lines} the rows that `hard_line` previously
-      # contributed (the inverse of {#append_physical_lines} for the same
-      # input). Used by {#append} when extending the last hard line: its
-      # old wrapped rows are dropped, then the extended hard line is
-      # re-wrapped and appended.
+      # Appends `hard_line` to the tail of {@hard_lines}, updating the
+      # wrap-count cache and {@physical_lines} in lockstep.
       # 
       # _@param_ `hard_line`
       # 
       # _@param_ `width`
-      def drop_physical_rows_for: (StyledString hard_line, Integer width) -> void
+      def push_hard_line: (StyledString hard_line, Integer width) -> void
+
+      # Pops the last hard line, the corresponding cache entry, and the
+      # physical rows that hard line contributed. Returns the popped
+      # hard line.
+      def pop_hard_line: () -> StyledString
+
+      # Splices `new_hard_lines` into the buffer in place of the `count`
+      # hard lines starting at index `from`. Updates {@hard_lines},
+      # {@hard_line_wrap_counts}, and {@physical_lines} consistently.
+      # The starting physical-row offset is computed in O(`from`) integer
+      # adds via the cache — no wraps of preceding hard lines. Wraps are
+      # done only for the new content, so total cost is
+      # `O(from + count + new_hard_lines.sum(&:display_width))`.
+      # 
+      # _@param_ `from`
+      # 
+      # _@param_ `count` — number of existing hard lines to remove.
+      # 
+      # _@param_ `new_hard_lines`
+      def splice_hard_lines: (Integer from, Integer count, ::Array[StyledString] new_hard_lines) -> void
+
+      # _@param_ `idx`
+      # 
+      # _@return_ — the {@physical_lines} index where the hard line
+      # at {@hard_lines}`[idx]` starts. O(`idx`) integer adds via the
+      # wrap-count cache.
+      def phys_offset_at: (Integer idx) -> Integer
 
       # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
       # default-styled `"\n"` between hard lines. Called from the {#text}
@@ -1691,6 +1955,136 @@ module Tuile
       # `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
+      # has at least one region, an internal default that owns whatever
+      # hard lines aren't claimed by an app-created region.
+      # 
+      # Apps don't construct regions directly; call {TextView#create_region}
+      # to get one. The handle stays valid as long as the region is
+      # attached — i.e. until {TextView#text=} (or {TextView#clear}) wipes
+      # the slate and installs a fresh internal default. Detached regions
+      # raise {RuntimeError} on every mutator and reader.
+      # 
+      # A region's position is derived from its sibling order and counts,
+      # so growing or shrinking an earlier region implicitly shifts the
+      # ranges of all later regions. Empty regions occupy zero rows but
+      # still hold a position in the sequence; `region.text = ""` collapses
+      # a region's visible footprint without detaching it. Pre-creating
+      # empty placeholder regions is supported and is the natural pattern
+      # for "I'll fill this in later" layouts.
+      class Region
+        # _@param_ `view` — the owning view (never `nil` at construction).
+        # 
+        # _@param_ `line_count` — number of hard lines this region owns.
+        def initialize: (TextView view, ?Integer line_count) -> void
+
+        # _@return_ — `true` while the region is owned by its
+        # {TextView}. Becomes `false` permanently once detached
+        # (typically by {TextView#text=} / {TextView#clear}).
+        def attached?: () -> bool
+
+        # _@return_ — true iff the region owns zero hard lines.
+        # Empty regions render nothing — they still hold a position in
+        # the sequence, so subsequent mutations route to them as usual.
+        def empty?: () -> bool
+
+        # _@return_ — the joined content of just this region's
+        # hard lines. Empty regions return {StyledString::EMPTY}.
+        def text: () -> StyledString
+
+        # Replaces all of this region's hard lines with the parsed content
+        # of `value`. Accepts the same inputs as {TextView#text=}; empty
+        # or `nil` content collapses the region to zero hard lines.
+        # 
+        # _@param_ `value`
+        def text=: ((String | StyledString)? value) -> void
+
+        # Verbatim append into this region's tail. Same semantics as
+        # {TextView#append} but scoped to the region: embedded `"\n"`
+        # creates new hard lines within the region, no-leading-newline
+        # input extends the region's last hard line. Empty / `nil` input
+        # is a no-op (but still raises when detached). When the region is
+        # the spatial tail of the view, this uses the incremental
+        # {TextView#append} path; mid-document regions splice the affected
+        # slice of the physical-row buffer (lines outside the region are
+        # not re-wrapped).
+        # 
+        # _@param_ `str`
+        def append: ((String | StyledString)? str) -> void
+
+        # _@return_ — the hard-line indices this region currently
+        # occupies — `start...(start + line_count)`. Empty regions
+        # return a degenerate exclusive range at their position (e.g.
+        # `5...5`). The result is computed on each call and so always
+        # reflects sibling mutations.
+        def range: () -> ::Range[untyped]
+
+        # Removes this region from its view. The region's hard lines (if
+        # any) are deleted from the buffer — subsequent regions' ranges
+        # shift up by `line_count` — and the handle detaches permanently.
+        # The view keeps its always-≥1-region invariant: if this was the
+        # only remaining region, a fresh internal default is installed
+        # (the app doesn't get a handle to it; call
+        # {TextView#create_region} again to start tracking).
+        # 
+        # Idempotent: calling `remove` on an already-detached region is a
+        # silent no-op (unlike the other mutators, which raise). This
+        # lets cleanup paths blindly call `remove` without first checking
+        # {#attached?}.
+        def remove: () -> void
+
+        # Appends `str` as a new entry in this region: starts a fresh
+        # hard line first (when the region is non-empty), then appends
+        # `str`. Scoped equivalent of {TextView#add_line}. On an empty
+        # region behaves like {#append}.
+        # 
+        # _@param_ `str`
+        def add_line: ((String | StyledString)? str) -> void
+
+        # Replaces a contiguous range of this region's hard lines with the
+        # parsed content of `str`. Region-scoped counterpart of
+        # {TextView#replace}: indices are 0-based **within the region**
+        # (so `replace(0, "x")` rewrites the region's first line, not
+        # the buffer's). Same range conventions apply — `Integer`,
+        # inclusive/exclusive `Range`, empty range as insertion at
+        # `begin`, and `begin == line_count` for end-insertion.
+        # 
+        # _@param_ `range` — region-relative hard-line indices.
+        # 
+        # _@param_ `str` — replacement content.
+        def replace: ((::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+        # Inserts `str` at region-relative hard-line index `at`.
+        # Equivalent to `replace(at...at, str)`. Region-scoped counterpart
+        # of {TextView#insert}; `at == line_count` is allowed and appends
+        # at the region's tail.
+        # 
+        # _@param_ `at` — region-relative index in `[0, line_count]`.
+        # 
+        # _@param_ `str`
+        def insert: (Integer at, (String | StyledString)? str) -> void
+
+        # Drops the last `n` hard lines from this region's tail.
+        # Subsequent regions' ranges shift up by the number actually
+        # dropped. `n` is clamped to {#line_count}, so passing a large
+        # `n` empties the region — the handle stays attached (use
+        # {#remove} when the goal is to drop the region itself).
+        # `n == 0` and an already-empty region are no-ops.
+        # 
+        # _@param_ `n`
+        def remove_last_n_lines: (Integer n) -> void
+
+        def detach!: () -> void
+
+        def check_attached: () -> void
+
+        # _@return_ — number of hard lines this region owns. Safe to
+        # read on a detached region (no error raised).
+        attr_accessor line_count: (Integer | untyped)
+      end
     end
 
     # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
@@ -2032,13 +2426,39 @@ module Tuile
     # Awaits until the event queue is empty (all events have been processed).
     def await_empty: () -> void
 
+    # Schedules `block` to fire on the event-loop thread roughly `fps` times
+    # per second, passing a 0-based monotonically increasing tick counter. Use
+    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
+    # periodic UI refresh from a background task.
+    # 
+    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
+    # stop it.
+    # 
+    # **Errors:** if `block` raises, the {Ticker} cancels itself and the
+    # exception flows through the normal event-loop error path — i.e.
+    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
+    # broken block from spamming `on_error` at the tick rate.
+    # 
+    # Tickers reuse `concurrent-ruby`'s shared timer thread
+    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
+    # threads, just more work on the shared scheduler.
+    # 
+    # _@param_ `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
+
     # 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.
+    # events; the block is always called from the thread running this function.
     # 
-    # Any exception raised by block is re-thrown, causing this function to
-    # terminate.
+    # Any exception raised by the block is re-thrown, causing this function to
+    # terminate. Wrap the block body in `rescue` if you want to handle errors
+    # without tearing down the loop — see {Screen#event_loop} for an example.
+    # 
+    # **Procs are yielded too.** A {#submit}ed block arrives as a `Proc` event;
+    # the consumer is responsible for invoking it (typically `event.call`).
+    # Yielding rather than dispatching inline means a raise inside the
+    # submitted block flows through the consumer's `rescue` like any other
+    # event-handler error, instead of bypassing it.
     def run_loop: () ?{ (Object event) -> void } -> void
 
     # _@return_ — true if this thread is running inside an event queue.
@@ -2109,6 +2529,36 @@ module Tuile
     class EmptyQueueEvent
       include Singleton
     end
+
+    # Handle returned by {EventQueue#tick}. Cancel a running ticker via
+    # {#cancel}.
+    # 
+    # Internally wraps a `Concurrent::TimerTask` whose firing posts a single
+    # submit-block to the owning {EventQueue}; the user's block therefore
+    # always runs on the event-loop thread and may freely mutate UI. If the
+    # user block raises, the Ticker auto-cancels and the exception is
+    # re-raised so it flows through the loop's normal error handling
+    # ({Screen#on_error} for the default Tuile setup).
+    class Ticker
+      # _@param_ `event_queue` — queue to dispatch tick calls onto.
+      # 
+      # _@param_ `fps` — firings per second (positive).
+      # 
+      # _@param_ `block` — called as `block.call(tick_count)` on each fire.
+      def initialize: (EventQueue event_queue, Numeric fps, Proc block) -> void
+
+      # _@return_ — true once {#cancel} has been called.
+      def cancelled?: () -> bool
+
+      # Stops the ticker. Idempotent and safe to call from any thread,
+      # including from inside the tick block. Any tick already queued on the
+      # event loop at the moment of cancellation is dropped before the user
+      # block runs.
+      def cancel: () -> void
+
+      # Runs on the event-loop thread.
+      def fire: () -> void
+    end
   end
 
   # Testing only — a screen which doesn't paint anything and pretends that the
@@ -2456,16 +2906,16 @@ module Tuile
     # `underline`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     # 
-    # _@param_ `bg` — background color, in any of the forms accepted by {Style.new}. `nil` clears bg back to the terminal default.
-    def with_bg: ((Symbol | Integer | ::Array[Integer])? bg) -> StyledString
+    # _@param_ `bg` — background color, coerced via {Color.coerce}. `nil` clears bg back to the terminal default.
+    def with_bg: ((Color | Symbol | Integer | ::Array[Integer])? bg) -> StyledString
 
     # Returns a new {StyledString} with `fg` applied to every span, preserving
     # each span's text and other style attributes (`bg`, `bold`, `italic`,
     # `underline`). The new fg overlays without dropping background colors or
     # text attributes the original styling carried.
     # 
-    # _@param_ `fg` — foreground color, in any of the forms accepted by {Style.new}. `nil` clears fg back to the terminal default.
-    def with_fg: ((Symbol | Integer | ::Array[Integer])? fg) -> StyledString
+    # _@param_ `fg` — foreground color, coerced via {Color.coerce}. `nil` clears fg back to the terminal default.
+    def with_fg: ((Color | Symbol | Integer | ::Array[Integer])? fg) -> StyledString
 
     def inspect: () -> String
 
@@ -2481,10 +2931,11 @@ module Tuile
 
     # _@param_ `color`
     # 
-    # _@param_ `base` — base SGR code — 30 for fg, 40 for bg.
+    # _@param_ `target` — `:fg` or `:bg`.
     # 
-    # _@param_ `ext` — extended-color SGR code — 38 for fg, 48 for bg.
-    def color_codes: ((Symbol | Integer | ::Array[Integer])? color, base: Integer, ext: Integer) -> ::Array[Integer]
+    # _@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`
     # 
@@ -2537,18 +2988,16 @@ module Tuile
     class ParseError < Tuile::Error
     end
 
-    # A frozen value type describing the visual style of a {Span}.
-    # 
-    # `fg` and `bg` accept:
-    # - `nil` — the terminal default (SGR 39 / 49)
-    # - a symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright ANSI colors
-    # - an Integer 0..255 — 256-color palette index (SGR 38;5;N / 48;5;N)
-    # - an `[r, g, b]` Array of three 0..255 Integers — 24-bit RGB
+    # A frozen value type describing the visual style of a {Span}. Colors are
+    # stored as {Color} instances (or `nil` for the terminal default); inputs
+    # to {.new} and {#merge} are coerced via {Color.coerce}, so the four
+    # accepted color forms — `nil`, Symbol, Integer 0..255, RGB Array — work
+    # transparently.
     # 
     # @!attribute [r] fg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bold
     #   @return [Boolean]
     # @!attribute [r] italic
@@ -2556,12 +3005,11 @@ module Tuile
     # @!attribute [r] underline
     #   @return [Boolean]
     class Style
-      COLOR_SYMBOLS: ::Array[Symbol]
       DEFAULT: Style
 
-      # _@param_ `fg`
+      # _@param_ `fg` — coerced via {Color.coerce}.
       # 
-      # _@param_ `bg`
+      # _@param_ `bg` — coerced via {Color.coerce}.
       # 
       # _@param_ `bold`
       # 
@@ -2569,18 +3017,13 @@ module Tuile
       # 
       # _@param_ `underline`
       def self.new: (
-                      ?fg: (Symbol | Integer | ::Array[Integer])?,
-                      ?bg: (Symbol | Integer | ::Array[Integer])?,
+                      ?fg: (Color | Symbol | Integer | ::Array[Integer])?,
+                      ?bg: (Color | Symbol | Integer | ::Array[Integer])?,
                       ?bold: bool,
                       ?italic: bool,
                       ?underline: bool
                     ) -> Style
 
-      # _@param_ `color`
-      # 
-      # _@param_ `which`
-      def self.validate_color!: (Object color, Symbol which) -> void
-
       def default?: () -> bool
 
       # Returns a new {Style} with the given attributes overridden.
@@ -2588,9 +3031,9 @@ module Tuile
       # _@param_ `overrides`
       def merge: (**::Hash[Symbol, Object] overrides) -> Style
 
-      attr_reader fg: (Symbol | Integer | ::Array[Integer])?
+      attr_reader fg: Color?
 
-      attr_reader bg: (Symbol | Integer | ::Array[Integer])?
+      attr_reader bg: Color?
 
       attr_reader bold: bool
 
@@ -2656,6 +3099,8 @@ module Tuile
   # 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 initialize: () -> void
+
     def locked?: () -> bool
 
     def stop: () -> void
@@ -2668,6 +3113,42 @@ module Tuile
 
     # _@param_ `event`
     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
+    # 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
+
+    # Test helper: fires every live ticker's user block once and prunes
+    # cancelled tickers. No-op when no tickers are registered. Pumps once
+    # per call regardless of any ticker's fps — the fake has no clock, so
+    # tests pump N frames by calling this N times.
+    def tick_once: () -> void
+
+    # Handle returned by {FakeEventQueue#tick}. Mirrors the public surface of
+    # {EventQueue::Ticker} (`cancel`, `cancelled?`) but does not auto-fire —
+    # the host {FakeEventQueue} drives firing via {FakeEventQueue#tick_once}.
+    class FakeTicker
+      # _@param_ `block` — called as `block.call(tick_count)` on each {#fire}.
+      def initialize: (Proc block) -> void
+
+      # _@return_ — true once {#cancel} has been called.
+      def cancelled?: () -> bool
+
+      # Marks the ticker cancelled. Idempotent. Subsequent {#fire} calls are
+      # no-ops; {FakeEventQueue#tick_once} also prunes the ticker on its next
+      # pass.
+      def cancel: () -> void
+
+      # Invokes the user block with the current tick counter, then advances.
+      # No-op when {#cancelled?}. Typically driven by
+      # {FakeEventQueue#tick_once}; safe to call directly from a test that
+      # wants to drive a single ticker.
+      def fire: () -> void
+    end
   end
 
   # A vertical scrollbar that computes which character to draw at each row.