tuile 0.9.0 → 0.11.0

data/ideas/arrow-key-navigation.md

@@ -0,0 +1,205 @@
+# Arrow keys move focus between fields — as a *behavior*, not a layout class
+
+**Status:** design sketch, 2026-08-12. Nothing built. Started from the
+sampler's PasswordField pane ("Up/Down between the three fields would be
+friendlier"), but that pane is a *demo* of the feature, not an argument for
+it — the argument is a ten-field form. Open questions at the bottom are the
+point of this file.
+
+## What is being proposed
+
+In a form, Up/Down moves focus between fields, in addition to Tab/Shift+Tab.
+Tab keeps its current job (cycle every tab stop in the scope, wrapping);
+arrows do *local* motion within one container and stop at its edges.
+
+## Why it's plausible at all: Tuile already has the whole mechanism
+
+Two findings from the survey, both load-bearing:
+
+1. **`TextField` already declines Up/Down by design.** `text_field.rb:134-140`:
+   `on_key_up` / `on_key_down` are nil by default and the nil branch is
+   `return false`, with rdoc reading "when nil, UP falls through to the parent
+   (default behavior)". The clash we feared was already resolved in the
+   direction that enables this.
+2. **Rung 3 of the key ladder is exactly the right hook.** `bubble_key` asks
+   the focused widget, then each ancestor. AGENTS.md already names this as the
+   sanctioned home for scope-wide keys ("a layout's one-key jumps to its
+   panes"). So this is a `handle_key` on a container — no dispatch phase, no
+   gate in `Screen#handle_key`, no framework change.
+
+   Worth stating explicitly for a future reader: the key ladder's "no gate, no
+   predicate, no mode flag" rule constrains `Screen#handle_key`, **not** a
+   component's own `handle_key`. Adding behavior at rung 3 is sanctioned; a
+   per-instance switch on a *component* is not the thing that rule forbids.
+
+Everything that must keep the arrows already claims them and wins for free:
+`TextArea`, `TextView`, `List`, the three numeric fields, `ComboBox`.
+
+## Prior art
+
+Splits by lineage, not by age:
+
+- **FTXUI** — closest to Tuile architecturally, and does exactly this.
+  `Container::Vertical` is *defined* as "navigated vertically using up/down
+  arrow keys"; `Container::Horizontal` gets left/right. Dispatch is our shape:
+  active child asked first, container only sees what the child declined
+  (`container.cpp`, `OnEvent`). Arrows do **not** wrap (`MoveSelector`); Tab
+  wraps (`MoveSelectorWrap`).
+- **Midnight Commander** — "to move between the widgets use the arrow keys or
+  the Tab key". The ncurses form-dialog lineage generally (`dialog`, newt)
+  behaves this way; only MC was verified.
+- **Bubble Tea** — the canonical `examples/textinputs` cycles focus on
+  up/down/tab/shift+tab, but app-side; the framework has no focus model.
+- **Textual, ratatui, Ink, Vaadin** — no. Textual is the explicit web/ARIA
+  position: Tab between widgets, arrows only *within* a composite widget.
+
+## The shape: a behavior on a layout, not a `Layout::Form`
+
+`Layout::Form < Layout::Vertical` was the first sketch and is **rejected**.
+Reasons, in order of force:
+
+- **Vaadin's FormGroup precedent.** It coupled `Binder` to layouting and was
+  abandoned for it. `Form` here would couple a layout algorithm to a key
+  behavior — a smaller version of the same mistake.
+- **It breaks the moment the layout is insufficient.** A real form needs a
+  nested `Horizontal` row, or an `Absolute` for a capped-proportion split. Now
+  the behavior is attached to the *outer* class and the nested layouts are
+  arbitrary, so "does this container navigate?" stops being answerable from
+  the class. Policy carried by a class is inherited by every subclass and
+  unavailable to every non-subclass; policy carried by a setter is per
+  instance and never inherited.
+- **COP says so.** `Layout::Vertical` is a *generic, domain-agnostic*
+  component, and the skill's rule for those is to externalize policy via
+  injected strategies — not to subclass per policy. A `Form` whose only
+  divergence is one `handle_key` is precisely the "shallow divergent
+  scaffolding — duplicate or inject, don't fold into a base" case.
+
+So: **any layout can be given the behavior; none has it by default.** virtui
+gets nothing and stays exactly as it is; a form opts in. The sampler's `form`
+helper (`sampler.rb:832`) becomes the one place the demo opts in.
+
+Concretely, the nesting story this buys — and it is the whole reason for the
+shape: a layout without the behavior **declines** the arrow key, so it bubbles
+to the next ancestor that *does* have it. An inner `Absolute` inside a
+navigating `Vertical` is therefore one opaque slot: focus anywhere inside it,
+Down moves to the next slot of the outer box. No inheritance, no surprise, and
+the answer is the same at any nesting depth.
+
+## Semantics that already look settled
+
+Recorded here so the open questions below stay narrow.
+
+- **Walk direct children, not `on_tree`.** A `Horizontal` row nested in a
+  navigating `Vertical`: flattened pre-order would make Down from the row's
+  left field jump to the row's *right* field, which is geometrically wrong.
+  Direct children makes Down go to the next row. (FTXUI indexes `children()`
+  for the same reason.) "Which direct child holds focus" is a parent-chain
+  walk from `screen.focused`, so depth doesn't matter.
+- **Skip children with no focusable descendant** (a `Label`, a spacer).
+- **Don't wrap; decline at the edge.** Two payoffs: nesting composes (an inner
+  box at its edge declines and the outer box moves to the next sibling group),
+  and wrapping stays Tab's distinguishing job. Same split FTXUI landed on.
+- **Descend via the existing focus cascade** — set `screen.focused` to the
+  sibling and let `Layout#on_focus` (`layout.rb:203`) forward to its first tab
+  stop. See open question on backwards entry.
+- **Mouse is untouched.** Popups are untouched — the bubble is already scoped
+  to the topmost modal popup.
+
+## The honest argument against
+
+A *partially* live feature is worse than an absent one: if arrows navigate in
+80% of positions the user can't build a model. Inside a form the exception set
+is mostly coherent — `TextArea` / `TextView` / `List` swallow arrows, and
+they're the *tall* widgets, where a user already expects arrows to move
+*inside* the box. That reads as "arrows move within a tall widget, between
+short ones", which is learnable and is the story MC tells.
+
+The three numeric fields break that story and are the real problem (see Q6).
+
+## Open questions
+
+**Q1 — What exactly is the knob?** Candidates, roughly in order of how much
+API they add:
+
+  a. keyword + accessor on `Layout`: `navigation: :vertical` / `:horizontal` /
+     `:both` / `nil` (default `nil`).
+  b. a strategy *object*: `layout.navigation = Layout::ArrowNavigation.new(...)`,
+     leaving room for per-instance config and app subclassing.
+  c. a module the app mixes in: `Vertical.new.extend(Layout::ArrowNavigable)`.
+     Composable with any layout without touching `Layout`, but `extend` on a
+     singleton class is obscure and hard to document.
+  d. a general `Component#on_key` interceptor hook (the shape
+     `AbstractStringField#on_key` already has), with the framework shipping a
+     ready-made callable to assign. Most decoupled — touches `Layout` not at
+     all — but adds a general hook whose merits should be argued on their own,
+     not smuggled in under this feature.
+
+  (a) is the smallest thing that works; (d) is the most COP-pure. Not decided.
+
+**Q2 — Where does the axis come from?** If the behavior is layout-agnostic it
+can't be derived from the class. `Vertical` → up/down and `Horizontal` →
+left/right are natural defaults, but `Absolute` has none. Does the knob always
+carry an explicit axis, or default per class and require it on `Absolute`?
+
+**Q3 — Should `Horizontal` / left-right navigation exist at all?**
+`AbstractStringField` *always* consumes Left/Right for the caret, so a row of
+text fields will never arrow-navigate while a row of Buttons/Checkboxes will.
+The rule stays uniform (widget wins); the outcome looks selective. Ship both
+axes, or vertical-only until someone asks?
+
+**Q4 — Ordering inside an `Absolute`.** Declaration order is all that's
+available and may not match visual order — the original worry that killed the
+idea of putting this on every layout. Options: document "declaration order is
+yours to get right"; or sort direct children geometrically per keypress (by
+`rect.top`, then `rect.left`), which is cheap and actually correct, and would
+make `Absolute` a first-class citizen here. Is geometric ordering worth it?
+
+**Q5 — Backwards entry into a multi-widget sibling.** `Layout#on_focus` always
+forwards to the *first* tab stop, so arrowing **Up** into a previous group
+lands on its first widget rather than its last. FTXUI has the same wart. Fix
+with a `last:` variant of the cascade, or accept it?
+
+**Q6 — The numeric fields.** `IntegerField` / `FloatField` / `BigDecimalField`
+consume Up/Down to step by ±1, and they are *one row tall* — so they break the
+"arrows move within tall widgets" story silently, with nothing on screen
+explaining why. This is the sharpest concrete collision. Options:
+
+  a. leave it; document the exception,
+  b. move stepping to `Ctrl+Up/Down` or `PgUp/PgDn` (breaking, but the fields
+     are young),
+  c. make stepping opt-in per field (`step = 1` / `nil`) — a knob, but on the
+     widget that actually has the ambiguity, and a numeric field in a form
+     usually doesn't want spinner behavior anyway.
+
+**Q7 — `List` at its edges.** It clamps and returns true, so arrows can never
+escape a focused list; only Tab does. Keep clamping (a list is a list, and MC
+agrees), or have it decline at its edges so arrows escape? Note this is
+exactly virtui's shape, so the answer matters more there than in a form.
+
+**Q8 — `ComboBox` is asymmetric.** Closed, it eats Down to open the menu
+(`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?
+
+**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,
+which Tuile has no notion of.
+
+**Q10 — Does Enter participate?** `dialog(1)` moves to the next field on
+Enter. Almost certainly out of scope — `Checkbox`, `Button` and `TextArea` all
+claim Enter already, and book ch5 has the per-widget Enter table — but worth
+rejecting explicitly rather than by omission.
+
+**Q11 — Where does the code live?** Zeitwerk wants one top-level constant per
+file. If Q1 lands on (b) or (c) it needs its own file under
+`lib/tuile/component/layout/`; if (a), it's a few lines on `Layout` itself.
+Also: any public signature change means `rake sig` in the same commit.
+
+## Graduation
+
+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` —
+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/new-components.md

@@ -0,0 +1,118 @@
+# Components Vaadin has and Tuile doesn't — the survey
+
+**Status:** survey done 2026-07-25 against Vaadin **25.2** (54 free/OSS
+components, via the Vaadin docs MCP). This file is the roadmap; each
+component we actually decide to build gets its own `ideas/<name>.md`.
+Retire this file once the interesting part of the list is either built or
+explicitly rejected — the tiering below is the only nugget worth keeping,
+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
+"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
+sampler ported onto them.
+
+## What Tuile already has
+
+Seven of the 54 have a counterpart: Button, Text Field, Text Area,
+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} is line-based, with no typed items and no
+multi-select.
+
+Tuile also has pieces Vaadin doesn't name as components — `ListDropdown`,
+`TextView`, `LogWindow`, `VerticalScrollBar` — so the gap is not
+symmetric.
+
+That leaves ~46 gaps.
+
+## Tier 1 — reachable from what exists (S–M each)
+
+| 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` | needs corner-anchored (non-centered) popup placement |
+| Confirm Dialog | `Popup`+`Window`+`Button` | fold `PickerWindow` in |
+| 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 |
+| 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 |
+
+## Tier 2 — worth doing, each blocked on a new seam
+
+| Component | Blocked on |
+|---|---|
+| **Grid** (the flagship gap) | column model + renderer strategies + typed items + horizontal scroll (L) |
+| Form Layout | a field label/helper seam (Vaadin's `HasLabel`) — Tuile fields carry no caption |
+| Email Field | a validation seam (`HasValidation`: invalid state + error line) |
+| Date / Time / DateTime Picker | calendar-grid popup over Popover (L) |
+| Multi Select Combo Box | Checkbox Group + ComboBox |
+| Split Layout → Master Detail Layout | mouse **motion/drag**: Tuile runs X10 mode 1000 (press only, no release, no motion) |
+| 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 |
+| 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 |
+
+## Tier 3 — design tension or marginal
+
+- **Scroller** — scrolling *arbitrary* content needs clipping/viewport
+  machinery and pushes against the top-down layout invariant (it wants to
+  measure content). Best kept as a documented road-not-taken.
+- **Tooltip** — competes with Tuile's status-bar `keyboard_hint` idiom.
+- **Card** — overlaps `Window` almost entirely.
+- **Avatar / Avatar Group** — initials in a box; little value on a TTY.
+- **Not applicable:** Field Highlighter (collaboration), Themable Mixin
+  (covered by `Theme`).
+
+## Infrastructure that gates clusters
+
+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
+   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`
+   constraints per row and column rather than invent a second vocabulary.
+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.
+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.
+
+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
+(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
+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/ideas/per-component-buffers.md

@@ -0,0 +1,55 @@
+# Per-component back buffers + a z-order compositor
+
+**Status:** deferred, not worth doing yet. Graduated out of `Buffer`'s
+rdoc (it was speculative design musing, not caller contract — see the
+doc-kinds rules in AGENTS.md). Parked here so the thinking isn't lost.
+
+## The idea
+
+Today there is one global {Tuile::Buffer}: every component paints into
+the same grid via `set_line` / `set_char` / `fill`, and {Tuile::Screen}
+flushes its minimal diff to the terminal.
+
+Components already paint through that drawing surface *without knowing*
+whether it's the one global buffer or a private one — the indirection is
+deliberate. So per-component back buffers plus a z-order compositor could
+drop in **without touching component code**: give each component its own
+`Buffer`, let it paint into that, and have a compositor blend the
+per-component buffers in stacking order into the frame the terminal sees.
+
+## Why it's not worth doing yet
+
+The current single-buffer diff already captures most of the win a
+compositor would give:
+
+- The flush drops unchanged cells from the wire, so an unchanged region
+  costs nothing on the terminal side regardless of how many components
+  overlap it.
+- An occluded component that didn't change is never repainted at all —
+  invalidation gates it out before `repaint` runs.
+
+So a compositor would only save **residual `repaint` CPU**: the cost of a
+component re-rendering its content into a buffer, when that content then
+turns out to be occluded or unchanged after compositing.
+
+## The one regime where it pays off
+
+High repeat-rate scroll — a held arrow key or a spun mouse wheel — over a
+**large** component on a **large** screen, where re-rendering the
+component's content on every repeat is the dominant cost. A per-component
+buffer would let an unchanged-but-scrolled component be re-composited
+(cheap) instead of re-rendered (expensive) each repeat.
+
+Until Tuile has a real workload in that regime, the extra machinery
+(per-component buffer allocation, a compositor pass, dirty propagation
+across buffer layers) buys nothing over what the single-buffer diff
+already delivers.
+
+## If we revisit
+
+- The component-facing drawing API (`set_line` / `set_char` / `fill`)
+  stays the same — that's the whole point of the existing indirection.
+- What changes is *who owns the buffer* and the addition of a
+  composite-into-frame step between `repaint` and `Buffer#flush`.
+- Measure first: prove the residual-`repaint`-CPU regime is real and
+  material before adding a layer.

data/lib/tuile/buffer.rb

@@ -21,17 +21,10 @@ module Tuile
   # size. There is deliberately no per-frame whole-buffer clear or copy;
   # un-touched cells retain the previous frame's value.
   #
-  # The bookkeeping avoids hashing and full-grid scans: a dirty flag **on each
-  # cell** (O(1) set, no `Set` bucket math, no separate array), a per-row
-  # boolean so {#flush} scans only the rows that changed, and one global flag
-  # so {#dirty?} and the "nothing changed" early-out are O(1). {#flush} clears
-  # every flag it consumes.
-  #
-  # Cells are **mutable and pre-allocated**: the grid builds its {Cell}s once
+  # Cells are **mutable and pre-allocated** — the grid builds its {Cell}s once
   # (at construction and {#resize}) and rewrites them in place, so a normal
-  # paint allocates nothing per cell. That is why {Cell} is a plain mutable
-  # object rather than a frozen value type. The empty state of a cell is a
-  # space in the default style.
+  # paint allocates nothing per cell. That's why {Cell} is a plain mutable
+  # object, not a frozen value type.
   #
   # ## Wide characters
   #
@@ -40,19 +33,6 @@ module Tuile
   # nothing for, since the glyph itself advances the cursor two columns).
   # Overwriting either half of a wide glyph blanks the orphaned half, so the
   # grid never holds a dangling continuation or a headless one.
-  #
-  # ## Future direction
-  #
-  # Components paint through this drawing surface ({#set_line} / {#set_char})
-  # without knowing whether it is the one global buffer or a private one — that
-  # indirection is deliberate, so per-component back buffers plus a z-order
-  # compositor could drop in without touching component code. It is not worth
-  # doing yet: the diff already drops unchanged cells from the wire, and an
-  # occluded component that didn't change is never repainted at all, so a
-  # compositor would only save residual `repaint` CPU. It pays off in exactly
-  # one regime — high repeat-rate scroll (held arrow / mouse wheel) of a large
-  # component on a large screen, where re-rendering the content each repeat is
-  # the dominant cost.
   class Buffer
     # One screen cell: a single grapheme cluster, the {StyledString::Style} it's
     # drawn in, and a dirty flag. Mutable by design (see {Buffer} "Dirty
@@ -118,10 +98,15 @@ module Tuile
     # emoji), so the per-grapheme width lookup — the dominant cost of a repaint
     # (see `benchmark/display_width.rb`) — collapses to a Hash read after the
     # first sighting. Shared across all buffers and unbounded, but bounded in
-    # practice by the font's glyph set; safe to share because all painting runs
-    # on the single UI thread (see AGENTS.md "Threading rule").
+    # practice by the font's glyph set.
+    #
+    # The memo carries its weight most for emoji: resolving a sequence under
+    # {StyledString::EMOJI_WIDTH} costs ~20x a plain lookup, and this pays it
+    # once per distinct cluster. Racing writes from a non-UI thread are benign
+    # rather than merely absent — the value for a grapheme is deterministic, so
+    # a lost write only costs a recomputation.
     # @return [Hash{String => Integer}]
-    WIDTH_CACHE = Hash.new { |h, g| h[g] = Unicode::DisplayWidth.of(g) }
+    WIDTH_CACHE = Hash.new { |h, g| h[g] = Unicode::DisplayWidth.of(g, emoji: StyledString::EMOJI_WIDTH) }
     private_constant :WIDTH_CACHE
 
     # Memoized {Unicode::DisplayWidth.of}. Use this for every paint-path width
@@ -174,9 +159,8 @@ module Tuile
     end
 
     # Writes a {StyledString} starting at `(x, y)`, advancing by each grapheme's
-    # display width and clipping at the right edge. The workhorse that replaces
-    # the old `screen.print(TTY::Cursor.move_to(x, y), styled.to_ansi)` per-row
-    # paint. Newlines in the string are not handled — pass one physical line.
+    # display width and clipping at the right edge. Newlines are not handled —
+    # pass one physical line.
     # @param x [Integer] starting column.
     # @param y [Integer] row.
     # @param styled [StyledString]
@@ -346,21 +330,27 @@ module Tuile
       return unless in_bounds?(x, y)
       return if w <= 0
 
-      if w == 2 && !in_bounds?(x + 1, y)
+      if w > 1 && !in_bounds?(x + w - 1, y)
         blank_left_partner(x, y)
         return write_cell(x, y, " ", style)
       end
 
-      # Repair only the glyphs we'd leave half-overwritten on our flanks: a wide
-      # glyph whose right half sits at `x`, or one whose left half sits at the
-      # last cell we write. The cells we fully rewrite need no pre-blanking —
-      # pre-blanking the continuation only to re-empty it would churn it
-      # spuriously dirty, which misplaces the next flush onto the glyph's right
-      # half (see bug/, balloon corruption).
+      # Repair only the glyphs we'd leave half-overwritten on our flanks: one
+      # whose tail reaches `x`, or one whose head sits at the last cell we write.
+      # The cells we fully rewrite need no pre-blanking — pre-blanking a
+      # continuation only to re-empty it would churn it spuriously dirty, which
+      # misplaces the next flush onto the glyph's right half (see bug/, balloon
+      # corruption).
       blank_left_partner(x, y)
       blank_right_partner(x + w - 1, y)
       write_cell(x, y, grapheme, style)
-      write_cell(x + 1, y, "", style) if w == 2
+      # A while loop, not (1...w).each: this runs once per painted cell, and a
+      # Range allocation per cell is 8000 per full-screen repaint.
+      i = 1
+      while i < w
+        write_cell(x + i, y, "", style)
+        i += 1
+      end
     end
 
     # (Re)allocates a blank grid of `size` with clean dirty state. Callers
@@ -451,31 +441,42 @@ module Tuile
       @any_dirty = true
     end
 
-    # If `(x, y)` holds the right half (continuation) of a wide glyph, blanks the
-    # orphaned left half at `x - 1`. Called before a write lands on `x`, so the
-    # wide glyph to the left isn't left headless.
+    # If `(x, y)` holds a continuation, blanks the head of the glyph it belongs to
+    # and every continuation up to — but not including — `x`. Called before a
+    # write lands on `x`, so the glyph reaching into `x` isn't left headless.
+    # Walks left rather than assuming the head sits at `x - 1`: a glyph may be
+    # wider than two columns, so its tail can run several cells.
     # @param x [Integer] column
     # @param y [Integer] row
     # @return [void]
     def blank_left_partner(x, y)
-      return unless in_bounds?(x, y) && @cells[index(x, y)].continuation? && in_bounds?(x - 1, y)
+      return unless in_bounds?(x, y) && @cells[index(x, y)].continuation?
 
-      write_cell(x - 1, y, " ", DEFAULT_STYLE)
+      head = x - 1
+      head -= 1 while in_bounds?(head, y) && @cells[index(head, y)].continuation?
+      return unless in_bounds?(head, y)
+
+      cx = head
+      while cx < x
+        write_cell(cx, y, " ", DEFAULT_STYLE)
+        cx += 1
+      end
     end
 
-    # If the cell just right of `(x, y)` is a continuation (the right half of a
-    # wide glyph whose origin is `(x, y)`), blanks it. Called before a write
-    # lands on `x`, so overwriting a wide origin doesn't strand its continuation.
-    # A continuation can only ever belong to the wide glyph immediately to its
-    # left, so the empty-grapheme test is exact — and cheaper than re-measuring
-    # the origin's width.
+    # Blanks the run of continuations immediately right of `(x, y)` — the tail of
+    # a glyph whose head is at or before `x`, and which the write landing on `x`
+    # is about to decapitate. A continuation always belongs to the nearest glyph
+    # on its left, so the empty-grapheme test is exact — and cheaper than
+    # re-measuring that glyph's width.
     # @param x [Integer] column
     # @param y [Integer] row
     # @return [void]
     def blank_right_partner(x, y)
-      return unless in_bounds?(x + 1, y) && @cells[index(x + 1, y)].continuation?
-
-      write_cell(x + 1, y, " ", DEFAULT_STYLE)
+      cx = x + 1
+      while in_bounds?(cx, y) && @cells[index(cx, y)].continuation?
+        write_cell(cx, y, " ", DEFAULT_STYLE)
+        cx += 1
+      end
     end
   end
 end

data/lib/tuile/color.rb

@@ -29,16 +29,10 @@ module Tuile
   # Color.coerce(nil)            # nil → nil
   # ```
   #
-  # Which entry point to use is a deliberate policy split. High-traffic
-  # call sites ({StyledString} and friends) stay lenient and {.coerce} raw
-  # forms — you don't want factory ceremony on every styled span.
-  # Declaration sites ({Theme}, defined once per app) are strict and take
-  # only {Color} instances, where `Color.palette(130)` documents itself in
-  # a way the bare `130` (palette index? RGB channel?) does not.
-  #
-  # {#to_ansi} renders a full SGR escape (`"\e[31m"`); {#sgr_codes} returns the
-  # raw numeric codes so callers (notably {StyledString}) can combine them with
-  # other SGR attributes in a single sequence.
+  # {.coerce} is the lenient entry point (raw forms plus `nil`); the named
+  # factories and constants are the strict, self-documenting path for
+  # declaration sites — see the book's chapter 6 for why theme colors take
+  # {Color} instances only.
   class Color
     # Symbolic color names. Order is significant: indices 0..7 map to the
     # standard ANSI colors (SGR 30..37 fg / 40..47 bg); indices 8..15 map to