tuile 0.5.0 → 0.7.0

data/lib/tuile/styled_string.rb

@@ -3,7 +3,7 @@
 module Tuile
   # An immutable string-with-styling, modeled as a sequence of {Span}s where
   # each span carries a complete {Style} (`fg`, `bg`, `bold`, `italic`,
-  # `underline`). Spans are non-overlapping and fully tile the string — every
+  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile the string — every
   # character has exactly one resolved style, no overlay layers to merge.
   #
   # Where this differs from threading SGR escapes through a plain `String`:
@@ -43,12 +43,21 @@ module Tuile
   #
   # ## Parser
   #
-  # {.parse} is strict by design: it recognizes only the SGR codes
+  # {.parse} is strict by default: it recognizes only the SGR codes
   # corresponding to {Style}'s supported attributes (fg/bg/bold/italic/
-  # underline). Anything else — unmodeled attributes (dim, blink, reverse,
-  # strike, conceal, double-underline, overline, ...), unknown SGR codes, or
+  # underline/strikethrough). Anything else — unmodeled attributes (dim, blink,
+  # reverse, conceal, double-underline, overline, ...), unknown SGR codes, or
   # non-SGR escapes (cursor moves, OSC) — raises {ParseError}. This keeps the
   # round-trip parse(to_ansi(x)) == x contract honest.
+  #
+  # Pass `lenient: true` to instead **discard** everything the parser can't
+  # model and keep going — recognized fg/bg/bold/italic/underline/strikethrough codes still
+  # apply, and any unmodeled SGR code, malformed extended color, non-SGR CSI
+  # (cursor moves, `\e[K`), OSC/DCS/string sequence, or stray escape is
+  # silently dropped. This is the mode for piping in colored output you don't
+  # control (e.g. `git --color` through a pager): "give me the colors, throw
+  # the rest away." It is lossy by design — `parse(x, lenient: true)` does not
+  # round-trip back to `x`.
   class StyledString
     # Raised by {.parse} on malformed or unsupported escape sequences.
     class ParseError < Error; end
@@ -69,16 +78,19 @@ module Tuile
     #   @return [Boolean]
     # @!attribute [r] underline
     #   @return [Boolean]
-    class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
+    # @!attribute [r] strikethrough
+    #   @return [Boolean]
+    class Style < Data.define(:fg, :bg, :bold, :italic, :underline, :strikethrough)
       # @param fg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bold [Boolean]
       # @param italic [Boolean]
       # @param underline [Boolean]
+      # @param strikethrough [Boolean]
       # @return [Style]
       # @raise [ArgumentError] when a color is not one of the accepted forms.
-      def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
-        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:)
+      def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false, strikethrough: false)
+        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:, strikethrough:)
       end
 
       # The style with no color and no attributes — what the terminal shows
@@ -117,8 +129,9 @@ module Tuile
     # @api private
     # Hand-rolled SGR parser. State machine over a {StringScanner}: plain
     # text accumulates into the current span; each `\e[...m` flushes the
-    # current span and updates the running {Style}. Anything outside the
-    # supported SGR alphabet raises {ParseError}.
+    # current span and updates the running {Style}. In strict mode anything
+    # outside the supported SGR alphabet raises {ParseError}; in lenient mode
+    # it is consumed and discarded (see {StyledString} "## Parser").
     class Parser
       # @return [Array<Symbol>]
       STANDARD_COLORS = Color::COLOR_SYMBOLS[0, 8].freeze
@@ -128,9 +141,20 @@ module Tuile
       BRIGHT_COLORS = Color::COLOR_SYMBOLS[8, 8].freeze
       private_constant :BRIGHT_COLORS
 
+      # ESC-introducers (the byte after `\e`) whose payload runs until a string
+      # terminator (ST `\e\\` or BEL): OSC `]`, DCS `P`, SOS `X`, PM `^`,
+      # APC `_`. In lenient mode the whole sequence — payload included — is
+      # swallowed so it never leaks into span text.
+      # @return [Array<String>]
+      STRING_INTRODUCERS = %w(] P X ^ _).freeze
+      private_constant :STRING_INTRODUCERS
+
       # @param input [String]
-      def initialize(input)
+      # @param lenient [Boolean] when true, discard unmodeled SGR codes and
+      #   non-SGR escapes instead of raising {ParseError}.
+      def initialize(input, lenient: false)
         @scanner = StringScanner.new(input)
+        @lenient = lenient
         @style = Style::DEFAULT
         @text = +""
         @spans = []
@@ -160,16 +184,70 @@ module Tuile
       # @return [void]
       def consume_escape
         @scanner.getch # \e
-        bracket = @scanner.getch
-        raise ParseError, "expected '[' after ESC, got #{bracket.inspect}" if bracket != "["
+        intro = @scanner.getch
+        case intro
+        when "[" then consume_csi
+        when nil then raise ParseError, "unterminated escape sequence" unless @lenient
+        else
+          raise ParseError, "expected '[' after ESC, got #{intro.inspect}" unless @lenient
+
+          consume_non_csi(intro)
+        end
+      end
 
-        params = @scanner.scan(/[\d;]*/) || ""
+      # Consumes a CSI sequence (`\e[` already eaten). A well-formed SGR
+      # (`\e[...m` with numeric/`;` params and no intermediates) is applied;
+      # anything else is a non-SGR or malformed CSI — raises in strict mode,
+      # swallowed in lenient. Scans the full CSI grammar (parameter bytes
+      # `\x30-\x3F`, intermediate bytes `\x20-\x2F`, final byte) so lenient
+      # mode consumes the whole sequence even for private-marker forms like
+      # `\e[?25l`.
+      # @return [void]
+      def consume_csi
+        params = @scanner.scan(/[\x30-\x3F]*/) || ""
+        intermediates = @scanner.scan(/[\x20-\x2F]*/) || ""
         final = @scanner.getch
-        raise ParseError, "unterminated escape sequence" if final.nil?
-        raise ParseError, "non-SGR CSI sequence (final byte #{final.inspect})" if final != "m"
 
+        if final == "m" && intermediates.empty? && params.match?(/\A[\d;]*\z/)
+          flush
+          return apply_sgr(params)
+        end
+
+        raise ParseError, "unterminated escape sequence" if final.nil? && !@lenient
+        raise ParseError, "non-SGR CSI sequence (final byte #{final.inspect})" unless @lenient
+
+        flush
+      end
+
+      # Lenient-only: discards a non-CSI escape (`\e` and `intro` already
+      # eaten). OSC/DCS/string sequences run to their string terminator; an
+      # nF escape (`\e( B`) eats its intermediates plus one final byte; any
+      # other Fe/Fp/Fs escape was complete in `intro` alone.
+      # @param intro [String] the byte after `\e` (never `"["`).
+      # @return [void]
+      def consume_non_csi(intro)
         flush
-        apply_sgr(params)
+        if STRING_INTRODUCERS.include?(intro)
+          consume_string_sequence
+        elsif intro.match?(/[\x20-\x2F]/)
+          @scanner.scan(/[\x20-\x2F]*/)
+          @scanner.getch
+        end
+      end
+
+      # Lenient-only: swallows an OSC/DCS/string-sequence payload up to and
+      # including its terminator (BEL, or ST `\e\\`), or to EOS if unterminated.
+      # @return [void]
+      def consume_string_sequence
+        until @scanner.eos?
+          ch = @scanner.getch
+          break if ch == "\a"
+
+          if ch == "\e"
+            @scanner.getch if @scanner.peek(1) == "\\"
+            break
+          end
+        end
       end
 
       # @param params_str [String]
@@ -187,6 +265,8 @@ module Tuile
           when 23 then @style = @style.merge(italic: false)
           when 4 then @style = @style.merge(underline: true)
           when 24 then @style = @style.merge(underline: false)
+          when 9 then @style = @style.merge(strikethrough: true)
+          when 29 then @style = @style.merge(strikethrough: false)
           when 30..37 then @style = @style.merge(fg: STANDARD_COLORS[code - 30])
           when 38
             i += consume_extended_color(codes, i, :fg)
@@ -199,7 +279,7 @@ module Tuile
           when 49 then @style = @style.merge(bg: nil)
           when 90..97 then @style = @style.merge(fg: BRIGHT_COLORS[code - 90])
           when 100..107 then @style = @style.merge(bg: BRIGHT_COLORS[code - 100])
-          else raise ParseError, "unsupported SGR code #{code}"
+          else raise ParseError, "unsupported SGR code #{code}" unless @lenient
           end
           i += 1
         end
@@ -208,27 +288,37 @@ module Tuile
       # @param codes [Array<Integer>]
       # @param index [Integer]
       # @param target [Symbol] either `:fg` or `:bg`.
-      # @return [Integer] how many SGR codes were consumed (3 for 256-color, 5 for RGB).
+      # @return [Integer] how many SGR codes were consumed. In lenient mode a
+      #   malformed color is skipped rather than applied, but the same count is
+      #   returned (3 for 256-color, 5 for RGB) so the running index advances
+      #   past its operands; an unknown selector skips just `38`/`48` + the
+      #   selector byte (2), letting the rest be reprocessed.
       def consume_extended_color(codes, index, target)
         mode = codes[index + 1]
         case mode
         when 5
           n = codes[index + 2]
-          raise ParseError, "invalid 256-color index #{n.inspect}" unless n&.between?(0, 255)
-
-          @style = @style.merge(target => n)
+          if n&.between?(0, 255)
+            @style = @style.merge(target => n)
+          elsif !@lenient
+            raise ParseError, "invalid 256-color index #{n.inspect}"
+          end
           3
         when 2
           r = codes[index + 2]
           g = codes[index + 3]
           b = codes[index + 4]
-          [r, g, b].each do |v|
-            raise ParseError, "invalid RGB component #{v.inspect}" unless v&.between?(0, 255)
+          if [r, g, b].all? { |v| v&.between?(0, 255) }
+            @style = @style.merge(target => [r, g, b])
+          elsif !@lenient
+            bad = [r, g, b].find { |v| !v&.between?(0, 255) }
+            raise ParseError, "invalid RGB component #{bad.inspect}"
           end
-          @style = @style.merge(target => [r, g, b])
           5
         else
-          raise ParseError, "unsupported extended-color selector #{mode.inspect}"
+          raise ParseError, "unsupported extended-color selector #{mode.inspect}" unless @lenient
+
+          2
         end
       end
 
@@ -268,10 +358,14 @@ module Tuile
       # default-styled span.
       #
       # @param input [String, StyledString, nil]
+      # @param lenient [Boolean] when true, unmodeled SGR codes and non-SGR
+      #   escapes are discarded instead of raising — see {StyledString}
+      #   "## Parser". Lossy: the result no longer round-trips to `input`.
       # @return [StyledString]
-      # @raise [ParseError] on unsupported or malformed escape sequences.
+      # @raise [ParseError] on unsupported or malformed escape sequences
+      #   (strict mode only).
       # @raise [TypeError] when `input` is none of String, StyledString, nil.
-      def parse(input)
+      def parse(input, lenient: false)
         case input
         when nil then EMPTY
         when StyledString then input
@@ -279,7 +373,7 @@ module Tuile
           return EMPTY if input.empty?
           return new([Span.new(text: input, style: Style::DEFAULT)]) unless input.include?("\e")
 
-          Parser.new(input).parse
+          Parser.new(input, lenient:).parse
         else
           raise TypeError, "cannot parse #{input.class}"
         end
@@ -456,7 +550,7 @@ module Tuile
 
     # Returns a new {StyledString} with `bg` applied to every span, preserving
     # each span's text and other style attributes (`fg`, `bold`, `italic`,
-    # `underline`). Useful for row-level highlights — the new bg overlays
+    # `underline`, `strikethrough`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     #
     # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background
@@ -469,7 +563,7 @@ module Tuile
 
     # 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
+    # `underline`, `strikethrough`). The new fg overlays without dropping background colors or
     # text attributes the original styling carried.
     #
     # @param fg [Color, Symbol, Integer, Array<Integer>, nil] foreground
@@ -528,6 +622,7 @@ module Tuile
       codes << (to.bold ? 1 : 22) if from.bold != to.bold
       codes << (to.italic ? 3 : 23) if from.italic != to.italic
       codes << (to.underline ? 4 : 24) if from.underline != to.underline
+      codes << (to.strikethrough ? 9 : 29) if from.strikethrough != to.strikethrough
       codes.concat(color_codes(to.fg, target: :fg)) if from.fg != to.fg
       codes.concat(color_codes(to.bg, target: :bg)) if from.bg != to.bg
       return "" if codes.empty?

data/lib/tuile/terminal_background.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Detects whether the terminal background is light or dark, so {Screen}
+  # can pick {Theme::LIGHT} or {Theme::DARK} automatically at startup.
+  #
+  # Two mechanisms, in order of reliability:
+  #
+  # 1. **OSC 11 query** — writes `ESC ] 11 ; ? BEL` to the terminal; modern
+  #    terminals (xterm, kitty, alacritty, wezterm, iTerm2, GNOME Terminal,
+  #    Windows Terminal) reply on stdin with the background color
+  #    (`\e]11;rgb:RRRR/GGGG/BBBB` + BEL or ST). The color's relative
+  #    luminance against a 0.5 threshold decides light vs dark. Terminals
+  #    that don't support the query simply never reply, so the read is
+  #    bounded by a short timeout.
+  # 2. **`COLORFGBG` env var** — rxvt/konsole export `"fg;bg"` ANSI palette
+  #    indices. Less reliable (stale across SSH/tmux, often unset); used
+  #    only when OSC 11 yields nothing.
+  #
+  # **Timing matters**: the OSC 11 reply arrives on stdin, so the query
+  # must complete before {EventQueue#start_key_thread} owns stdin —
+  # otherwise the reply bytes get consumed as garbage keystrokes. {Screen}
+  # calls {.detect} from its constructor, which apps run before
+  # {Screen#run_event_loop}; don't call this after the event loop started.
+  module TerminalBackground
+    # How long to wait for the OSC 11 reply. Generous for a local
+    # terminal; bounded so unsupporting terminals (which never reply)
+    # don't stall startup.
+    # @return [Float] seconds.
+    QUERY_TIMEOUT = 0.1
+
+    # The OSC 11 background-color query, BEL-terminated.
+    # @return [String]
+    QUERY = "\e]11;?\a"
+
+    # Matches the OSC 11 reply. Components are 1–4 hex digits each
+    # (terminals vary); `rgba:` (4 components) also matches — the alpha
+    # tail is ignored.
+    # @return [Regexp]
+    REPLY = %r{\e\]11;rgba?:(\h{1,4})/(\h{1,4})/(\h{1,4})}
+
+    # Enables mode 2031: the terminal pushes a color-scheme report
+    # (`\e[?997;1n` dark / `\e[?997;2n` light) whenever the OS appearance
+    # flips — see {EventQueue::ColorSchemeEvent}. Terminals without
+    # support ignore the sequence. Written by {Screen#run_event_loop}.
+    # @return [String]
+    NOTIFY_ON = "\e[?2031h"
+
+    # Disables mode 2031 again; written when the event loop exits.
+    # @return [String]
+    NOTIFY_OFF = "\e[?2031l"
+
+    class << self
+      # Detects the terminal background. Queries OSC 11 when both `input`
+      # and `output` are TTYs, falling back to `COLORFGBG`.
+      #
+      # @param input [IO] where the OSC 11 reply arrives (the TTY input).
+      # @param output [IO] where the query is written (the TTY output).
+      # @param env [Hash{String => String}] environment for the `COLORFGBG`
+      #   fallback; defaults to `ENV` (which duck-types the `[]` lookup).
+      # @param timeout [Numeric] max seconds to wait for the OSC 11 reply.
+      # @return [Symbol, nil] `:light`, `:dark`, or nil when undetectable.
+      def detect(input: $stdin, output: $stdout, env: ENV, timeout: QUERY_TIMEOUT)
+        osc = query_osc11(input, output, timeout) if input.tty? && output.tty?
+        osc || from_colorfgbg(env["COLORFGBG"])
+      end
+
+      private
+
+      # Writes the OSC 11 query and classifies the reply. The whole
+      # exchange runs with `input` in raw mode: the reply has no trailing
+      # newline, so a canonical-mode read would block past the timeout,
+      # and echo would smear the reply bytes onto the screen.
+      # @param input [IO]
+      # @param output [IO]
+      # @param timeout [Numeric]
+      # @return [Symbol, nil]
+      def query_osc11(input, output, timeout)
+        reply = input.raw do
+          output.write(QUERY)
+          output.flush
+          read_reply(input, timeout)
+        end
+        match = REPLY.match(reply)
+        match && classify(match.captures)
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      # Accumulates reply bytes until a BEL/ST terminator or the deadline.
+      # Terminals that don't support OSC 11 never reply — returning
+      # whatever arrived (usually nothing) lets the caller fail soft.
+      # @param input [IO]
+      # @param timeout [Numeric]
+      # @return [String]
+      def read_reply(input, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        buffer = +""
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return buffer if remaining <= 0 || IO.select([input], nil, nil, remaining).nil?
+
+          buffer << input.readpartial(256)
+          return buffer if buffer.include?("\a") || buffer.include?("\e\\")
+        end
+      rescue EOFError
+        buffer
+      end
+
+      # Relative luminance of the reported background, scaled per
+      # component hex width (xterm replies 4 digits per channel, others 2).
+      # @param components [Array<String>] three hex strings.
+      # @return [Symbol] `:light` or `:dark`.
+      def classify(components)
+        r, g, b = components.map { |c| c.to_i(16).fdiv((16**c.length) - 1) }
+        luminance = (0.2126 * r) + (0.7152 * g) + (0.0722 * b)
+        luminance > 0.5 ? :light : :dark
+      end
+
+      # `COLORFGBG` is `"fg;bg"` (rxvt sometimes `"fg;default;bg"`) with
+      # ANSI palette indices. White-ish backgrounds — 7 (white) and the
+      # bright range 9–15 — read as light; 0–6 and 8 as dark; anything
+      # else (missing, `"default"`, out of range) is inconclusive.
+      # @param value [String, nil]
+      # @return [Symbol, nil]
+      def from_colorfgbg(value)
+        bg = value&.split(";")&.last
+        return nil unless bg&.match?(/\A\d+\z/)
+
+        case bg.to_i
+        when 0..6, 8 then :dark
+        when 7, 9..15 then :light
+        end
+      end
+    end
+  end
+end

data/lib/tuile/theme.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A set of semantic colors the built-in components read when painting.
+  # The current theme lives at {Screen#theme}; components must look it up
+  # at paint time (inside `repaint`) rather than caching values, so that
+  # assigning {Screen#theme=} restyles everything via a single
+  # invalidate-everything pass.
+  #
+  # The primary API is the rendering helpers — {#active_bg},
+  # {#active_border}, {#input_bg}, {#hint} — which wrap a plain string in
+  # the token's SGR color (on the channel appropriate for the token's
+  # role) and reset:
+  #
+  #   screen.theme.active_bg("[ Ok ]")   # => "\e[48;5;59m[ Ok ]\e[0m"
+  #   screen.theme.hint("quit")          # => "\e[38;5;109mquit\e[0m"
+  #
+  # The helpers pass content through verbatim, so input may carry other
+  # escape sequences (e.g. {Component::Window} feeds its border string,
+  # cursor moves included). For span-aware styling — applying a token to a
+  # {StyledString} while preserving per-span colors — use the `*_color`
+  # readers instead (e.g. {Component::List} highlights its cursor row via
+  # `with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome text →
+  # helper; structured text → `*_color` reader + {StyledString}.
+  #
+  # Two built-in themes are provided: {DARK} (the default; the colors Tuile
+  # has always used) and {LIGHT} (counterparts legible on light terminal
+  # backgrounds). A custom theme is one `with` away:
+  #
+  #   screen.theme = Theme::DARK.with(active_border_color: Color::CYAN)
+  #
+  # Tokens deliberately cover only the *accents* Tuile paints. Everything
+  # else inherits the terminal's own default foreground/background, which
+  # already matches the user's terminal theme perfectly — that's why there
+  # is no global `bg`/`fg` token.
+  #
+  # Every token is a {Color} — and must be passed as one. Unlike the
+  # lenient {Color.coerce} call sites elsewhere in the framework, a theme
+  # is declared once per app, so it takes only {Color} instances: at a
+  # declaration site `Color.palette(130)` documents itself in a way the
+  # bare `130` does not (palette index? RGB channel?) — and the named
+  # palette constants (`Color::DARK_ORANGE3` *is* 130; see
+  # {Color::PALETTE_NAMES}) go one step further.
+  #
+  # ## App-specific tokens
+  #
+  # Beyond the built-in tokens, an app can carry its own colors in
+  # {#custom} — a frozen `Hash{Symbol => Color}` member. Look them up with
+  # {#[]} (fail-fast: a typo raises `KeyError`) and render with the
+  # generic {#fg} / {#bg} helpers:
+  #
+  #   theme = Theme::DARK.with(custom: { accent: Color::DARK_ORANGE })
+  #   theme[:accent]              # => Color, e.g. for StyledString#with_fg
+  #   theme.fg(:accent, "NEW")    # => "\e[38;5;208mNEW\e[0m"
+  #
+  # Apps wanting semantic readers can subclass — `Data#with` preserves the
+  # subclass, so an `AppTheme` stays an `AppTheme` through `with`:
+  #
+  #   class AppTheme < Tuile::Theme
+  #     def accent(text) = fg(:accent, text)
+  #   end
+  #
+  # Pair the dark and light variants in a {ThemeDef} and hand it to
+  # {Screen#theme_def=} so OS appearance flips pick the right one.
+  #
+  # @!attribute [r] active_bg_color
+  #   Background highlight of the component the user is interacting with:
+  #   the {Component::List} cursor row, the focused {Component::TextField} /
+  #   {Component::TextArea} well, the focused {Component::Button}. "Active"
+  #   matches the {Component#active?} focus-chain flag — this is the
+  #   focus/selection highlight in conventional UI terms.
+  #   @return [Color]
+  # @!attribute [r] active_border_color
+  #   Foreground of a {Component::Window} border when the window is on the
+  #   active (focus) chain.
+  #   @return [Color]
+  # @!attribute [r] input_bg_color
+  #   Resting background "well" of {Component::TextField} /
+  #   {Component::TextArea} when *not* active — visibly a field, but
+  #   distinctly subtler than {#active_bg_color}.
+  #   @return [Color]
+  # @!attribute [r] hint_color
+  #   Foreground of keyboard-shortcut captions in status-bar hints (the
+  #   "quit" in "q quit") — see {#hint}.
+  #   @return [Color]
+  # @!attribute [r] custom
+  #   App-specific color tokens; empty in the built-in themes. Frozen —
+  #   build a changed theme via `with(custom: ...)`. Prefer {#[]} for
+  #   lookups (it fail-fasts on typos); read this directly to enumerate
+  #   the tokens.
+  #   @return [Hash{Symbol => Color}]
+  class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color, :hint_color, :custom)
+    # @param active_bg_color [Color]
+    # @param active_border_color [Color]
+    # @param input_bg_color [Color]
+    # @param hint_color [Color]
+    # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
+    # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
+    #   `Hash{Symbol => Color}`.
+    def initialize(active_bg_color:, active_border_color:, input_bg_color:, hint_color:, custom: {})
+      { active_bg_color:, active_border_color:, input_bg_color:, hint_color: }.each do |name, value|
+        raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
+      end
+      raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)
+
+      custom.each do |key, value|
+        raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
+        raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
+      end
+      super(active_bg_color:, active_border_color:, input_bg_color:, hint_color:, custom: custom.dup.freeze)
+    end
+
+    # Looks up an app-specific token from {#custom}.
+    # @param token [Symbol]
+    # @return [Color]
+    # @raise [KeyError] when the token is not present — a typo should fail
+    #   loudly, not paint in a default.
+    def [](token) = custom.fetch(token)
+
+    # Renders `text` in the foreground color of the app-specific `token`
+    # — the generic counterpart of {#hint} for {#custom} tokens.
+    # @param token [Symbol]
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    # @raise [KeyError] when the token is not present.
+    def fg(token, text) = wrap(text, self[token], :fg)
+
+    # Renders `text` on the background color of the app-specific `token`
+    # — the generic counterpart of {#active_bg} for {#custom} tokens.
+    # @param token [Symbol]
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    # @raise [KeyError] when the token is not present.
+    def bg(token, text) = wrap(text, self[token], :bg)
+
+    # Renders `text` on the {#active_bg_color} background.
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def active_bg(text) = wrap(text, active_bg_color, :bg)
+
+    # Renders `text` in the {#active_border_color} foreground. Content
+    # passes through verbatim, so it may embed non-SGR escapes (cursor
+    # moves in a border string).
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def active_border(text) = wrap(text, active_border_color, :fg)
+
+    # Renders `text` on the {#input_bg_color} background.
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def input_bg(text) = wrap(text, input_bg_color, :bg)
+
+    # Renders `text` in the {#hint_color} foreground, for status-bar hints,
+    # e.g. `"q #{screen.theme.hint("quit")}"`. The color is baked into the
+    # returned String, so strings built this way do *not* restyle when the
+    # theme changes — rebuild them instead (the framework's own call sites
+    # rebuild on every status-bar refresh).
+    # @param text [String]
+    # @return [String] ANSI-rendered text, ending with an SGR reset.
+    def hint(text) = wrap(text, hint_color, :fg)
+
+    # The colors Tuile used before themes existed, tuned for dark terminal
+    # backgrounds. GREY37 (palette 59) is what Rainbow emits for
+    # `:darkslategray`, LIGHT_SKY_BLUE3 (109) for `:cadetblue`; GREY27
+    # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
+    # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
+    # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
+    # darker than the active highlight at 59 (~#5f5f5f).
+    # @return [Theme]
+    DARK = new(active_bg_color: Color::GREY37,
+               active_border_color: Color::GREEN,
+               input_bg_color: Color::GREY27,
+               hint_color: Color::LIGHT_SKY_BLUE3)
+
+    # Counterparts legible on light terminal backgrounds: grayscale-ramp
+    # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
+    # ~#dadada — dark enough to read as a "well" against white, one step
+    # lighter than the active highlight) and a dark teal (TURQUOISE4 = 30,
+    # ~#008787) keeping the hint hue. `active_border_color` stays the
+    # named green — named ANSI colors are remapped by the terminal's own
+    # palette, so the theme picks a light-appropriate green for us.
+    # @return [Theme]
+    LIGHT = new(active_bg_color: Color::GREY82,
+                active_border_color: Color::GREEN,
+                input_bg_color: Color::GREY85,
+                hint_color: Color::TURQUOISE4)
+
+    private
+
+    # The single sanctioned place for verbatim SGR wrapping: `text` is not
+    # parsed or validated, so callers may embed non-SGR escapes. Emits the
+    # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
+    # text.
+    # @param text [String]
+    # @param color [Color]
+    # @param target [Symbol] `:fg` or `:bg`.
+    # @return [String]
+    def wrap(text, color, target)
+      "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
+    end
+  end
+end