tuile 0.13.0 → 0.14.0

data/examples/sampler.rb

@@ -134,7 +134,7 @@ module SamplerExample
     attr_reader :demo_window, :menu_bar, :jump_box
 
     # The bottom row. Tuile draws no status bar and reserves no row
-    # (`D-status-bar`) — this one is the sampler's own, kept current by
+    # (`D_status_bar`) — this one is the sampler's own, kept current by
     # {Tuile::Screen#on_focus_changed=}. Naming the focused component makes Tab
     # traversal visible as you walk a pane, which no per-pane label shows.
     # @return [void]
@@ -216,6 +216,7 @@ module SamplerExample
       Menu.new("Overlay", "o", [
                  Entry.new("Popup", :build_popup_launcher, "p"),
                  Entry.new("Notification", :build_notification_launcher, "n"),
+                 Entry.new("ConfirmWindow", :build_confirm_launcher, "c"),
                  Entry.new("InfoWindow", :build_info_launcher, "i"),
                  Entry.new("PickerWindow", :build_picker_launcher, "k"),
                  Entry.new("LogWindow", :build_log_window, "l")
@@ -491,24 +492,21 @@ module SamplerExample
     # Slash commands the demo offers; the menu filters these by what's typed.
     SLASH_COMMANDS = %w[/help /list /open /save /clear /quit].freeze
 
-    # A non-modal Popup used as an autocomplete menu. Focus (and the caret)
-    # stays in the TextArea the whole time: an `on_change` listener refills the
-    # menu, an `on_key` interceptor forwards Up/Down/Enter/ESC to it while it's
-    # open, and the menu floats above the field, anchored to the caret. None of
-    # this is baked into TextArea — it's all assembled here from stock hooks.
+    # A ListDropdown driven from a TextArea — the same shape {ComboBox} and
+    # {Select} use, but wired by app code onto a field that knows nothing about
+    # it. Focus (and the caret) stays in the TextArea the whole time: an
+    # `on_change` listener refills the menu, and an `on_key` interceptor hands
+    # movement keys to `#move` and Enter to `#choose` while it is open. None of
+    # this is baked into TextArea.
     def build_slash_demo
       prompt = Tuile::Component::Label.new
-      prompt.text = "Non-modal Popup as an autocomplete menu. Type a slash command\n" \
-                    "(try \"/\" or \"/s\"). The menu floats above the field without taking\n" \
+      prompt.text = "A ListDropdown driven from a TextArea. Type a slash command\n" \
+                    "(try \"/\" or \"/s\"). The menu floats over the field without taking\n" \
                     "focus: Down/Up move the selection, Enter accepts, ESC dismisses, and\n" \
                     "ordinary typing keeps editing the field and refilters the menu."
       area = Tuile::Component::TextArea.new
 
-      list = Tuile::Component::List.new
-      list.cursor = Tuile::Component::List::Cursor.new
-      list.show_cursor_when_inactive = true # highlight the selection though focus stays in the field
-      window = Tuile::Component::Window.new("Commands").tap { _1.content = list }
-      overlay = Tuile::Component::Popup.new(content: window, modal: false)
+      overlay = Tuile::Component::ListDropdown.new
       @slash_overlay = overlay
 
       refill = lambda do
@@ -516,20 +514,23 @@ module SamplerExample
         if matches.empty?
           overlay.close if overlay.open?
         else
+          overlay.items = matches
           overlay.open unless overlay.open?
-          list.lines = matches
-          anchor_overlay(overlay, area)
+          # Width is the driver's call, never the dropdown's: measure the
+          # commands rather than inherit the full-width TextArea's columns.
+          overlay.anchor_to(area.rect, rows: matches.size, width: slash_menu_width(matches))
         end
       end
 
       area.on_change = ->(_text) { refill.call }
-      list.on_item_chosen = ->(_idx, line) { accept_slash_command(area, line.to_s) }
+      overlay.on_item_chosen = ->(_idx, item) { accept_slash_command(area, item.to_s) }
       area.on_key = lambda do |key|
         next false unless overlay.open?
+        next true if overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
 
         case key
-        when Tuile::Keys::UP_ARROW, Tuile::Keys::DOWN_ARROW, Tuile::Keys::ENTER
-          list.handle_key(key) # works though the list is unfocused — dispatch gates on focus, not the list
+        when Tuile::Keys::ENTER
+          overlay.choose
         when Tuile::Keys::ESC
           overlay.close
           true
@@ -928,6 +929,21 @@ module SamplerExample
       BgChoice.new("Hot pink (RGB)", Tuile::Color.rgb(120, 20, 70))
     ].freeze
 
+    # The one choice that can't be a constant: the terminal's *own* background
+    # stepped +10 per channel — the borderless-pane tint, which only sits right
+    # when it's derived from the real background. Nil on a terminal that
+    # reported none, which is the branch most users will actually see.
+    def terminal_tint_choice
+      bg = Tuile::Screen.instance.background_color
+      return BgChoice.new("Terminal background — none reported", nil) if bg.nil?
+
+      BgChoice.new("Terminal background +10 (derived)",
+                   Tuile::Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }))
+    end
+
+    # @param derived [BgChoice] the live terminal-derived tint, offered second.
+    def bg_choices(derived) = [BG_CHOICES.first, derived, *BG_CHOICES[1..]]
+
     def build_background
       intro = Tuile::Component::Label.new
       intro.text = "bg_color tints a component and every descendant that doesn't set its own.\n" \
@@ -951,7 +967,8 @@ module SamplerExample
       # their own well. Theme::Ref picks re-resolve on a scheme flip with no hook;
       # the hard-coded Colors are fixed by design, so no on_theme_changed here.
       outer = nil
-      combo = Tuile::Component::ComboBox.new(items: BG_CHOICES)
+      derived = terminal_tint_choice
+      combo = Tuile::Component::ComboBox.new(items: bg_choices(derived))
       combo.item_label = :label.to_proc
       combo.on_value_change = ->(choice) { outer.bg_color = choice.color }
 
@@ -960,6 +977,17 @@ module SamplerExample
         f.add(combo, Fixed[1], cross: Fixed[40])
         f.add(box, Expand[1])
       end
+      # The derived tint is the one pick whose *color* moves under it: a flip
+      # re-probes the terminal, so rebuild the choice and re-apply it if it is
+      # the current one. Expect it to correct itself a frame late — the flip
+      # report carries no RGB, so this hook runs once on the old background and
+      # again when the re-probe answers.
+      outer.on_theme_changed = lambda do
+        was_derived = combo.value.equal?(derived)
+        derived = terminal_tint_choice
+        combo.items = bg_choices(derived)
+        combo.value = derived if was_derived
+      end
       combo.value = BG_CHOICES.first # show "None" as the resting selection
       outer
     end
@@ -1166,6 +1194,61 @@ module SamplerExample
       end
     end
 
+    # The three factories, the layer-1 builder (3-way), and a message long
+    # enough to scroll. The status row makes the one-dismissal-channel contract
+    # visible: every route out of a dialog lands in exactly one callback.
+    def build_confirm_launcher
+      label = Tuile::Component::Label.new
+      label.text = "ConfirmWindow asks a question with a row of buttons, in a popup sized to\n" \
+                   "its content (capped at half the screen). Every button closes the dialog;\n" \
+                   "ESC, q or an outside click dismiss it instead. An underlined letter presses\n" \
+                   "its button from anywhere; Up/Down scroll a long message meanwhile."
+      status = Tuile::Component::Label.new("Outcome: none yet")
+      report = ->(outcome) { status.text = "Outcome: #{outcome}" }
+      buttons = [
+        Tuile::Component::Button.new("Confirm") do
+          Tuile::Component::ConfirmWindow.confirm(
+            "Delete Report Q4?", "This cannot be undone.",
+            confirm: "Delete", on_dismiss: -> { report.call("kept the report") }
+          ) { report.call("deleted the report") }
+        end,
+        Tuile::Component::Button.new("Yes/No") do
+          Tuile::Component::ConfirmWindow.yes_no(
+            "Overwrite draft.txt?", "The file already exists.",
+            on_dismiss: -> { report.call("kept draft.txt") }
+          ) { report.call("overwrote draft.txt") }
+        end,
+        Tuile::Component::Button.new("Alert") do
+          Tuile::Component::ConfirmWindow.alert("Export failed", "Contact support@example.com.")
+        end,
+        Tuile::Component::Button.new("3-way") do
+          dialog = Tuile::Component::ConfirmWindow.new("Unsaved changes")
+          dialog.message = "Save your changes before leaving?"
+          dialog.button("Save")    { report.call("saved") }
+          dialog.button("Discard") { report.call("discarded") }
+          dialog.button("Cancel")
+          dialog.on_dismiss = -> { report.call("stayed put") }
+          dialog.open
+        end,
+        Tuile::Component::Button.new("Long") do
+          dialog = Tuile::Component::ConfirmWindow.new("Terms of Service")
+          dialog.message = (1..40).map { "#{_1}. Clause #{_1} of the agreement, spelled out in full." }.join("\n")
+          dialog.button("Accept")  { report.call("accepted the terms") }
+          dialog.button("Decline") { report.call("declined the terms") }
+          dialog.on_dismiss = -> { report.call("left the terms unanswered") }
+          dialog.open
+        end
+      ]
+      strip = row do |r|
+        buttons.each { |b| r.add(b, Fixed[button_width(b)]) }
+      end
+      form do |f|
+        f.add(label, Fixed[4])
+        f.add(strip, Fixed[1])
+        f.add(status, Fixed[1])
+      end
+    end
+
     def build_popup_launcher
       launcher(
         "Popup is a modal overlay wrapping any Component.\n" \
@@ -1179,17 +1262,39 @@ module SamplerExample
     end
 
     def build_info_launcher
-      launcher(
-        "InfoWindow is a Window of read-only text lines, openable as a popup.",
-        "Open InfoWindow"
-      ) do
-        Tuile::Component::InfoWindow.open(
-          "Hello",
-          ["InfoWindow displays static text",
-           "inside a popup.",
-           "",
-           "Press ESC or q to close."]
-        )
+      label = Tuile::Component::Label.new
+      label.text = "InfoWindow is a Window with a read-only body: prose (message=) wraps in\n" \
+                   "a TextView, rows (lines=) stay one per row in a List, truncating. The\n" \
+                   "constructor picks the presentation by the body's type."
+      buttons = [
+        Tuile::Component::Button.new("Prose") do
+          Tuile::Component::InfoWindow.open(
+            "About",
+            "InfoWindow renders a String as wrapping prose: this sentence is long " \
+            "enough to wrap to the popup's width, and it scrolls when it outgrows " \
+            "the box. Press ESC or q to close."
+          )
+        end,
+        Tuile::Component::Button.new("Rows") do
+          Tuile::Component::InfoWindow.open(
+            "Files",
+            ["drwxr-xr-x  src/",
+             "drwxr-xr-x  spec/",
+             "-rw-r--r--  README.md   4.1k",
+             "-rw-r--r--  Rakefile     812",
+             "",
+             "Rows never wrap: a long row like this one is truncated at the popup's edge, keeping columns aligned.",
+             "",
+             "Press ESC or q to close."]
+          )
+        end
+      ]
+      strip = row do |r|
+        buttons.each { |b| r.add(b, Fixed[button_width(b)]) }
+      end
+      form do |f|
+        f.add(label, Fixed[3])
+        f.add(strip, Fixed[1])
       end
     end
 
@@ -1207,7 +1312,7 @@ module SamplerExample
 
     def build_log_window
       log = Tuile::Component::LogWindow.new("Log")
-      ["LogWindow is a Window wrapping an auto-scrolling TextView.",
+      ["LogWindow is a Window framing an auto-scrolling LogTextView.",
        "Lines are appended via #log (safe from any thread).",
        "Used with Logger::IO it captures arbitrary log output."].each { |line| log.log(line) }
       log
@@ -1315,18 +1420,13 @@ module SamplerExample
       area.caret = start + command.length + 1
     end
 
-    # Positions the overlay just below the caret, flipping above when there's
-    # no room beneath, and clamps it to the screen.
-    def anchor_overlay(overlay, area)
-      caret = area.cursor_position
-      return if caret.nil?
-
-      screen_size = Tuile::Screen.instance.size
-      size = overlay.rect
-      top = caret.y + 1
-      top = [caret.y - size.height, 0].max if top + size.height > screen_size.height - 1
-      left = caret.x.clamp(0, [screen_size.width - size.width, 0].max)
-      overlay.rect = Tuile::Rect.new(left, top, size.width, size.height)
+    # The slash menu's width: the widest command plus List's two row gutters,
+    # clamped to the screen. ListDropdown places itself but never measures — the
+    # width policy stays with the driver, exactly as it does for Select.
+    # @return [Integer]
+    def slash_menu_width(matches)
+      widest = matches.map { Tuile::StyledString.plain(_1).display_width }.max || 0
+      [widest + 2, Tuile::Screen.instance.size.width].min
     end
 
     # A button's natural width — enough to show "[ caption ]".

data/ideas/arrow-key-navigation.md

@@ -107,7 +107,7 @@ Recorded here so the open questions below stay narrow.
 - **{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
+  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.
 
@@ -215,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,20 +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~~ | 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`) |
+| ~~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 |
+| ~~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 |
@@ -70,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 |
@@ -91,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,25 +100,25 @@ file when its cluster comes up:
    Layout is actually blocked on — the layout half now exists.
 3. **Validation seam** → Email Field, forms generally.
 4. **Anchored Popover extraction** → pickers, Tooltip. **No longer gates Menu
-   Bar** — `D-menu-bar` argues the side-anchor is a sibling method on
+   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/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).