tuile 0.12.0 → 0.14.0

data/ideas/arrow-key-navigation.md

@@ -104,6 +104,12 @@ Recorded here so the open questions below stay narrow.
   stop. See open question on backwards entry.
 - **Mouse is untouched.** Popups are untouched — the bubble is already scoped
   to the topmost modal popup.
+- **{Tuile::Component::Tabs} already left the vertical axis free for this.**
+  The strip claims Left/Right and *declines* Up/Down specifically so that this
+  feature can move focus out of it vertically while Left/Right keep switching
+  tabs inside it (`D_tabs`). It composes for nothing: the strip declines, the
+  key bubbles, the navigating ancestor moves. That is also the shape to copy
+  for any future one-axis widget — claim one axis, leave the other.
 
 ## The honest argument against
 
@@ -180,6 +186,16 @@ exactly virtui's shape, so the answer matters more there than in a form.
 (`combo_box.rb:181`) but declines Up. So Up would jump out of a closed combo
 while Down opens it. Browsers eat both. Deliberate choice or accident to fix?
 
+**Q12 — Down out of a `Tabs` strip: to the pane, or past the whole
+`TabSheet`?** The strip is a child of the sheet, not of the navigating layout,
+so "walk direct children" sees the *sheet* holding focus and would move to the
+sheet's next sibling — skipping the pane the user is looking at. Entering the
+pane is almost certainly what a user means by Down here. Options: let a
+`TabSheet` claim Down when focus is on its strip (a `handle_key` on the sheet,
+no framework change, but a second place that binds an arrow); or have the
+navigating walk descend into a child that holds focus deeper than its first
+tab stop. Interacts with Q1's placement question.
+
 **Q9 — Naming.** "Form" is the wrong word for the behavior — it's *focus
 navigation*. `navigation` / `arrow_nav` / `key_navigation` /
 `focus_navigation`? Whatever it is, it must not imply validation or submit,
@@ -199,7 +215,7 @@ Also: any public signature change means `rake sig` in the same commit.
 
 If built: the user-facing half goes to book ch5 (the key/Enter tables live
 there), the invariants half to AGENTS.md's key-dispatch section, and the
-choice-plus-rejected-roads half to `DECISIONS.md` as `D-arrow-navigation` —
+choice-plus-rejected-roads half to `DECISIONS.md` as `D_arrow_navigation` —
 which must record the `Layout::Form` rejection and the Vaadin FormGroup
 precedent behind it, since that's the reasoning most likely to be
 re-litigated. Then retire this file.

data/ideas/modal-backdrop.md

@@ -0,0 +1,24 @@
+# Modal backdrop — dim the content under a popup, or cast a shadow
+
+**Status:** seed, 2026-08-31. Deliberately not brainstormed yet; spun off from
+the `ConfirmWindow` design (`D_confirm_window`'s sizing paragraph).
+
+**The problem.** A modal `Popup` floats over the tiled content with no visual
+separation beyond its own border: the content underneath is neither dimmed nor
+shadowed. A small popup — a `ConfirmWindow` measuring a one-line "Overwrite?" —
+can sit in the middle of a busy screen and simply not be noticed.
+
+**The two candidate treatments** (every GUI stack ships at least one):
+
+- **Dim/tint** the non-popup cells under the topmost modal.
+- **A drop shadow** — a one-cell dark offset under/right of the popup box.
+
+**Hooks that exist today, for whoever picks this up:** `Screen#repaint`
+already partitions tiled vs. popup subtrees and repaints popups on top, so a
+dim pass has a natural slot between the two. Terminal cells are opaque
+(`D_bg_inherit`), so "dim" means restyling cells, not compositing — and
+`Color` has no darken/blend operation yet, which a dim factor would need.
+
+**Open when picked up:** flush-time transform in `Buffer` vs. repaint-time
+style override in components; does a shadow belong to `Overlay` or only
+`Popup`; interaction with themes and with the terminal-default (unset) bg.

data/ideas/new-components.md

@@ -9,14 +9,14 @@ and it belongs here, not in a durable doc, because it goes stale as we
 build.
 
 Batch 1 ("field components only") is **done** — every idea filed under it has
-graduated: `checkbox` (`DECISIONS.md` `D-boolean-fields`) and `checkbox-group`
-(`D-checkbox-group`), both built 2026-07-30; `radio-group` (`D-radio-group`),
-built 2026-07-31; `progress-bar` (`D-color-slots`, book ch7 "Reporting
-progress") and `password-field` (`D-integer-field`'s taxonomy, book ch7
+graduated: `checkbox` (`DECISIONS.md` `D_boolean_fields`) and `checkbox-group`
+(`D_checkbox_group`), both built 2026-07-30; `radio-group` (`D_radio_group`),
+built 2026-07-31; `progress-bar` (`D_color_slots`, book ch7 "Reporting
+progress") and `password-field` (`D_integer_field`'s taxonomy, book ch7
 "Editing text"), both built 2026-08-02.
 
 The **box layouts** that headed the gating list below are done too
-(`D-box-layouts`, 2026-08-07) — `Layout::Vertical` / `::Horizontal`, plus the
+(`D_box_layouts`, 2026-08-07) — `Layout::Vertical` / `::Horizontal`, plus the
 sampler ported onto them.
 
 ## What Tuile already has
@@ -26,7 +26,7 @@ Integer Field, Combo Box (1:1), Dialog ({Tuile::Component::Popup} plus
 `Window`/`InfoWindow`/`PickerWindow`), Themable Mixin
 ({Tuile::Theme}/{Tuile::ThemeDef}). **List Box** is half-there:
 {Tuile::Component::List} takes typed items and a renderer since 2026-08-14
-(`D-list-items`), but has no multi-select — {Tuile::Component::CheckboxGroup}
+(`D_list_items`), but has no multi-select — {Tuile::Component::CheckboxGroup}
 is the nearest thing.
 
 Tuile also has pieces Vaadin doesn't name as components — `ListDropdown`,
@@ -39,21 +39,20 @@ That leaves ~46 gaps.
 
 | Component | Builds on | Note |
 |---|---|---|
-| ~~Box layouts (H/V)~~ | `Layout` | **built** 2026-08-07 (`D-box-layouts`, book ch3); `Vertical`/`Horizontal` over `Box`, additive sugar on top of `Absolute` — no foundation change |
-| ~~Checkbox~~ | `HasValue` | **built** 2026-07-30 (`D-boolean-fields`); tri-state still deferred |
-| ~~Radio Group~~ | `List` + `HasValue` | **built** 2026-07-31 (`D-radio-group`); composes a `List`, cursor roams and Space selects |
-| ~~Checkbox Group~~ | `List` + `HasValue` | **built** 2026-07-30 (`D-checkbox-group`); composes a `List`, frozen `Set` value |
-| ~~Select~~ | `ListDropdown` + `HasValue` | **built** 2026-08-12 (`D-select`, book ch7); a *second driver* of `ListDropdown`, not "ComboBox − filter" — it paints its own one-row face and needs no read-only axis. Claims no printable but Space |
-| ~~Password Field~~ | `TextField` | **built** 2026-08-02 (`D-integer-field`'s taxonomy — subclass, since a password's value *is* its text; mask default in `D-ambiguous-width`); a `display_text` seam, one mask glyph per character |
-| ~~Number Field~~ | `IntegerField` twin | **built** 2026-08-07 as `FloatField` (`D-float-field`) and `BigDecimalField` (`D-bigdecimal-field`, on Tuile's first optional dep); each named for its Ruby value type, deliberate copies of `IntegerField` |
-| ~~Progress Bar~~ | `draw_line` + `EventQueue#tick_fps` | **built** 2026-08-02 (`D-progress-bar`, book ch7); a `value` that stays out of `HasValue`, ticker synced from `attached? && indeterminate?` |
-| ~~Notification~~ | `Popup` + `Ticker` | **built** 2026-08-17 (`D-notification`, book ch7); one non-modal top-right box, N messages, one 3 s ticker retiring the oldest. Corner anchor is its own `reposition` override, so `Popup` was untouched — and the `Popover` extraction still waits for a second *kind* of anchoring |
-| Confirm Dialog | `Popup`+`Window`+`Button` | fold `PickerWindow` in |
+| ~~Box layouts (H/V)~~ | `Layout` | **built** 2026-08-07 (`D_box_layouts`, book ch3); `Vertical`/`Horizontal` over `Box`, additive sugar on top of `Absolute` — no foundation change |
+| ~~Checkbox~~ | `HasValue` | **built** 2026-07-30 (`D_boolean_fields`); tri-state still deferred |
+| ~~Radio Group~~ | `List` + `HasValue` | **built** 2026-07-31 (`D_radio_group`); composes a `List`, cursor roams and Space selects |
+| ~~Checkbox Group~~ | `List` + `HasValue` | **built** 2026-07-30 (`D_checkbox_group`); composes a `List`, frozen `Set` value |
+| ~~Select~~ | `ListDropdown` + `HasValue` | **built** 2026-08-12 (`D_select`, book ch7); a *second driver* of `ListDropdown`, not "ComboBox − filter" — it paints its own one-row face and needs no read-only axis. Claims no printable but Space |
+| ~~Password Field~~ | `TextField` | **built** 2026-08-02 (`D_integer_field`'s taxonomy — subclass, since a password's value *is* its text; mask default in `D_ambiguous_width`); a `display_text` seam, one mask glyph per character |
+| ~~Number Field~~ | `IntegerField` twin | **built** 2026-08-07 as `FloatField` (`D_float_field`) and `BigDecimalField` (`D_bigdecimal_field`, on Tuile's first optional dep); each named for its Ruby value type, deliberate copies of `IntegerField` |
+| ~~Progress Bar~~ | `draw_line` + `EventQueue#tick_fps` | **built** 2026-08-02 (`D_progress_bar`, book ch7); a `value` that stays out of `HasValue`, ticker synced from `attached? && indeterminate?` |
+| ~~Notification~~ | `Popup` + `Ticker` | **built** 2026-08-17 (`D_notification`, book ch7); one non-modal top-right box, N messages, one 3 s ticker retiring the oldest. Corner anchor is its own `reposition` override, so `Popup` was untouched — and the `Popover` extraction still waits for a second *kind* of anchoring |
+| ~~Confirm Dialog~~ | `Popup`+`Window`+`Button` | **built** 2026-08-31 as `ConfirmWindow` (`D_confirm_window`, book ch7); the component is the builder — `#button` plus the `alert`/`confirm`/`yes_no` factories — every button dismisses, MenuBar-shaped mnemonics with `q`/`g`/`G` reserved. The fold-`PickerWindow`-in idea is **rejected**: the two disagree on every semantic that matters (cursor, default, ESC, close-on-pick) and share only API shape |
 | Details → Accordion | `HasContent` | Details is the atom, Accordion the group |
-| Tabs → Tabsheet | `HasValue` (index) + `HasContent` | strip, then strip + content swap |
-| Popover | `ListDropdown#anchor_to` (extracted 2026-08-12) | generalize the anchored non-modal overlay: `anchor_to` moves down to it and `ListDropdown` inherits it. Build it when the second *kind* of anchoring appears (a point; a right edge that flips) — not the second caller of the same kind. Gates the next two |
-| Menu Bar | `ListDropdown::Menu` + Popover | |
-| Context Menu | same | `:right` button already parses |
+| ~~Tabs → TabSheet~~ | plain `Component` + the tree API | **built** 2026-08-23 (`D_tabs`, book ch7); a strip (one tab stop, Left/Right, immediate activation) plus a sheet whose `children` are `[strip, pane]`. Neither is `HasValue` — a tab selection is view state — and neither is `HasContent`; hiding a pane means *detaching* it, since Tuile has no visibility flag; the strip owns mutable `Tabs::Tab` handles rather than the `items`/`item_label` shell. Hidden/disabled/closeable tabs, lazy panes and a scrolling strip are deferred, each additive (`D_tabs`) |
+| Popover | `ListDropdown#anchor_to` (extracted 2026-08-12) | generalize the anchored non-modal overlay: `anchor_to` moves down to it and `ListDropdown` inherits it. Build it when the second *kind* of anchoring appears (a point; a right edge that flips) — not the second caller of the same kind. Nothing gates on it today: Menu Bar shipped without it |
+| ~~Menu Bar~~ | `ListDropdown` (+ `anchor_beside`) | **built** 2026-08-24 (`D_menu_bar`, book ch7), mnemonics the same day. Turned out *not* to need the Popover extraction: a focused strip drives a cascade of non-modal `ListDropdown`s the way `Select` drives one, so the additions were a side-anchor method, a highlighted-row rect and a cursor pass-through. Unlimited submenu depth; checkable/disabled items and global-shortcut activation deferred indefinitely |
 | Slider | `draw_line` | arrows/PgUp; 25.2 also has a two-thumb *range* variant |
 | Breadcrumbs | `Label`/`StyledString` | clickable path segments |
 | Markdown | `TextView` + `StyledString` | Markdown subset → styled text; high value on a TTY |
@@ -71,7 +70,7 @@ That leaves ~46 gaps.
 | Virtual List | a lazy data-provider strategy on `List` |
 | Side Nav | hierarchical collapsible list (the sampler's nav is the prototype) |
 | App Layout | shell: title bar + drawer + content slot |
-| Custom Field | formalize the composed typed-field pattern — or *reject* it as a shared base (COP: inherit to *be*, not to share); `D-integer-field` already sketches the taxonomy |
+| Custom Field | formalize the composed typed-field pattern — or *reject* it as a shared base (COP: inherit to *be*, not to share); `D_integer_field` already sketches the taxonomy |
 | Message Input / Message List / Login | nothing — pure assemblies, good example fodder |
 | Upload | reinterpret as a file-chooser dialog (`file_commander` has the ingredients) |
 | Icon | a glyph / Nerd-Font constants module |
@@ -92,7 +91,7 @@ That leaves ~46 gaps.
 These are prerequisites, not components, and each deserves its own idea
 file when its cluster comes up:
 
-1. ~~**Box layouts** (H/V)~~ — **done** 2026-08-07 (`D-box-layouts`). Turned
+1. ~~**Box layouts** (H/V)~~ — **done** 2026-08-07 (`D_box_layouts`). Turned
    out *not* to be structural: a `Box` is an `Absolute` subclass with a `rect=`
    override, so it unblocked the form-shaped cluster without touching the
    foundation. A future Grid should reuse its `Fixed`/`Percent`/`Expand`
@@ -100,24 +99,26 @@ file when its cluster comes up:
 2. **Field label + helper text seam** → Form Layout. Note this is what Form
    Layout is actually blocked on — the layout half now exists.
 3. **Validation seam** → Email Field, forms generally.
-4. **Anchored Popover extraction** → Menu Bar, Context Menu, pickers,
-   Tooltip.
+4. **Anchored Popover extraction** → pickers, Tooltip. **No longer gates Menu
+   Bar** — `D_menu_bar` argues the side-anchor is a sibling method on
+   `ListDropdown`, since both callers still wrap a `List`; the extraction's
+   trigger is now the first non-`List` content that wants anchoring.
 5. **Mouse motion/drag** (modes 1002/1006, release events) → Split
    divider, Slider drag, scrollbar drag.
 6. **Typed items + data provider on `List`** → List Box, Grid, Virtual
-   List. **Half done** 2026-08-14 (`D-list-items`): `List` takes `items` +
+   List. **Half done** 2026-08-14 (`D_list_items`): `List` takes `items` +
    a `renderer` and renders only the visible rows, and the five composers
    are folded onto it. The remaining half is *sourcing* items lazily (a
    data provider behind `items`), which lazy rendering was chosen to keep
    reachable without a redesign.
 
 Vaadin's `Binder` is the natural companion for the forms cluster but is
-not a component; `D-has-value` already parks the forms-layer questions
+not a component; `D_has_value` already parks the forms-layer questions
 (converters, read-only, required indicator).
 
 ## ~~Cross-cutting open question: component color slots vs. theme tokens~~
 
-**Settled 2026-08-01 as `DECISIONS.md` `D-color-slots`** — the slot, defaulting
+**Settled 2026-08-01 as `DECISIONS.md` `D_color_slots`** — the slot, defaulting
 to `nil`. Slider and Badge are bound by it when they land; Badge's promotion
 trigger (a *second* built-in needing the same semantic color) is written up
 there, so neither has to re-argue it.

data/lib/tuile/ansi.rb

@@ -12,6 +12,16 @@ module Tuile
     # @return [String]
     RESET = "\e[0m"
 
+    # The bell (`BEL`, `\a`, 0x07) — the "that keystroke went nowhere" signal.
+    # Ring it with {Screen#beep} rather than printing it: the bell is terminal
+    # IO, which is {Screen}'s job.
+    #
+    # What the user gets is the *terminal's* business — an audible beep, a
+    # visual flash, or nothing at all — and Tuile keeps no preference of its
+    # own about that.
+    # @return [String]
+    BEL = "\a"
+
     # Begin Synchronized Update (DEC private mode 2026, "Synchronized
     # Output"). The terminal stops refreshing its display and buffers every
     # subsequent write until {SYNC_END}, then composites the whole batch

data/lib/tuile/buffer.rb

@@ -116,7 +116,16 @@ module Tuile
     def self.display_width(grapheme) = WIDTH_CACHE[grapheme]
 
     # @param size [Size] grid dimensions in columns × rows.
-    def initialize(size)
+    # @param color_depth [Symbol] what the terminal can show — one of
+    #   {ColorDepth::DEPTHS}; {#flush} degrades every emitted color to it.
+    #   Validated here rather than at paint time: a bad value would otherwise
+    #   surface as an exception mid-frame, far from the mistake.
+    # @raise [ArgumentError] when `color_depth` is not a known depth.
+    def initialize(size, color_depth: :truecolor)
+      raise ArgumentError, "invalid color depth: #{color_depth.inspect}" unless
+        ColorDepth::DEPTHS.include?(color_depth)
+
+      @color_depth = color_depth
       allocate_grid(size)
       # A fresh buffer never matches the terminal yet — the screen holds
       # whatever was there at startup — so it begins fully dirty and the first
@@ -130,6 +139,12 @@ module Tuile
     # @return [Integer]
     attr_reader :width, :height
 
+    # What the terminal can show ({ColorDepth::DEPTHS}). Cells hold whatever
+    # color a component painted — {#region_ansi} and friends report that,
+    # unchanged — and only {#flush} degrades it on the way to the wire.
+    # @return [Symbol]
+    attr_reader :color_depth
+
     # @param x [Integer] column.
     # @param y [Integer] row.
     # @return [Cell, nil] the live cell at `(x, y)` (do not mutate — paint via
@@ -395,8 +410,9 @@ module Tuile
               out << TTY::Cursor.move_to(x, y)
               run_open = true
             end
-            out << style.sgr_to(c.style) << c.grapheme
-            style = c.style
+            shown = quantized_style(c.style)
+            out << style.sgr_to(shown) << c.grapheme
+            style = shown
           end
         else
           run_open = false
@@ -406,6 +422,38 @@ module Tuile
       style
     end
 
+    # `style` as {#color_depth} can actually show it, each color through
+    # {Color#quantize}. Applied *before* the {StyledString::Style#sgr_to}
+    # diff, so two RGBs that quantize onto the same cell emit nothing at all
+    # rather than a redundant SGR.
+    #
+    # The one-slot memo is load-bearing, not a micro-optimization: this runs
+    # per dirty *cell*, while a painted run shares one frozen
+    # {StyledString::Style} instance, so remembering just the last answer
+    # collapses the work onto actual style transitions. Without it a
+    # full-screen repaint of RGB-styled content measured 51 ms against 15 ms
+    # at `:truecolor` — a keyed cache is still the wrong answer
+    # (`D_color_depth`), but paying the arithmetic 8000 times for one span
+    # was too.
+    #
+    # @param style [StyledString::Style]
+    # @return [StyledString::Style] `style` itself whenever nothing needed
+    #   degrading — {Color#quantize}'s identity contract, extended.
+    def quantized_style(style)
+      return style if @color_depth == :truecolor
+      return @quantized_style if style.equal?(@quantized_source)
+
+      fg = style.fg&.quantize(@color_depth)
+      bg = style.bg&.quantize(@color_depth)
+      @quantized_source = style
+      @quantized_style =
+        if fg.equal?(style.fg) && bg.equal?(style.bg)
+          style
+        else
+          style.merge(fg: fg, bg: bg)
+        end
+    end
+
     # @param rect [Rect]
     # @return [Array<Array<Cell>>] cells within `rect`, row-major, clamped to
     #   the grid (out-of-bounds positions yield a blank cell).

data/lib/tuile/color.rb

@@ -144,6 +144,47 @@ module Tuile
       end
     end
 
+    # This color as the nearest one `depth` can actually show — the
+    # degradation {Buffer#flush} applies to every color on its way to the wire:
+    #
+    #   Color.rgb(100, 100, 100).quantize(:palette256)  # => Color.palette(241)
+    #   Color.rgb(255, 0, 0).quantize(:ansi16)          # => Color::BRIGHT_RED
+    #   Color.rgb(255, 0, 0).quantize(:truecolor)       # => itself, unchanged
+    #
+    # Returns **the same instance** whenever `depth` shows this color as-is —
+    # every named color at every depth, a palette index anywhere but
+    # `:ansi16`, RGB at `:truecolor` — so `color.quantize(depth).equal?(color)`
+    # *is* the "needs no translating" predicate, and the common path
+    # allocates nothing.
+    #
+    # == Implementation details
+    #
+    # RGB picks whichever is nearer in squared-RGB distance: the 6×6×6 cube
+    # (16..231, its per-channel nearest levels being the nearest cell outright
+    # — the axes are independent) or the 24-step grey ramp (232..255, whose
+    # nearest step is the one nearest the channel mean).
+    #
+    # Under `:ansi16` a color goes *direct* to the nearest of the 16, never
+    # via the 256-palette — two steps would compound the rounding — and the
+    # result is a *named* color, which keeps respecting the user's terminal
+    # scheme. Matching is against xterm's default RGBs for the 16, which that
+    # scheme may itself redefine: the one mapping here that can be honestly
+    # wrong.
+    #
+    # @param depth [Symbol] one of {ColorDepth::DEPTHS}.
+    # @return [Color]
+    # @raise [ArgumentError] when `depth` is not a known depth.
+    def quantize(depth)
+      case depth
+      when :truecolor then self
+      when :palette256
+        @value.is_a?(Array) ? PALETTE_COLORS[nearest_palette(@value)] : self
+      when :ansi16
+        @value.is_a?(Symbol) ? self : ANSI16_COLORS[nearest_ansi16(rgb_triple)]
+      else raise ArgumentError, "invalid color depth: #{depth.inspect}"
+      end
+    end
+
     # 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.
@@ -171,10 +212,112 @@ module Tuile
       "#<#{self.class.name} #{@value.inspect}>"
     end
 
+    private
+
+    # This color's RGB — the palette cell's own coordinates when the value is
+    # an index. Only ever asked of a non-Symbol value; a named color has no
+    # RGB of its own, since the terminal's scheme decides what it looks like.
+    # @return [Array<Integer>] red, green and blue, each 0..255.
+    def rgb_triple
+      return @value if @value.is_a?(Array)
+      return ANSI16_RGB[@value] if @value < 16
+      return [8 + (10 * (@value - 232))] * 3 if @value >= 232
+
+      cube = @value - 16
+      [CUBE_LEVELS[cube / 36], CUBE_LEVELS[(cube / 6) % 6], CUBE_LEVELS[cube % 6]]
+    end
+
+    # Written flat — destructured rather than splatted, `x * x` rather than
+    # `x**2`, no distance helper — because it runs per style transition in
+    # {Buffer#flush}, and the tidy shape measures ~2x slower (see
+    # `benchmark/quantize.rb`).
+    #
+    # @param rgb [Array<Integer>] red, green and blue, each 0..255.
+    # @return [Integer] palette index, 16..255 — the nearer of this color's
+    #   cube cell and its grey-ramp step. A tie goes to the cube, which spans
+    #   the whole space where the ramp only covers the diagonal.
+    def nearest_palette(rgb)
+      red, green, blue = rgb
+      ri = CUBE_INDEX[red]
+      gi = CUBE_INDEX[green]
+      bi = CUBE_INDEX[blue]
+      dr = CUBE_LEVELS[ri] - red
+      dg = CUBE_LEVELS[gi] - green
+      db = CUBE_LEVELS[bi] - blue
+      cube = (dr * dr) + (dg * dg) + (db * db)
+      # The grey minimizing the distance sits at the channel mean, so the best
+      # ramp step is the one nearest it; floor division rounds it half-up.
+      step = ((((red + green + blue) / 3) - 3) / 10).clamp(0, 23)
+      level = 8 + (10 * step)
+      gr = level - red
+      gg = level - green
+      gb = level - blue
+      grey = (gr * gr) + (gg * gg) + (gb * gb)
+      cube <= grey ? 16 + (36 * ri) + (6 * gi) + bi : 232 + step
+    end
+
+    # @param rgb [Array<Integer>] red, green and blue, each 0..255.
+    # @return [Integer] index into {COLOR_SYMBOLS} of the nearest of the 16.
+    def nearest_ansi16(rgb)
+      red, green, blue = rgb
+      best = 0
+      best_distance = nil
+      index = 0
+      while index < 16
+        candidate = ANSI16_RGB[index]
+        dr = candidate[0] - red
+        dg = candidate[1] - green
+        db = candidate[2] - blue
+        distance = (dr * dr) + (dg * dg) + (db * db)
+        if best_distance.nil? || distance < best_distance
+          best = index
+          best_distance = distance
+        end
+        index += 1
+      end
+      best
+    end
+
     COLOR_SYMBOLS.each do |sym|
       const_set(sym.upcase, new(sym))
     end
 
+    # The channel values the 6×6×6 cube (palette 16..231) samples.
+    # @return [Array<Integer>]
+    CUBE_LEVELS = [0, 95, 135, 175, 215, 255].freeze
+    private_constant :CUBE_LEVELS
+
+    # Channel value 0..255 → index into {CUBE_LEVELS} of the nearest level,
+    # so quantizing a channel is one array read rather than six compares.
+    # @return [Array<Integer>]
+    CUBE_INDEX = Array.new(256) { |c| (0...6).min_by { |i| (CUBE_LEVELS[i] - c).abs } }.freeze
+    private_constant :CUBE_INDEX
+
+    # xterm's default RGB for each of the 16 named colors, in {COLOR_SYMBOLS}
+    # order — what `:ansi16` quantization matches against. A terminal scheme
+    # may redefine these; see {#quantize}.
+    # @return [Array<Array<Integer>>]
+    ANSI16_RGB = [
+      [0, 0, 0], [128, 0, 0], [0, 128, 0], [128, 128, 0],
+      [0, 0, 128], [128, 0, 128], [0, 128, 128], [192, 192, 192],
+      [128, 128, 128], [255, 0, 0], [0, 255, 0], [255, 255, 0],
+      [0, 0, 255], [255, 0, 255], [0, 255, 255], [255, 255, 255]
+    ].freeze
+    private_constant :ANSI16_RGB
+
+    # Every named color, in {COLOR_SYMBOLS} order — the shared instances
+    # `:ansi16` quantization returns.
+    # @return [Array<Color>]
+    ANSI16_COLORS = COLOR_SYMBOLS.map { |sym| const_get(sym.upcase) }.freeze
+    private_constant :ANSI16_COLORS
+
+    # Every palette cell 0..255 as a {Color}, so quantizing to the palette
+    # allocates nothing and lands on a shared instance. Distinct from the
+    # {PALETTE_NAMES} constants, which cover only the *named* cells.
+    # @return [Array<Color>]
+    PALETTE_COLORS = Array.new(256) { |index| new(index) }.freeze
+    private_constant :PALETTE_COLORS
+
     # Names for the 256-color palette indices 16..255, from the standard
     # xterm chart (<https://www.ditig.com/256-colors-cheat-sheet>). A constant
     # per entry is pre-defined, an exact palette cell — no quantization:

data/lib/tuile/color_depth.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Tuile
+  # How many colors the terminal on the other end can actually show — the
+  # depth {Color#quantize} degrades a color to:
+  #
+  #   ColorDepth.detect                                        # => :truecolor
+  #   ColorDepth.detect(env: { "TERM" => "xterm-256color" })   # => :palette256
+  #   ColorDepth.detect(env: {})                               # => :ansi16
+  #
+  # Env-only: no terminal round-trip, so unlike {TerminalBackground.detect}
+  # there is no stdin timing to respect, and the answer cannot go stale
+  # mid-session the way a background color can.
+  #
+  # Terminals lie in both directions — `COLORTERM` frequently doesn't survive
+  # ssh (it isn't in the default `SendEnv` set) or tmux — so {OVERRIDE_ENV}
+  # beats every other signal, the escape hatch for a terminal detected wrong.
+  # Misdetection otherwise lands *conservatively*: a truecolor tmux
+  # advertising only `tmux-256color` reads as `:palette256`, which renders
+  # coarser but never mangled.
+  #
+  # == Implementation details
+  #
+  # Terminfo is deliberately not consulted — its `RGB` boolean and
+  # `colors#0x1000000` would mean shelling out to `tput`/`infocmp` at every
+  # startup, and the env ladder plus the override already covers the real
+  # terminal matrix.
+  module ColorDepth
+    # The depths, most capable first: 24-bit RGB, the 256-color palette, and
+    # the 16 named ANSI colors.
+    # @return [Array<Symbol>]
+    DEPTHS = %i[truecolor palette256 ansi16].freeze
+
+    # Environment variable that overrides detection outright; holds one of
+    # {DEPTHS}. Empty counts as unset.
+    # @return [String]
+    OVERRIDE_ENV = "TUILE_COLOR_DEPTH"
+
+    # `COLORTERM` values that promise 24-bit color.
+    # @return [Array<String>]
+    TRUECOLOR_COLORTERM = %w[truecolor 24bit].freeze
+
+    class << self
+      # The terminal's color depth, from {OVERRIDE_ENV}, else `COLORTERM`,
+      # else `TERM` (a `-direct` entry means 24-bit, a `256color` one the
+      # palette), else the 16-color floor.
+      #
+      # @param env [Hash{String => String}] environment to read; defaults to
+      #   `ENV` (which duck-types the `[]` lookup).
+      # @return [Symbol] one of {DEPTHS}.
+      # @raise [ArgumentError] when {OVERRIDE_ENV} holds an unknown value. It
+      #   is only ever set deliberately, so a typo in it is worth failing at
+      #   startup over — ignoring it silently means a whole session of
+      #   debugging the wrong colors.
+      def detect(env: ENV)
+        override = env[OVERRIDE_ENV].to_s
+        return parse_override(override) unless override.empty?
+
+        term = env["TERM"].to_s
+        return :truecolor if TRUECOLOR_COLORTERM.include?(env["COLORTERM"].to_s.downcase) ||
+                             term.include?("-direct")
+        return :palette256 if term.include?("256color")
+
+        :ansi16
+      end
+
+      private
+
+      # @param value [String] the raw {OVERRIDE_ENV} value.
+      # @return [Symbol]
+      def parse_override(value)
+        depth = value.strip.downcase.to_sym
+        return depth if DEPTHS.include?(depth)
+
+        raise ArgumentError,
+              "invalid #{OVERRIDE_ENV}: #{value.inspect} (expected one of #{DEPTHS.join(", ")})"
+      end
+    end
+  end
+end

data/lib/tuile/component/abstract_string_field.rb

@@ -42,6 +42,8 @@ module Tuile
     #
     # - {#preprocess_text} — input filter (e.g. {TextField} truncates to
     #   fit `rect.width - 1`).
+    # - {#preprocess_paste} — the same for {#handle_paste}, which lands a
+    #   whole clipboard at the caret in one mutation.
     # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
@@ -155,8 +157,42 @@ module Tuile
         handle_text_input_key(key)
       end
 
+      # Inserts pasted text at the caret as **one** mutation, so {#on_change}
+      # fires once for the whole paste rather than once per character.
+      # {#preprocess_paste} filters it first.
+      # @param text [String]
+      # @return [Boolean] always true — a field consumes every paste, an empty
+      #   one included.
+      def handle_paste(text)
+        insert_text(preprocess_paste(text))
+        true
+      end
+
       protected
 
+      # Input filter for {#handle_paste}, the paste-side counterpart of
+      # {#preprocess_text}. Strips the C0 control characters a text buffer
+      # cannot hold — a raw `\e` or `\t` reaching {Buffer} would move the real
+      # terminal cursor mid-frame — keeping `\n`, and turning a tab into a
+      # single space so pasted code keeps its word gaps. {TextField} narrows it
+      # further; an app wanting tab *expansion* overrides {#handle_paste}.
+      # @param text [String]
+      # @return [String]
+      def preprocess_paste(text) = text.tr("\t", " ").gsub(/[\x00-\x09\x0b-\x1f\x7f]/, "")
+
+      # Inserts `str` at the caret, leaving the caret behind it. The bulk
+      # counterpart of a subclass's per-key insert.
+      # @param str [String]
+      # @return [Boolean] true if the text changed.
+      def insert_text(str)
+        return false if str.empty?
+
+        new_text = @text.dup.insert(@caret, str)
+        @caret += str.length
+        self.text = new_text
+        true
+      end
+
       # Renders `text` on the field's background well, looked up from the
       # current {Screen#theme} at paint time: {Theme#active_bg_color} when this
       # input is on the active (focus) chain, {Theme#input_bg_color} otherwise —

data/lib/tuile/component/button.rb

@@ -55,8 +55,8 @@ module Tuile
       # It still *focuses*: {Component#handle_mouse}'s click-to-focus is ungated
       # by geometry. Same rule as {Checkbox#extent}, which documents the two
       # traps behind it.
-      # @return [Rect]
-      def extent = Rect.new(rect.left, rect.top, [caption.display_width + 4, rect.width].min, 1)
+      # @return [Size]
+      def extent = Size.new([caption.display_width + 4, rect.width].min, 1)
 
       # Fires {#on_click} on a left click within {#extent}; `super` runs first, so
       # a click anywhere in {#rect} still focuses.
@@ -64,7 +64,7 @@ module Tuile
       # @return [void]
       def handle_mouse(event)
         super
-        return unless event.button == :left && extent.contains?(event.point)
+        return unless event.button == :left && extent_rect.contains?(event.point)
 
         @on_click&.call
       end

data/lib/tuile/component/checkbox.rb

@@ -95,8 +95,8 @@ module Tuile
       # The extent ignores {Component#bg_color}: an inherited tint paints the dead
       # tail, but a hit test that silently widened with a background would be a
       # mode switch invisible in the code and untestable by inspection.
-      # @return [Rect]
-      def extent = Rect.new(rect.left, rect.top, [caption.display_width + 4, rect.width].min, 1)
+      # @return [Size]
+      def extent = Size.new([caption.display_width + 4, rect.width].min, 1)
 
       # Toggles on Space or Enter. Every other key is left unhandled so it bubbles
       # to an ancestor.
@@ -115,7 +115,7 @@ module Tuile
       # @return [void]
       def handle_mouse(event)
         super
-        return unless event.button == :left && extent.contains?(event.point)
+        return unless event.button == :left && extent_rect.contains?(event.point)
 
         toggle
       end