tuile 0.11.0 → 0.13.0

data/DECISIONS.md

@@ -65,7 +65,7 @@ descendants pick it up; a widget with its own explicit bg
 (`TextField`/`TextArea` wells) keeps its look. `nil` keeps its existing
 meaning — "inherit upward," with the terminal default as the root of the
 chain. Self-painters route the effective bg through a single choke point,
-`Component#draw_line` / `#draw_char`.
+`Component#draw_text` / `#draw_char`.
 
 **Alternatives rejected.**
 - *Explicit per-component, no inheritance* (Textual/ratatui end):
@@ -1004,7 +1004,7 @@ much of `List` to reuse and what the value should be. (A single-select group
   from the list. Correct, and about 15 lines of forwarding plus a subclass, all
   to protect a promise nothing relied on (see `D-boolean-fields`' rejected Enter
   reservation). Reach for it only if a driver genuinely needs Enter for itself.
-- *Paint the rows directly (`< Component`, `draw_line` per row):* wrong here.
+- *Paint the rows directly (`< Component`, `draw_text` per row):* wrong here.
   The cursor-distinct-from-selection structure *is* `List`, a checkbox group is
   the one most likely to be long enough to scroll, and painting rows means
   re-implementing the cursor, the viewport, the scrollbar and the mouse
@@ -1110,7 +1110,7 @@ list floors at 0 and a `Cursor::Limited` keeps its own notion of "last". The
   moving a piece of user-facing navigation state. It also does not scroll into
   view (`move_viewport_to_cursor` is private to `List`'s own key/mouse paths),
   so on a scrolling group it parks the cursor off-screen. Left to the app.
-- *Paint the rows directly (`< Component` + `draw_line`), the fallback the idea
+- *Paint the rows directly (`< Component` + `draw_text`), the fallback the idea
   note held open:* it existed to escape the four frictions above, which the
   interaction model removes. Composing a `List` then costs nothing and keeps the
   cursor, viewport, scrollbar and mouse arithmetic in one place.
@@ -1161,7 +1161,7 @@ caret on the index axis was never in question — edits, word jumps and
 redefinition.
 
 **Decision — scroll horizontally instead of capping to the width.** `left_column`
-follows the caret by the minimum needed, mirroring `TextArea#top_display_row`.
+follows the caret by the minimum needed, mirroring `TextArea#scroll_top_row`.
 This deletes the width-derived capacity rule rather than fixing its arithmetic:
 the old `rect.width - 1` cap existed to reserve a column for the caret parked
 past the last glyph, and that reservation now lives in the scroll clamp
@@ -1206,7 +1206,7 @@ exactly the width-vs-length confusion this note removes.
 - **Cache the index↔column mapping.** A single line of text is short and
   `Buffer.display_width` is memoized per grapheme, so each walk is a few hash
   reads. A cache would need invalidating on every mutation — `TextArea`'s
-  `@display_rows` hazard — for no measured gain.
+  `@wrap` hazard — for no measured gain.
 
 **Consequences.** `TextField` no longer has a maximum length by default;
 an app that wants one sets `max_text_length`. `ComboBox` and `IntegerField`
@@ -1274,7 +1274,7 @@ not just a bug fix, and it matches every editor.
 - **Iterate characters, summing per-character widths.** Gets the column totals
   right (a mark measures 0, a wide glyph 2) and is a smaller diff, but it can
   split a cluster across a row break — leaving a bare base letter on one row and
-  a mark with no base on the next, which `Buffer#set_line` drops entirely. It
+  a mark with no base on the next, which `Buffer#set_text` drops entirely. It
   also keeps termination accidental.
 - **Wait for the cluster-caret redesign and do both at once.** The redesign is
   parked, and this fix does not depend on it: the caret stays a character index
@@ -1316,7 +1316,7 @@ the slice end.
 **(2) `Buffer` could not model a cluster wider than two columns.** `put_char`
 special-cased `w == 2` and wrote exactly one continuation cell. A cluster
 measuring 4 wrote its origin, no continuations, and left the next three cells
-holding whatever was there before — while `set_line` advanced the column by 4.
+holding whatever was there before — while `set_text` advanced the column by 4.
 Stale cells plus a cursor the flush positions from a wrong model.
 
 **Decision — `emoji: :rgi`, in one named constant, at every call site.**
@@ -1946,7 +1946,7 @@ makes the orphan bug unreachable.
   question about a loud rename migration purely to convert those silent breaks
   into `NoMethodError`s. (2) `max_text_length` would silently change meaning,
   characters → clusters. (3) It adds a second invalidated cache to a class that
-  already carries one (`TextArea`'s `@display_rows`), for state a per-keystroke
+  already carries one (`TextArea`'s `@wrap`), for state a per-keystroke
   walk recomputes in 62µs.
 - **Store an `Array` of clusters instead of a `String`.** Insertion is where
   cluster-native storage bites back: typing a combining mark after `e` would
@@ -2150,7 +2150,7 @@ PasswordField pane alone — renumbered by hand whenever a prompt gained a line)
 plus hand-rolled expansion (`[inner.height - 8, 2].max`) and hand-rolled cross
 clamps (`[inner.width, 30].min`). The cost was not that hand-rolling is
 impossible but that the code newcomers read to *learn* Tuile demonstrated the
-tedious version. The port took the sampler to 7 `Rect.new`.
+tedious version. The port took the sampler to a handful of `Rect.new` (5 today).
 
 **Decision — the vocabulary is `Fixed` / `Percent` / `Expand`, and there is no
 `Auto`.** Shrink-to-fit is the bottom-up `content_size` channel deleted in
@@ -2269,11 +2269,10 @@ are ~10-line concretes. That is the sanctioned cohesive base
   is what a sidebar wants. Vaadin 8's ratio and CSS `flex-grow` both chose
   weights.
 - *`Min` / `Max` constraints:* deliberately not shipped, and the sampler shows
-  what that costs — its main split (`(width / 3).clamp(20, 40)`) and its two
-  sidebars (`min(16, width / 3)`) are caps on a *proportion*, unsayable in three
-  constraints, so they keep a rect-callback `Absolute`. That is the intended
-  division of labour: only the part needing arithmetic has any. Revisit only if
-  capped proportions turn out to be common.
+  what that costs — its two sidebars (`min(16, width / 3)`) are caps on a
+  *proportion*, unsayable in three constraints, so they keep a rect-callback
+  `Absolute`. That is the intended division of labour: only the part needing
+  arithmetic has any. Revisit only if capped proportions turn out to be common.
 - *`BorderLayout` / `BorderPane` / Textual's `dock:`:* nesting
   `Vertical(Fixed, Expand, Fixed)` covers it, and `ScreenPane` (content + status
   bar) already *is* one, hard-coded.
@@ -2564,3 +2563,1960 @@ two callers that already know the answer.
   non-focusable `Menu` really does give the same re-entrancy safety
   `ComboBox#active=` leans on, and filtering / row rendering / the commit action
   really do vary.
+
+## D-list-items — `List` takes items + a renderer, rendered lazily (2026-08-14)
+
+**Status:** Accepted; implemented 2026-08-14, with the five composers folded onto
+it in the same series. Builds on `D-has-value` (typed, not stringly),
+`D-combobox` (resolve an index, never store one), `D-float-field` (duplicate
+rather than fold a shallow commonality) and the top-down layout rule
+(`D-box-layouts`). Delivers the first half of the "typed items + data provider on
+`List`" item that gated List Box, Grid and Virtual List.
+
+**Context.** `List` took pre-rendered rows: `lines=` stored `Array<StyledString>`
+and the callbacks handed one back. Two symptoms, both of them the same missing
+seam:
+
+- Six internal call sites read `->(index, _line) { @items[index] }` — every
+  composer obeying the resolve-an-index rule *by hand*, against its own array,
+  because the framework handed back a string.
+- Four components (`ComboBox`, `Select`, `RadioGroup`, `CheckboxGroup`) kept a
+  private copy of the `@items` / `@item_label` / `label_for` / `rebuild_rows`
+  shell. `D-select` set the trigger for re-arguing a shared base at the *fourth*
+  copy; this is it.
+
+**Decision — externalize rendering on the generic component.** `List` holds
+`items` (any objects) plus a `renderer` (item → row); `on_item_chosen` and
+`on_cursor_changed` hand back the item. This is the `cop` rule the gem already
+follows elsewhere — a domain component takes data, a generic one takes strategies
+— arriving late at the one component that had grown up without it.
+
+**Not a shared base class.** The alternative reading of four duplicated shells is
+"extract `AbstractItemsComponent`". That is exactly the `parse`/`format`-hook base
+`D-float-field` rejected, one level up: it would need a render hook, a
+commit-gesture hook and a where-do-rows-live hook to span a dropdown driver and a
+row-per-item group. The duplication was a symptom of a missing *seam*, not of a
+missing *ancestor*, and adding the seam deleted the duplication that actually
+mattered while leaving each widget's own gesture policy alone.
+
+**Decision — render lazily, at paint, memoized per row.** Only the rows in the
+viewport are rendered; the cache is dropped by `items=`, `renderer=`, a width
+change or `scrollbar_visibility=`. Eager rendering (render everything in `items=`,
+keeping today's shape) was the smaller diff and was rejected on three counts:
+
+- It made `renderer=` and every width change O(all items). That cost was already
+  being paid — a 50k-row `LogWindow` re-ellipsized all 50k rows on *every*
+  terminal resize — and the lazy version deletes `@padded_lines`,
+  `rebuild_padded_lines` and the blank-row field along with it. The refactor came
+  out net *smaller*.
+- It would have forced a redesign for a lazy data provider later. Rendering
+  on demand is the half of "virtual list" that touches every method; sourcing on
+  demand can then be added behind `items` without moving anything.
+- It makes `refresh_rows` (below) cheap enough to be the *normal* answer to
+  "my rendering changed", which is what let the groups stop rebuilding rows.
+
+Two prices, both accepted and both documented in the class rdoc: **a renderer runs
+at paint time**, so it must be pure and cheap (work that reaches a service belongs
+in the item), and **search must render without memoizing** — `select_next` scans
+with the uncached path, since one failed scan over a long list would otherwise
+grow the cache to one row per item. That asymmetry is invisible in the code and
+silent under test, so it is pinned by a spec that asserts the cache is still empty
+after a failed scan.
+
+**Decision — `refresh_rows` for a renderer whose *inputs* moved.** A renderer
+closing over mutable state (`RadioGroup`'s selection, `CheckboxGroup`'s `Set`)
+produces different rows from the same items and the same proc, which no setter can
+detect. The alternatives were worse: re-assigning `content.renderer =
+content.renderer` is a ritual whose meaning isn't visible at the call site, and
+having `value=` rebuild every row is the O(n) pass this decision just deleted.
+
+**Consequences.**
+
+- **`lines=` stays, and is not deprecated.** It splits on `\n`, rstrips, and
+  stores the resulting `StyledString`s *as the items* under the default renderer —
+  so for a line-populated list "the item" is exactly what the callbacks handed
+  back before, and all 2191 pre-existing examples passed unmodified. It is the
+  honest API for a log or a static report, not a compatibility shim.
+  Reconsidered right after implementation ("shouldn't `items=` be the only
+  input?") and re-affirmed on a checkable difference: `items = ["a\nb"]` is one
+  row, `lines = ["a\nb"]` is two, and the split-plus-style-preserving-rstrip a
+  caller would have to repeat lives in two privates. Retiring it would need
+  `StyledString.parse_lines(entries)` as a public class method so the coercion
+  sits with the type — worth doing only if a second input flavor ever wants it.
+- **The appenders were removed, because they are the one thing a provider can't
+  have.** `add_item` / `add_items` / `add_line` / `add_lines` are gone. This
+  decision's second half is sourcing on demand, and the promise that it "can then
+  be added behind `items` without moving anything" is only true while every input
+  is a whole-collection assignment: `add_items` mutates `@items`, which a provider
+  that computes a window on request has nothing to mutate, so the method would
+  have had to either raise for provider-backed lists (a mode) or force the
+  provider to materialize (defeating it). Removing four methods now is cheaper
+  than either. No caller existed — in the gem, in the examples, or in the two
+  downstream apps: every surviving `add_line` is `TextView`'s, including
+  `LogWindow`'s, which is the coherent line to draw (**incremental append is a
+  `TextView` feature; a `List` is a snapshot of a collection**). The price, paid
+  knowingly: an app that tails re-assigns and so drops the row cache, re-rendering
+  a viewport's worth of rows per incoming row where an append preserved every
+  cached row. That is bounded by the viewport, not the list — the 50k-row case
+  this decision was measured against is `TextView`'s now.
+- **The naming wart around them was deleted, not deprecated for long:** the
+  `lines` **reader** and `ListDropdown#lines=` / `#lines` are gone. The reader
+  returned `items` — it could have returned the *rendered* rows instead, which
+  would have kept two specs asserting rendered text through it, but that forces a
+  full render on a getter and lies about what a list of typed items contains
+  (those specs moved to asserting what is painted, which is what they were really
+  about). The dropdown's pass-throughs had exactly one caller in the wild —
+  pikuri-tui's `SlashMenuPopup`, which pre-rendered its rows and kept `@matches`
+  beside them, i.e. the parallel array this decision exists to delete. All three
+  first shipped as a docs-only deprecation (`@deprecated` + a CHANGELOG line,
+  since a runtime notice would have to go through `Tuile.logger` — `Kernel.warn`
+  writes stderr into the frame a TUI is painting, and a logger defaulting to
+  `IO::NULL` is a notice nobody reads), then were removed *inside the same
+  unreleased 0.12.0* once both downstream apps had migrated: a deprecation
+  nobody ever consumed is dead weight in the API, and virtui's surviving
+  `build_lines` / `lines=` calls confirm the split was drawn in the right place.
+- **The block form moved to `build_lines`, keeping `lines` a plain reader.** The
+  defect was the overload — `lines` meant "read the items" or "replace them all"
+  depending on `block_given?`, which is half of why the reader read as a lie. A
+  verb name splits the two with no semantic change (virtui's two `update` paths
+  migrate by one word), and leaves `build_items` as the obvious sibling if a
+  typed-items builder is ever wanted. Deleting it outright was the alternative —
+  the body is three lines a caller can write — and was rejected because virtui
+  reads `buffer.size` mid-build to record `Cursor::Limited` positions, so the
+  buffer being a plain growing `Array` is part of the contract worth pinning with
+  a spec rather than re-deriving per app.
+- **One item is one row.** A multi-line rendering keeps its first line: a `\n`
+  reaching the buffer corrupts the frame, and any other rule (raise, split into
+  several rows) breaks the index-is-the-item identity the whole change rests on.
+- **`items=` still leaves a stale cursor alone**, and the clamp stays in the
+  caller (`RadioGroup#items=`), *before* the assignment so the single
+  `on_cursor_changed` reports the final row. Moving the clamp into `List` was
+  tempting and rejected: it would change behavior for tailing lists and would
+  break that ordering guarantee for the one component that needs it.
+- **No measuring was added.** `Select` still measures its own labels caller-side
+  and assigns the rect it computed; `List` gained no width reader. The top-down
+  re-grow rule is unchanged.
+- **`file_commander`'s `descend` was broken** and this is what surfaced it: it
+  called `Rainbow.uncolor` on the callback's second argument, which had been a
+  `StyledString` (no `#gsub`) since long before this change, so Enter on a
+  directory raised. Holding the entry hashes as items — the name separate from its
+  rendering — is the shape that makes the bug unsayable, and the PTY test now
+  presses Enter.
+
+## D-scroll-nomenclature — `row` is the grid, `line` is `\n`, `items` are domain objects (2026-08-14)
+
+**Status:** Accepted; implemented 2026-08-14. Builds on `D-list-items` (which
+made the item vocabulary real), `D-text-area-columns` and `D-text-field-axes`
+(which named the index-vs-column axes inside the inputs) and
+`D-ambiguous-width` (whose `display_width` is the column authority).
+
+**Context.** Three scrolling components had grown three vocabularies for the
+same four concepts — a content unit, a wrapped unit, a viewport-relative row,
+and the offset between the last two. `TextView` said `hard_line` /
+`physical_line` / `row_in_viewport` / `top_line`; `List` said `item` / `item` /
+`row_in_viewport` / `top_line`; `TextArea`, the newest, invented "display row"
+and was the outlier on every axis. Worse, the *foundation* disagreed with
+itself: `Buffer#row_text` said row while `Buffer#set_line` said line, in one
+class; `line_count` meant screen rows in `VerticalScrollBar.new` and `\n` units
+in `TextView::Region`; and `List::Cursor#handle_key(key, line_count,
+viewport_lines)` carried an item count and a row count in one public signature,
+calling both "lines".
+
+**Decision.** `row` is the terminal grid unit, everywhere, with no exceptions; a
+wrapped unit *is* a row, because wrapping is the operation that turns text into
+rows. `line` means exactly what `String#lines` returns and is never a
+coordinate. `items` are the domain objects a widget renders. The offset is
+`scroll_top_row`, the extent `viewport_rows`, the viewport-relative coordinate
+`row_in_viewport`. Two space rules carry the rest: an object with only one row
+space leaves `row` unqualified; a component holding both qualifies the viewport
+one. AGENTS.md's *Nomenclature* section holds the invariants, TERMINOLOGY.md the
+definitions.
+
+**The survey that decided it — and it cuts against the conclusion.** The
+*official* word for a terminal row is `line`, not `row`: ECMA-48 addresses the
+presentation component by "line position", and its scroll primitives are named
+`IL` **INSERT LINE** / `DL` **DELETE LINE** operating on screen rows; terminfo's
+capabilities are `lines`/`cols`; POSIX's env vars are `LINES`/`COLUMNS`; VT100
+documented "24 lines by 80 columns"; and Textual's `Widget.render_line(y)`
+returns a `Strip` for screen row *y*. The kernel and the modern TUI world say
+row (`struct winsize.ws_row`, `stty rows`, `crossterm::terminal::size() ->
+(columns, rows)`, and decisively `TTY::Screen.rows`, which Tuile is built on).
+**`line` is unavailable to Tuile for exactly the reason ECMA-48 never hit the
+problem: ECMA-48 has no text buffer and no word wrap.** It had one meaning for
+"line", so it took the good word. Tuile has two and must give the free word to
+one of them — `row` is free, `line` is not, because Ruby owns it.
+
+**The objection, and what actually answers it.** `row` and `line` are
+near-synonyms in English *and* in terminal usage, so a load-bearing distinction
+resting on them looked like a permanent confusion source — and the survey found
+that failure in the wild: prompt_toolkit's `WindowRenderInfo.displayed_lines` is
+documented as "List of all the visible rows" but holds **input buffer line
+numbers**. What defuses it is not picking better words but *removing the house
+convention*: `row` is the terminal's unit and `line` is Ruby's, verifiable by
+typing `"a\nb".lines` in irb. prompt_toolkit's bug was a coordinate-space mixup,
+which this scheme makes unwriteable — `line` is never a coordinate.
+
+**Alternatives rejected.**
+
+- **One noun `line`, unqualified meaning the wrapped unit** (TextView's scheme,
+  extended to TextArea). The smallest possible break, and `line_count(width)`
+  has direct ratatui precedent. Rejected: it contradicts `line` = the logical
+  unit, and in `TextArea` — one String full of `\n` — an unqualified `line` is at
+  its most ambiguous exactly where it is used most.
+- **`row` for coordinates, `line` for content, scoped to the components.** This
+  is the decision's core, but as first scoped it left `Buffer#set_line`,
+  `Component#draw_line` and `StyledString#wrap`'s "physical lines" alone — the
+  synonym confusion preserved in the foundation — and it lacked the `String#lines`
+  anchor that answers the objection above.
+- **`line` everywhere with the wrapped unit always qualified** (`physical_line_count`).
+  Zero ambiguity by construction, but verbose, and "physical line" collides with a
+  *famous opposite* usage: Python's language reference calls the raw `\n` lines
+  *physical* and the joined ones *logical* — inverted from TextView's meaning.
+  Borrowing a term with a well-known opposite reading is worse than inventing one.
+- **Drop the unit noun and name the space** (`virtual_height` / `viewport_height`
+  / `scroll_offset`, per CSS and Textual). Follows the survey's own lesson —
+  nobody disambiguates via the noun, everybody qualifies the space — and has no
+  Tuile collision. Rejected because it names *extents*, not *positions*, and a
+  `Component`-level `virtual_height` seam edges toward the bottom-up sizing
+  channel deleted in 0.9.0.
+- **`Buffer#set_row` / `Component#draw_row`,** for parallelism with the reader
+  `row_text`. Rejected for `set_text` / `draw_text`: these write a
+  {Tuile::StyledString} *starting at* `(x, y)` and do not fill the row, so
+  `set_row` would be a new inaccuracy introduced by a cleanup whose point is to
+  stop using row-words loosely. Naming no row is not an exception to "row
+  everywhere".
+- **`List#items` → `List#rows`,** which a List item arguably is. Rejected:
+  `items` is where `cop` wants the domain-object noun (`D-list-items` had just
+  landed it), and it is the word the enum widgets above `List` already use.
+- **`scroll_top`** (CSS's `scrollTop`, shorter). Rejected for `scroll_top_row`:
+  it names no unit, and `list.scroll_top` reads as an imperative — *scroll to
+  top* — which a getter must not.
+- **A general `Component` scroll seam.** `scroll_top_row` stays per-component; a
+  framework-consulted seam is the 0.9.0 re-grow rule's tripwire.
+
+**Consequences.**
+
+- **`item_count`, not `row_count`, on `List::Cursor`** — the two are numerically
+  equal in a `List`, but a cursor's `position` indexes *items*
+  (`on_item_chosen` resolves it against `items`, and a `Cursor::Limited`'s
+  allowed positions are item indices). The one place the identity is legitimately
+  used is the scrollbar call, which is screen-space and says
+  `row_count: @items.size`. Same number, two names, each right in its own space.
+- **Every surviving `line` symbol takes or returns `\n`-delimited text** —
+  `List#lines=`, `#build_lines`, `TextView#add_line`, `Region#line_count`,
+  `StyledString#lines`, `InfoWindow.new(caption, lines)`. That is the property to
+  check a future rename against, and it is why `Buffer#set_line` had to go.
+- **`spec/tuile/nomenclature_spec.rb` guards it with no allowlist.** A grep
+  enforces words that are *always* wrong; `line_count` is deliberately absent,
+  since `Region#line_count` is correct. A word that is right in one space and
+  wrong in another is the glossary's job — that limit is accepted, not a gap to
+  close later, and a rename needing an allowlist entry is evidence the rename is
+  wrong.
+- **`row_count` was reserved here, then created separately.** Making it a public
+  reader was held to be a behavioural addition needing its own argument; that
+  argument is `D-text-area-rows`, which granted it on `TextArea` only. The point
+  this entry settled — that the *name* is already taken, so the addition need not
+  re-litigate its spelling — held.
+- **`CHANGELOG.md` was not swept.** Its 0.4.0 entry announcing the `set_line` /
+  `fill` / `set_char` buffer API stays as written: the changelog is append-only
+  and describes what shipped *then*, so retro-editing it would make a released
+  migration note reference a method that release did not have.
+
+## D-text-area-rows — `TextArea#caret_row` / `#row_count`, not a hook and not the wrap (2026-08-15)
+
+**Status:** Accepted; implemented 2026-08-15. Grants the reader
+`D-scroll-nomenclature` reserved the name for. Answers
+[#3](https://github.com/mvysny/tuile/issues/3).
+
+**Context.** Shell-style prompt-history recall in a `TextArea`: Up recalls the
+previous message, Down the next — but only once the caret has nowhere left to go
+that way, so Up/Down keep moving the caret inside wrapped text and only *leave*
+the buffer at its edge. That needs one question answered — **is the caret in the
+first / last row?** — and half of it was already public (`scroll_top_row` plus
+`cursor_position`), while the row *count* lived only on the private
+`WrappedText`. Meanwhile `move_caret_vertical` already computes exactly that
+condition (`new_row == cur_row` after a clamp) and already has an opinion about
+it: it snaps to the absolute start/end of the text.
+
+**Decision — two public readers on `TextArea`, forwarding to the private wrap.**
+`caret_row` and `row_count`, one line each. The caller claims the key in a seam
+that already exists — `handle_text_input_key` in a subclass, or the `on_key`
+interceptor for app code that would rather not subclass — and delegates to
+`super` everywhere else, which leaves the edge snap intact for anyone who
+doesn't claim it. The recipe lives in the `TextArea` rdoc.
+
+Both readers are needed and neither is redundant: history recall uses both, and
+the auto-growing prompt strip — the case the name was reserved for — uses
+`row_count` alone to size the strip top-down.
+
+**Alternatives rejected.**
+
+- **A protected `on_caret_vertical_overflow(delta)` hook**, consulted inside
+  `move_caret_vertical` before the snap. This was the issue's own preferred
+  shape, on the grounds that it avoids re-deriving a decision `TextArea` already
+  makes. Rejected on five counts. It would be a *fourth* key-interception
+  mechanism in a class that already has three (`on_key`,
+  `handle_text_input_key`, the rung-3 ancestor bubble), where the house style is
+  "claim the key, or decline it". It names an implementation *moment* rather than
+  an event — one point inside a private method, after a clamp — so a later branch
+  in the Up path (desired-column memory, say) would shift its firing condition
+  silently under every subclass, where `caret_row == 0` cannot drift. It points
+  the arrow the wrong way: a hook is the framework consulting the app, and the
+  0.9.0 layout re-grow rule explicitly sanctions the opposite — capability
+  returning as "an *optional, read-only, caller-side query* … never as an
+  automatic channel the framework consults" — which is also why
+  `D-scroll-nomenclature` rejected a general `Component` scroll seam. It serves
+  one question, in one direction, at one moment, where the readers also serve the
+  prompt strip, a "row 3/7" readout and a caller-drawn scrollbar. And it needs a
+  subclass, where the readers serve `on_key` too. In COP terms it is neither a
+  listener (nothing changed) nor a provider (no data pulled) — a template-method
+  escape valve where two COP-shaped seams already exist. As for the
+  re-derivation it was meant to avoid: the decision is literally
+  `caret_row == 0` / `caret_row == row_count - 1`, so there is nothing to
+  re-derive but a `- 1`.
+- **Publish `wrap` / `WrappedText` itself**, exposing the object that does the
+  arithmetic rather than forwarding its methods one at a time. Tempting: it looks
+  like it belongs in the published value-type family (`Point`, `Size`, `Rect`,
+  `Color`, `StyledString`, `Fraction`), and it caps delegation at one method
+  forever where readers grow one forwarder per question. Rejected on four counts.
+  **(1) Value versus cache handle** — `Rect` is safe to publish because it is
+  immutable *and* authoritative, with no truer copy that drifts; `@wrap` is a
+  lazy cache nilled by `on_text_mutated` and `on_width_changed`, so a held
+  reference goes *silently* stale, answering confidently about text the widget no
+  longer holds, and never raising. The natural place for a subclass to hold it is
+  an ivar — exactly the shape the "never cache a theme value in an ivar" and
+  `effective_bg_color` rules already forbid. Documenting "always call it fresh"
+  reduces the only safe usage to `area.wrap.row_at(area.caret)`, a longer
+  spelling of `caret_row` with a foot-gun attached. **(2) It blesses the very
+  coupling the issue objected to** — the stated complaint about reaching into
+  privates was the coupling to the wrap's shape; publishing it makes that
+  coupling permanent, putting `WrappedText` into `sig/tuile.rbs` and rubydoc and
+  turning any future change to how `TextArea` wraps into a breaking one.
+  **(3) Tell, don't ask** — `area.wrap.row_at(area.caret)` has the caller reading
+  two public bits and doing the component's arithmetic with its borrowed engine,
+  responsible for keeping them consistent. **(4) It flips a written invariant for
+  no argued caller** — AGENTS.md holds the class private "until a second caller
+  actually exists", and nobody has asked for `row_text` / `index_at` from
+  outside. Forwarders grow on demand at one line each; `D-float-field`'s
+  temperament ("a fourth copy is when to re-argue it") applies.
+- **A `wrapped_text` method documented "do not store".** Same staleness, renamed.
+- **A validity token on `WrappedText`,** so a holder can detect a stale snapshot.
+  Cache-invalidation protocol in public API, to fix a problem created by
+  publishing the cache.
+- **`caret_at_first_row?` / `caret_at_last_row?` predicates** instead of raw
+  readers. Reads better at the call site and removes the `- 1`, but `row_count`
+  is still needed for the prompt-strip case, making it three methods to the
+  readers' two while covering less.
+
+**Consequences.**
+
+- **`TextArea` only.** `TextView` and `List` share the reserved name and have no
+  argued caller; adding them now would be speculative. A future caller argues its
+  own case, and the spelling is settled either way.
+- **The edge snap is now a documented default, not just behavior.** A subclass
+  that claims one direction and delegates the other keeps the snap on the
+  unclaimed side — pinned by a spec, since it is the part a reader of the recipe
+  would assume rather than check.
+- **`caret_row` and `row_count` read the wrap live**, never a stored value —
+  which is the whole reason the object stays private. Specs pin that both track a
+  text change and a width change.
+
+## D-text-view-scroll-verbs — `TextView#scroll_half_page_up` / `#scroll_half_page_down` (2026-08-15)
+
+**Status:** Accepted; implemented 2026-08-15. Amended 2026-08-23: the
+`active?` guard this was originally argued *from* turned out to be dead code
+(see the correction at the end) — the decision stands on its other grounds.
+
+**Context.** A chat TUI keeps focus in the input field beneath its transcript,
+so the transcript's own scroll keys never fire: dispatch delivers a key along
+the focus chain only, and the view is not on it. The host wants PageUp/PageDown
+at the *prompt* to page the *view*, half a screen at a time so the reader keeps
+an overlap while output streams in. `TextView` already knows how to do exactly
+that — `Ctrl+U` / `Ctrl+D` have scrolled by half a viewport since the scroll
+ladder landed — but every clamped primitive behind those bindings
+(`move_scroll_top_row_by`, `move_scroll_top_row_to`, `viewport_rows`,
+`scroll_top_row_max`) is private, and the one public setter is not a safe
+substitute (see the alternatives).
+
+**Decision — two public verbs, and the key bindings route through them.**
+`scroll_half_page_up` and `scroll_half_page_down`, one line each, delegating to
+the private movers; the `Ctrl+U` / `Ctrl+D` cases in `handle_key` now call the
+verbs rather than repeating the arithmetic, so key and API cannot drift apart.
+Half a page is `viewport_rows / 2` floored at one row. The host's question is
+"scroll this view half a page", and that is exactly the granularity exposed —
+it never learns the row count, never clamps, and never touches focus.
+
+**Alternatives rejected.**
+
+- **Publish `move_scroll_top_row_by` + `viewport_rows` and let the app halve.**
+  Moves the definition of "half a page" out of the widget and into every app
+  that wants it, where the two spellings drift. `TERMINOLOGY.md` also pins
+  `viewport_rows` private on purpose — `rect.height` is its public form.
+- **Let the host forward a synthetic key** (`view.handle_key(Keys::CTRL_U)`).
+  A keystroke aimed at an unfocused widget is a lie about where focus is: the
+  host's question is "scroll this view", and spelling it as a key makes the
+  view's key bindings part of its API — rename `Ctrl+U` and the caller breaks.
+  (At the time this was also *dead on arrival*, the guard rejecting it; that
+  guard is gone and the forward would now work. It is still the wrong spelling.)
+- **App-side arithmetic on the existing public `scroll_top_row=`.** It raises
+  below `0` and is deliberately *not* clamped above, so a caller who overshoots
+  the last row leaves `at_bottom?` false and silently kills `auto_scroll`
+  tailing — the exact bug a transcript pane cannot afford.
+- **Redefine PageUp/PageDown as half-page moves in `TextView`.** A key named
+  "Page" should page, it would break `Ctrl+U`/`Ctrl+D`'s reason to exist, and it
+  fixes nothing anyway: an unfocused view still sees no keys.
+- **Ship the whole ladder as verbs** (full page, top, bottom, by-row). No caller
+  yet; `D-text-area-rows`'s temperament applies — a future caller argues its own
+  case, and these two settle the spelling for the rest.
+
+**Consequences.**
+
+- **The floor at one row is a behavior change to `Ctrl+D` / `Ctrl+U`** in a
+  one-row viewport, where `1 / 2 == 0` used to make both keys silent no-ops.
+  A public verb that does nothing is worse than a key that does nothing, and the
+  fix is the same line for both.
+- **Verbs return `void`, not "did it move?"** — consistent with the movers they
+  wrap. A caller wanting the answer reads `scroll_top_row` or `following?`; one
+  claiming a key should claim it unconditionally, since a clamped scroll at the
+  edge is still a handled key (`handle_key` has always returned `true` there).
+- **`following?` still does the tailing bookkeeping**: paging up un-arms it,
+  paging back to the last row re-arms it. The host gets read-while-streaming for
+  free and has nothing to wire.
+
+**The correction (2026-08-23).** `TextView#handle_key`'s opening
+`return false unless active?` was **vestigial**, and this entry took it for a
+live constraint. It was a leaf backstop for the one place the pre-0.8 framework
+over-delivered (`ScreenPane` forwarding to `content` unconditionally); e1777fe
+centralized dispatch and dropped the same guard from `TextInput`, `List` and
+`Button` — but `text_view.rb`, three weeks old at the time, was missed. It could
+never fire once removed from that context: `bubble_key` walks `Screen#focused`
+upward and `focused=` marks that chain `active`, and a `TextView` is a leaf, so
+the only chain position it can hold is `focused` itself. The stale
+`return true if super` above the `case` went with it — `Component#handle_key`
+has collapsed to `false` since the same commit. Both lines are deleted; the
+widget now obeys the framework-wide rule (AGENTS.md, book ch5) that a
+`handle_key` acts on the key alone. The *visible* change is that hand-feeding a
+key to an unfocused view now scrolls it, which is what every other widget in the
+gem already did (`examples/sampler.rb`'s unfocused `List` is the house idiom).
+
+## D-notification — One corner toast, N messages, one ticker draining them (2026-08-17)
+
+**Status:** Accepted and implemented, `Component::Notification`. Builds on
+`D-attach-hooks` (the synced-from-an-invariant ticker), `D-color-slots` (the
+per-message color), and Tier 1 of the component survey. Book ch7 "Notifications"
+is the user-facing half; the rdoc owns the per-symbol contract. What this entry
+owns is *why each choice*, and the alternatives that looked right first.
+
+**Context.** Vaadin's `Notification`, on a TTY. The requirements that shape
+everything: it must not interrupt (no focus, no keys, no click blocking), it must
+be raisable from one line of app code, and *several* may be raised at once — a
+batch job reporting five results, a burst of failures.
+
+### One box, N entries — not a stack of boxes
+
+Two toasts would need placement arithmetic (each box's `top` depends on the
+heights of those above it) and every expiry would reflow the rest: a layout
+system for a widget nobody asked to lay out. One box with N entries costs a
+`"\n"`. So `Notification.show` **finds the live notification and appends to it**.
+
+### Expiry: one repeating ticker over a deque, not a timer per message
+
+The first formulation was "the second message's 3 s starts when the first
+disappears", which implies per-message deadline arithmetic (when does #4's clock
+start? what if #2 is dismissed early?). It collapses to something with no
+arithmetic at all: **one repeating `tick(3.0)`; each firing retires the oldest;
+the box closes when the last one goes.** Identical behavior, and it makes the
+non-obvious rule explicit:
+
+- **The ticker is never restarted when a message arrives.** Restarting would
+  extend the oldest message's life on every append, so a stream arriving every
+  2.5 s would retire nothing and the box would live forever. The early return in
+  `sync_ticker` is what enforces it, and `notification_spec` pins the ticker's
+  *identity* across an append.
+- A message arriving 2.9 s into a cycle is not short-changed: it is retired only
+  once it becomes the oldest *and* a full tick elapses, so its visible lifetime
+  is ≥ 3 s and the bottom entry of a full box lives ~3·N seconds. That is the
+  property the staggering was reaching for — the box lingers exactly as long as
+  there is something left to read.
+
+Independent timers were the rejected alternative and are worse in the case that
+motivated the widget: five raised in the same instant would appear *and vanish*
+together, a flash nobody can read.
+
+### The cap is 5 messages, from reading time — and overflow goes to the log
+
+The drain rate is fixed at one message per `DISPLAY_SECONDS`, so **the queue
+length is a duration**: 20 pending messages is a full minute of toast, and the
+failure mode a cap must prevent is an app bug (a loop notifying per iteration)
+turning the box into a permanent fixture. 5 × 3 s ≈ 15 s is about the longest a
+corner box should own the screen, and about as many short lines as anyone reads.
+The two numbers agreeing is the reason to trust the bound.
+
+Consequence: **the pending queue is a short-terminal accommodation, not a
+feature.** With ≤3-row messages the 40 % height cap only binds below ~20 rows; on
+any normal terminal all five fit, nothing ever waits, and the concept is
+invisible. Overflow drops the **newest** (in an error storm the first messages are
+the diagnostic ones, the rest is cascade noise — and it never reorders) and warns
+via `Tuile.logger`, the gem's first internal log write.
+
+- **Rejected: a `… and N more` tail**, first sketched as `Window#footer_text`
+  (border chrome, so it costs no row and skips expiry — elegant machinery, which
+  is a bad reason to put something on screen). It fails on *meaning*: the count is
+  cumulative while the list shrinks, so it reads as a promise — "3 more are
+  coming" — that is never kept, and one message beside `+3 more` is that promise
+  at its most absurd. And when it fires the user is already looking at a full box
+  with nothing to act on: no way to retrieve a dropped message, nothing to click.
+  Information with no action. The party who *can* act is the app author, so the
+  report goes to the log, where it says "use a `LogWindow`".
+- **If it is ever revived**, the fix is *not* "hide while fewer than `MAX` are
+  showing": that resurrects the counter (8 arrive → 5 + `+3`; a tick hides it; one
+  new message refills the box → `+3` reappears though nothing was just dropped).
+  Zero the counter on every tick instead — self-clearing, no resurrection, and the
+  claim becomes honest ("3 dropped in the last 3 seconds").
+- **Deferred, not rejected:** coalescing identical messages into `"Sync failed
+  ×47"`. `StyledString` has structural equality so it is cheap, and it handles a
+  storm better than any cap — but it is a second mechanism against the same
+  problem. Build it if the storm case proves real.
+
+### `show` is the only door: `new` is private
+
+The class has no correct standalone use — `reposition` derives its rect from the
+screen corner, so a second instance lands on *exactly* the same rect and the two
+overdraw each other with no error. `show`'s find-or-create is the only thing that
+makes "at most one" true.
+
+- `TextView::Region` already establishes the idiom (`private_class_method :new`
+  plus a "don't construct these directly" rdoc line), so this is its second use.
+- The usual objection — that a private constructor forces every knob through the
+  factory — dissolves here: **`color:` is a property of the message, not of the
+  box** (one box holds an error line and an info line), and duration / caps /
+  corner are constants. The whole surface is `show(text, color: nil)`.
+- Corollary for a future factory: `self.show` calls bare `new`, never
+  `Notification.new`, so a subclass's `show` builds the subclass.
+- This widget is what surfaced `Popup.self.open` as a subclass trap (it had to be
+  privatized here too, until the factory was deleted outright — `D-popup-open`).
+
+### The singleton lives in the popups stack, never in a class ivar
+
+`show` finds it with `Screen.instance.pane.popups.find { _1.is_a?(Notification) }`.
+A `@@current` would be **process**-global while the notification is
+*screen*-global: it would survive `Screen.close` and leak a detached popup into
+the next `Screen.fake`. Clearing it would mean either `Screen#close` knowing about
+a component (dependencies point toward data, never toward UI) or a
+component-specific reset hook nothing else needs. The popups stack is already the
+single source of truth for "what overlays are up" and `ScreenPane#detach_all`
+empties it on close — the same "readers *over* the array, never a second copy"
+rule the tree API rests on. Cost is an `is_a?` scan of a 0–3 element array.
+
+### Flush to the corner — both axes, one reason
+
+`top = 0`, right edge at the last column, no margin and no knob. Against a
+full-screen framed app the toast's top and right borders land **coincident** with
+the window's, so its corner replaces the window's corner and nothing doubles;
+what you see is a box hanging off the top border, the toast's `┌` interrupting the
+window's `─`. Verified in the sampler at 100×30.
+
+**A 1×1 margin is the disease, not the cure** — it is what puts two parallel rules
+one cell apart (toast right border at `W-2` beside the window's at `W-1`, toast
+top on row 1 below the window's on row 0). This also settles the vertical question
+("should `top` clear a content title bar?"), which was never independent: same
+argument, same answer. The one case wanting `top: 1` is an app whose row 0 is a
+*title bar* rather than a border — but then there is nothing to double, and the
+framework cannot see which it is. That is the `anchor:`/`margin:` knob, deferred
+until an app complains.
+
+### Width is grow-only; a content floor is not needed
+
+The box widens to fit a new message and never shrinks while it lives: **width is a
+property of the burst, not of the current message.** A high-water mark in
+*desired* columns, with the cap applied last.
+
+- **Rejected: recompute freely.** On a 160-column terminal `"Saved"` is a
+  7-column box at `x = 153`; a 31-column message jumps the left edge 24 columns
+  left; three seconds later `"Saved"` retires and it jumps back. Every breath
+  re-wraps and repaints every visible message *and* moves the rect, which makes
+  `Popup#rect=` escalate to a full-scene repaint. Simultaneously the ugliest and
+  the most expensive option.
+- **Rejected: fixed at the cap.** A 64×3 box holding `"Saved"` with 58 blank
+  columns reads as a rendering bug. It works for macOS/GNOME toasts because
+  padding, shadows and icons fill the space; a TTY box has nothing.
+- **The clamp must not be stored in the mark.** If `@high_water` held the clamped
+  value, a SIGWINCH that narrows the terminal would ratchet the box permanently
+  down to the narrow cap with nothing to restore it on widening.
+- `MIN_CAP_WIDTH = 34` floors the *cap* (40 % of an 80-column terminal is 32
+  columns — about five words before the ellipsis). That is a different knob from a
+  **content** floor, which was considered and dropped: the sampler shows a
+  7-column `┌─────┐` / `│Saved│` reading as a proper small toast, not a glyph.
+
+### A click dismisses the whole box
+
+Not "one message per click". The box covers the corner where a
+`VerticalScrollBar` renders and header widgets sit, so **the stray click is the
+common click** — the user is aiming at something underneath. Whole-box dismissal
+clears the obstruction in one click; per-message would leave the widget covered
+and demand up to five. Gated on `:left`, because `MouseEvent` also carries
+`:scroll_up`/`:scroll_down` and a wheel spin must not nuke the box.
+
+**Accepted wart:** a wheel spin over the toast is swallowed, so the list beneath
+does not scroll. No fix stays inside the widget — falling through would mean
+`ScreenPane#handle_mouse` re-running its search past the toast (a framework change
+for one widget), and having the toast re-route into `screen.pane.content` itself
+is a component reaching sideways across the tree. It lives ≤15 s.
+
+### Content: a `TextView`, rebuilt wholesale — `Region` per message was dropped
+
+The expiry unit is a **message**, not a row (eating a 3-row message one row per
+tick is not a thing any UI does), which rules out `Component::List` — one item is
+one row there, so a list cannot hold a wrapped message.
+
+The design called for one `TextView::Region` per message, retired with
+`region.text = nil`. **Implementation dropped the regions** and rebuilds the
+view's text on every change instead, for two reasons found while writing it:
+
+1. **Regions are unremovable.** Only `TextView#text=` clears them, so a
+   long-lived box (a trickle of messages that never lets it empty) would
+   accumulate one dead region per message forever — and `region_start_index` sums
+   the line counts of every preceding region, so the per-append cost grows with
+   the number of *retired* messages.
+2. **A rebuild is what a width change needs anyway.** Grow-only width and SIGWINCH
+   both change the wrap width, so every message must be re-wrapped and
+   re-ellipsized regardless. With ≤5 short messages that is trivially cheap, and
+   it makes size, wrap, position and text one computation in `reposition` — which
+   is why every mutation routes through there.
+
+`TextView` still earns its place: pre-wrapped rows go in as hard lines (so its
+own wrap is a no-op over them), and it supplies the painting, the blank-row
+padding, the bg inheritance and the viewport clipping that makes an over-tall
+queue simply wait, unpainted, with no visible/pending bookkeeping at all.
+
+### Two traps this widget is the first to hit
+
+Both are framework-level and belong to *any* future non-modal popup; AGENTS.md
+carries them as invariants and the specs pin them.
+
+1. **A click on a non-modal popup kills the keyboard.** `Popup#focusable?` is
+   `true` and `ScreenPane#handle_mouse` routes an in-rect click to the popup,
+   which reaches `Component#handle_mouse`'s `screen.focused = self`. Focus is then
+   inside a subtree that is *not* the key scope (`modal_popup || content`), so
+   `bubble_key` delivers to nobody and every keystroke goes dead until Tab
+   recovers. `ListDropdown` dodges it by being `focusable? = false`; a
+   notification must also override `handle_mouse`, since being unfocusable alone
+   only makes the click a silent no-op.
+2. **`Popup#reposition` strands a derived position.** For a non-modal popup it
+   re-resolves the size but keeps the caller-assigned `rect.left` — correct for an
+   overlay someone placed by hand, wrong for a corner anchor, which is off-screen
+   entirely after the terminal narrows.
+
+**The `Popover` extraction still waits.** A screen-corner anchor is arguably the
+second *kind* of anchoring that would unlock it (per the component survey), but
+`Notification` ships its own `reposition` first so the extraction is judged with
+two real implementations rather than one and a guess.
+
+## D-popup-open — No class-level `Popup.open` factory; `#open` returns `self` (2026-08-17)
+
+**Status:** Accepted and implemented; `Component::Popup.open` **removed**, and
+`Popup#open` now returns `self`. Surfaced while building
+{Tuile::Component::Notification} (`D-notification`), which had to privatize the
+inherited factory to stop it undermining a private constructor.
+
+**Context.** `Popup.open(content:, modal:, size:)` was one-line sugar for
+`Popup.new(...).tap(&:open)`. It hardcoded `Popup.new`, so **every subclass
+inherited a factory that silently built the wrong class**:
+`ListDropdown.open(...)` and `Notification.open(...)` each returned a bare
+`Popup` — no dropdown behavior, no message, no ticker, and no error to say so.
+
+**Decision — delete it, and there is no fixed version to keep.** The obvious
+repair is late binding (`new(...)` instead of `Popup.new(...)`), and it does not
+work: a subclass's constructor takes different parameters — `ListDropdown.new`
+takes its list, `Notification.new` takes nothing and is *private* — so there is
+no argument list a base-class factory could forward. A factory that can be
+inherited neither correctly nor safely should not exist. (Privatizing it per
+subclass, which `Notification` did first, treats the symptom once per subclass
+and leaves the trap armed for the next one; and it barely works — a private
+method is still callable with an implicit receiver, so a *late-bound*
+`Popup.open` would have cheerfully built a second `Notification` from inside the
+inherited method.)
+
+**Decision — `#open` returns `self`, which is what makes the deletion free.**
+The migration is `Popup.new(content: window).open`, one expression, no `.tap`:
+
+```ruby
+popup = Component::Popup.new(content: window, size: Fraction::FULL).open
+```
+
+The previous return value was undocumented junk (whatever `Screen#add_popup`
+happened to hand back), so nothing could depend on it. Both internal callers got
+*shorter*: `InfoWindow.open` is now a single line, and `PickerWindow.open` drops
+its trailing bare `popup` — and that method is the standing demonstration that
+the deleted factory could never have served the general case anyway, since it
+needs the popup *before* mounting it in order to wire `on_pick`.
+
+**Not extended to the batteries-included windows.** `InfoWindow.open` and
+`PickerWindow.open` stay: each names its own class explicitly, takes that class's
+own arguments, and wraps the popup rather than *being* one — none of them is an
+inherited factory, so the trap does not apply. `popup_spec` asserts that neither
+`Popup` nor `ListDropdown` responds to `open` at the class level.
+
+## D-bracketed-paste — A paste is its own event, not a burst of keys (2026-08-23)
+
+**Status:** Accepted and implemented in `Keys` (`BRACKETED_PASTE_ON`,
+`PASTE_START`, `read_paste`, `normalize_paste`), `EventQueue::PasteEvent`,
+`Screen#run_event_loop(bracketed_paste:)`, `ScreenPane#handle_paste`,
+`Component#handle_paste`, `AbstractStringField#handle_paste`, and
+`FakeScreen#paste`. Reported as
+[issue #4](https://github.com/mvysny/tuile/issues/4).
+
+**Context — the two bytes are the same byte.** Pressing Return in raw mode sends
+`\r`. Pasting into a terminal that has *not* been told the app can tell a paste
+apart also sends `\r` for every clipboard line break: xterm, VTE and tmux all
+rewrite the selection's `\n` on the way out, deliberately, so that a paste looks
+exactly like typing (tmux's `paste-buffer -r` exists to opt out of it). So a
+{Tuile::Component::TextArea} subclass that rebinds ENTER to submit — the
+chat-prompt shape — submitted **once per pasted line**, and the first line was
+gone before the second arrived.
+
+Nothing downstream can repair that. By the time `handle_key("\r")` runs, "the
+user pressed Enter" and "the clipboard held a line break" are the same event.
+The only downstream lever is inter-keystroke timing, which `D-select` already
+rejected for type-ahead on exactly this ground: a terminal degrades that signal
+(bytes in one read burst merge into a single key) and a paste has no gaps at all.
+The information exists only at the layer that talks to the terminal, which is
+Tuile's.
+
+**Decision — drive DEC private mode 2004, on by default.** `run_event_loop`
+prints `\e[?2004h` alongside the mode-2031 notify and `\e[?2004l` in the same
+`ensure`, and takes `bracketed_paste: false` to opt out, mirroring
+`capture_mouse:`. Terminals that don't know the mode ignore the sequence, so
+there is no capability probe and nothing to detect — which is what makes
+defaulting it *on* safe rather than a gamble. The off switch exists for the same
+reason `capture_mouse: false` does: a terminal that mishandles the mode, and a
+one-flag escape beats a fork of the loop.
+
+**Decision — the payload is read raw, not through `Keys.getkey`.** `getkey`
+returns `\e[200~` cleanly (its 5-byte tail gulp fits the marker exactly), but the
+*content* must not go back through it: a pasted `\e` would send it gulping five
+bytes of clipboard as an escape tail and surfacing them as phantom keypresses —
+the failure the `\e[M` and `\e[?` drains already exist to prevent. So
+`Keys.read_paste` reads **one byte at a time** to the `\e[201~` terminator.
+One byte at a time, and not a chunked read, because a chunk would over-read past
+the terminator and swallow whatever the user typed behind the paste; there is
+deliberately no pushback buffer in `Keys` to make chunking safe. A paste is
+human-scale and arrives once, so the syscall count is not worth a second
+mechanism.
+
+**Decision — a `PasteEvent`, and it never touches the key ladder.** The key
+thread posts one event carrying the whole payload; `Screen#event_loop` routes it
+to `handle_paste` down the focus chain, with the same modal scoping as a key and
+no other rung. *Rejected: reusing `KeyEvent` with a flag*, which would put a
+`pasted?` predicate on the ladder and re-create the runtime gate `D-key-dispatch`
+deleted — every `handle_key` would have to remember to check it, and the ones
+that forgot would be exactly today's bug. *Rejected: replaying an unhandled paste
+as individual keys.* It reads like graceful degradation and is the ambiguity
+walking back in through the fallback: a component that declines a paste would
+still get eight ENTERs. Unhandled text is dropped.
+
+**Decision — the field inserts it as one mutation.**
+`AbstractStringField#handle_paste` inserts at the caret in a single `text=`, so
+`on_change` fires once for the paste rather than once per character. That is what
+lets a submit-on-Enter subclass need *no* paste code at all — it keeps
+`handle_key` for the typed ENTER and inherits paste-inserts-text — and it
+incidentally retires an O(n) re-render and, for a slash-command overlay, an O(n)
+re-filter.
+
+**Where each layer sanitizes, and why the line is there.** `Keys.normalize_paste`
+fixes only what is a *terminal* artifact: `\r`/`\r\n` → `\n` (terminals disagree
+about which they send inside the brackets — readline carries its own `\r`→`\n`
+pass for precisely that reason, so this cannot be left to the caller), and an
+invalid-UTF-8 scrub so a pasted binary file cannot make a downstream
+grapheme-cluster walk raise. Control characters are *content* and survive that
+layer. What a **text buffer** may hold is the field's call:
+`AbstractStringField#preprocess_paste` drops the C0 controls (a raw `\e` or `\t`
+reaching {Tuile::Buffer} would move the real cursor mid-frame), keeps `\n`, and
+turns a tab into one space rather than inventing a tab width;
+`TextField#preprocess_paste` narrows further — newlines to spaces, since a
+one-row field holds no line break, and a trim to `max_text_length` rather than a
+rejection, because that is what typing the same characters would have done. An
+app wanting tab *expansion* or a `[Pasted 230 lines]` placeholder overrides
+`handle_paste`, which is the seam that exists for it.
+
+**Testing is three layers, because no one of them covers the others.**
+`FakeScreen#paste` (normalize + dispatch) is the unit door and starts one layer
+above the terminal; the sampler's *Paste* pane is the visual demo; and one PTY
+example in `spec/examples/sampler_spec.rb` is the only place mode 2004, the
+marker recognition and `read_paste` run for real. That PTY test writes the whole
+`\e[200~…\e[201~` sequence as **one burst**, which is the one place AGENTS.md's
+pace-the-keys rule is deliberately inverted: a real paste *is* a gapless burst,
+and the payload is drained raw, so nothing in it can be mistaken for a key. Its
+assertions read newly painted log rows rather than the counter row, because the
+buffer flushes the minimal diff — `rows in draft: 1` becoming `…: 3` puts one
+character on the wire, not the phrase.
+
+**Corrected while here.** `TextArea`'s rdoc claimed a pasted line break arrived
+as `\n` and a typed one as `\r`, which is backwards and read as though multi-line
+paste already worked. Accepting {Keys::CTRL_J} is still right, but its
+justification is now the honest one: that is the byte a *typed* Ctrl+J sends.
+
+## D-repaint-cascade — the repaint cascade skips the clear, never the invalidate (2026-08-23)
+
+**Status:** Accepted and implemented in {Tuile::Component#repaint}. Found while
+building {Tuile::Component::TabSheet}, but the bug predates it and was already
+visible in three shipped sampler panes.
+
+**Context — the symptom.** Focus the sampler's *TabSheet* pane and press Tab to
+put focus on the strip: the pane below it vanishes. It is still there — Tab once
+more and it comes back — so nothing was detached; the cells were simply blanked
+and never repainted. The same fault, less dramatically, blanked four rows of the
+*Checkbox*, *CheckboxGroup* and *RadioGroup* panes whenever focus moved into
+them. A sweep comparing each pane's incremental repaint against a
+repaint-everything baseline is what found the other three.
+
+**The mechanism, in one chain.** A focus change invalidates every component
+whose `active?` flipped — i.e. the whole new focus chain. One of those is a
+`Layout::Vertical(spacing: 1)`, whose children leave gaps, so the default
+{Tuile::Component#repaint} runs `clear_background` over **its whole rect** —
+which is every descendant's cells, not just the gaps — and then re-invalidates
+its *direct children*. That notice then has to travel the rest of the way down,
+and it didn't: the old default opened with
+
+    return if children.any? && children_tile_rect?
+
+so a container whose children tile it perfectly painted nothing **and
+re-invalidated nothing**. A `TabSheet` (strip on row 0, pane below, exactly
+tiling) is such a container, and so is a `Layout` whose slot happens to fit its
+children. The cascade dead-ended there, the grandchildren never learned their
+cells had been wiped, and the blank stayed until some unrelated event invalidated
+them again. Nothing in the code says "this must forward", and no test went red —
+the invalidation set and the buffer were both self-consistent.
+
+**Decision.** Make the *clear* conditional and the *invalidate* unconditional:
+
+    clear_background unless children.any? && children_tile_rect?
+    children.each { |c| screen.invalidate(c) }
+
+A container that paints nothing of its own can only redraw its area *through* its
+children, so being invalidated has to mean invalidating them. The tiling test
+keeps doing the one job it is good for — deciding whether there is a gap worth
+blanking, which is what `D-progress-bar`'s "never blank a cell you are about to
+paint over" cares about.
+
+**Why the extra invalidation is not a cost.** It is a repaint of a subtree that
+was about to be wrong, and it reaches the terminal only if it changes something:
+`Buffer::Cell#set` flips the dirty flag on a real content change alone, so
+repainting identical glyphs emits nothing. The wire stays minimal; only CPU
+moves, and only on the frames where an ancestor cleared.
+
+**Roads not taken.**
+
+- **Clear only the gaps instead of the whole rect.** Strictly better in
+  principle — no descendant's cells would be destroyed, so no cascade would be
+  needed at all — but it means real rect-subtraction geometry (n children, holes,
+  overlap) in the hottest path in the framework, to replace one `fill`. The
+  cascade fix is three lines and needs no new geometry. Revisit only if clearing
+  ever shows up in a profile.
+- **Fix it in `TabSheet` alone** (invalidate the strip and pane from its own
+  `repaint`). Rejected on evidence: the sweep proves three other panes already
+  had the bug, so the fault is the framework default, not the new component. A
+  local fix would have left the trap armed for the next container that happens to
+  tile.
+- **Make the clearing container invalidate the whole subtree** (`on_tree`) rather
+  than its direct children. Same end state by a blunter route, and it moves the
+  knowledge of "who might have been clobbered" into the clearing parent, where
+  the tree below it is none of its business. Each container forwarding one hop is
+  the local rule that composes.
+
+## D-tabs — `Tabs` / `TabSheet`: a strip, and a strip that swaps panes (2026-08-23)
+
+**Status:** Accepted; `Component::Tabs` (with `Tabs::Tab`) and
+`Component::TabSheet` implemented 2026-08-23, demoed in the sampler, taught in
+book ch7 ("Switching between views"). Brainstormed in `ideas/tabs.md`, now
+retired. Leans on `D-has-value` (the seam it declines), `D-progress-bar` (the
+precedent for a selection kept *out* of that seam), `D-list-items` (items vs.
+identities), `D-select` (claim the minimum), `D-ambiguous-width` (the separator
+glyph), `D-tree-api` (the slot-swap recipe) and `D-attach-hooks` (what
+detachment fires).
+
+**Context.** Several views, one visible at a time, and a one-row strip of
+captions to pick between them. Two components, because the strip is useful
+alone — Vaadin documents that case explicitly ("content switching without Tab
+Sheet"), and an app whose strip lives structurally elsewhere on the screen
+needs it: `Tabs` is the selector, `TabSheet` is the selector plus the pane that
+goes with it.
+
+**Decision — neither is `HasValue`, because a selection is not a value.** The
+test that decides it, and it generalizes: **would a form save it?** A
+`RadioGroup`'s selection *is* the datum being edited, so it is a value; a tab's
+selection is where the user is looking — nothing saves it, nothing validates it,
+and a forms layer iterating fields must never find it. `D-progress-bar` made the
+same call one step further out (a `value` that is a read-only report), and
+`List` has held a cursor and an `on_item_chosen` without being a field since it
+existed. External corroboration: **Vaadin's `Tabs` is not a field either** — it
+fires `SelectedChangeEvent`, exposes `setSelectedTab`/`setSelectedIndex`, and is
+grouped with Accordion and Details rather than with the fields. The cost is that
+`Tabs` gets no `empty?` / `clear` / `on_value_change` and no free `focusable?`,
+so it declares `focusable?` and `tab_stop?` itself, the way `Checkbox` and
+`Select` do. Someone will eventually ask for `tabs.value`; the answer is
+`selected` / `selected_index`, and this paragraph is why.
+
+**Decision — `on_tab_selected` reports that the selection *changed*, not that
+the user pressed something.** Arrows, a click, `selected=` / `selected_index=`,
+the autoselect of the first `add_tab`, and the re-selection that follows removing
+the selected tab all fire it; re-selecting the tab already selected fires
+nothing. Removing the *last* tab fires `(nil, nil)`, both arguments nil. The
+alternative — notify only on user gestures — would make `Tabs` the one component
+where an app must re-derive the selection after a removal, and the empty case is
+exactly where a listener most needs to hear from the strip: an app that renders
+from the callback has to be told to render *nothing*, or the departed tab's
+content sits on screen with no tab pointing at it. One implementation
+consequence worth keeping: the notification decision cannot be made by comparing
+indices, because removing the selected middle tab of three leaves the index at 1
+with a *different* tab under it. `apply_selection` therefore takes the
+previously-selected tab as an argument.
+
+**Decision — hiding a pane means *detaching* it; Tuile grows no visibility
+flag.** `TabSheet` keeps only the selected tab's pane in the tree. The
+alternative — n+1 children, unselected panes hidden by an empty rect — looks
+cheaper and is not, because the empty rect is a *paint* convention that gates
+nothing else. Five leaks, all silent: `cycle_focus` collects tab stops by tree
+walk, so every field in every hidden pane stays in the Tab cycle;
+`first_tab_stop_or_root` and `Layout#on_focus` cascade focus *into* hidden
+subtrees; `Screen` parks the hardware cursor at `focused.cursor_position`, so a
+hidden `TextField` puts the terminal cursor in the middle of the visible pane;
+`keyboard_hint` advertises the hidden widget in the status bar; and key delivery
+bubbles through it because it is on the focus chain. Only mouse hit-testing is
+safe. So option B needs a real seam gating at least four places plus a ruling on
+whether `Box` / `Absolute` skip invisible children when dividing space — a
+framework-wide change in the focus system, to buy one component what detachment
+already gives. Note the prior art: every framework that keeps hidden panes
+mounted (Textual, FTXUI) has a display/visibility flag in its *core* — Textual's
+`ContentSwitcher` is one `display` toggle. Tuile's honest options were detach or
+invent that flag. **Re-grow rule:** `Component#visible?` comes back only when a
+*second* consumer appears (a pane that must stay live while hidden, an app
+wanting hidden-but-laid-out widgets), and only argued as a focus-and-paint gate
+with an explicit ruling on layout arithmetic — never as a paint-time flag
+smuggled in under one component. AGENTS.md carries the one-line invariant.
+
+**Decision — one tab stop for the whole strip, and arrows activate
+immediately.** Three arguments against a component per tab, in order of force:
+"exactly one stop per widget" (`D-has-value`), and n tabs would mean n Tab
+presses before the content is reachable; making the *Tab key* walk between
+*tabs* is the one thing the key ladder forbids by construction (Tab is claimed
+above everything and means "leave this widget"), so it would read as a feature
+and be a semantic inversion; and no prior art does it, including the frameworks
+where individual tabs are widgets (Textual's `Tab`s are children of a focusable
+`Tabs` and are not focus stops).
+
+Activation is immediate — Textual, Terminal.Gui, FTXUI, Windows tab controls and
+the ARIA "automatic activation" pattern all agree, Vaadin being the lone
+counterexample with a manual variant motivated by expensive panels and
+screen-reader semantics a TTY doesn't have. The deciding reason is narrower than
+the prior art, though: **auto-activation means only one thing is ever
+highlighted.** Manual activation needs two states on one row — the selection and
+the roamed-to tab — and therefore two visual channels to separate them, on a
+strip that spends both on the selection alone (below). `RadioGroup` could afford
+that split vertically because each row has a glyph column of its own
+(`D-radio-group`); a one-row strip cannot, and two highlights side by side read
+as noise rather than as two kinds of state. Auto-activation deletes the
+distinction instead of styling it, and every code path — paint, hit test,
+callback — has one index to consult. Consequence, and it runs the opposite way
+to the brainstorm's guess: **lazy panes inherit this rather than reopening it.**
+Arrowing across five lazy tabs builds five panes; a sheet that can't afford
+that owes its own answer (a cheap placeholder, or building on a settle delay),
+not a return to Enter-to-activate.
+
+**Decision — the strip claims LEFT / RIGHT and the mouse, and nothing else.**
+`D-select`'s contract restated: Enter and Space have nothing to do once arrows
+activate, and declining them keeps a form's default button and the app's keys
+alive. UP / DOWN are declined so a future arrow-navigating layout can move focus
+*out* of the strip on the axis the strip doesn't use. HOME / END are declined
+too — Terminal.Gui binds them on its tab row, but a key no widget claims stays
+available app-wide, which is worth more than a shortcut for a jump that is two
+Left presses away in the 3–5 tab normal case; an app that wants it assigns
+`selected_index`. Edges clamp and consume, no wrap (as `List` does): the
+arrow-nav rule about declining at the edge is about *focus motion*, and this is
+selection, with the vertical axis already the way out.
+
+**Decision — bold marks the selected tab; it is not strip chrome.** The selected
+caption is bold *always*, and additionally sits on `Theme#active_bg_color` while
+the strip is on the focus chain; unselected captions are regular weight. Two
+channels, no new theme token. Bold is the one that survives an unfocused strip,
+which matters because the strip is the map of where you are in the app — unlike
+a `List` cursor, which is a transient pointer and has
+`show_cursor_when_inactive` for exactly this reason. **Bolding every caption is
+the tempting "fix" and it is wrong**: it spends the only unfocused-visible
+channel, leaving selection to the focus-gated background alone, so an unfocused
+strip would show no selection at all. Neither escape works — `input_bg_color` is
+the only other bg token and it means "resting input well" (`Select` uses it for
+exactly that), and dimming the *unselected* captions instead collides with the
+dim a *disabled* tab wants (see Deferred below), which would leave unselected
+and disabled indistinguishable.
+Rejected alternatives: bracketing the label (`[Payment]`) shifts every later
+segment by two columns whenever the selection moves, making hit-test geometry
+depend on the selection; an underline is `▁`, a fresh Ambiguous glyph. This
+ruling also needed one new primitive — `StyledString#with_bold`, since nothing
+in the gem had used bold and a caption is a `StyledString` that may carry its own
+colors.
+
+**Decision — the separator is `│`, the glyph `Window` paints its borders with,
+not ASCII `|`.** This inverts `D-ambiguous-width`'s "a new component defaults to
+ASCII when the pretty glyph is Ambiguous", and the inversion is the point: that
+rule exists to keep the Ambiguous inventory small and enumerable, and `│` is
+already *in* the inventory — `window.rb` paints it on every window, and nothing
+in the gem is designed to survive it measuring 2. Reusing a glyph the framework
+has already bet on adds nothing to the audit list, and a strip inside a window
+lines up with the border around it. `separator=` remains, now as the opt-in for
+ASCII. A *fresh* Ambiguous glyph still defaults to ASCII.
+
+**Decision — segment geometry: the padding is part of the segment, the separator
+column is chrome.** A segment is `" " + caption + " "`, segments joined by one
+separator column. Every segment has the same shape including the first and last
+(no trimmed outer padding, so no edge case in the arithmetic); the highlight
+covers the padding, because one that stopped at the glyphs would read as a
+ragged smear; and a click on a padding column selects that tab, while the
+separator column selects nothing — same rule as the blank tail past `extent`,
+which focuses without selecting (`D-boolean-fields`). One private `segments`
+method is the sole source of that arithmetic, read by *both* the paint and the
+hit test, and derived from the captions on each call rather than recorded during
+the last paint — so a hit test is correct before the first paint and after a
+caption change.
+
+**Decision — a narrow strip scrolls to keep the selection whole in view**
+(2026-08-24; v1 clipped, and this replaces that ruling before either strip
+shipped). One private `left_column` — the strip column painted in the rect's
+leftmost cell, the name `TextField` uses — read by the paint, the hit test,
+`extent` and (on `MenuBar`) the segment rect a panel anchors to, so there is
+still exactly **one** source of segment arithmetic; two would let a click land on
+the tab beside the one drawn under it. One idempotent `adjust_left_column` is its
+sole writer, called from every mutation site (`ProgressBar#sync_ticker`'s shape,
+not a nudge per site), which is what makes the offset `0` in every situation the
+clipping version handled, scroll back on its own when the rect grows or the
+captions shrink, and never need a scroll-back branch in any mutator. `MenuBar`
+funnels its three highlight writers through one private `highlight=` for the same
+reason, and gets a guarantee out of it: the highlighted segment is on screen
+*before* `Cascade` anchors a panel to it.
+
+Rejected — *segment-aligned scrolling* (the offset always a segment start): it
+buys clean edges and needs no glyph snapping, but wastes up to a segment of width
+at the right edge, and a strip this narrow is exactly where columns are scarce.
+Rejected — *reserved cue columns*: reserving two columns makes the window width a
+function of the scroll state that is computed from it, which is `D-select`'s
+`:auto`-scrollbar circularity, and shifts the whole strip sideways when a caption
+is edited. The cues are **overlaid** on the edge columns instead, keeping the
+style of the cell they cover so one landing on the selected segment doesn't punch
+a hole in its highlight, and they are ASCII `<` / `>` — `‹ ›` are Ambiguous-width
+(`D-ambiguous-width`), and a `cue_glyphs=` knob with no caller is a knob to argue
+about later. They stay chrome, not buttons: a click on a cue falls through to the
+half-visible segment under it, which selects it and reveals it — the direction the
+cue pointed anyway — where a clickable cue would need the column to hit-test
+differently from what it paints. And *free scrolling* (a wheel moving the window
+without moving the selection) is deliberately absent: the next sync would yank the
+view back to the selection, so supporting it means a second "user scrolled, stop
+following" state with a resume rule — `List#auto_scroll`'s machinery, for a
+one-row widget.
+
+**The trap this design steps over.** `StyledString#slice` *drops* a grapheme
+cluster straddling the window edge rather than half-painting it, so an offset
+landing mid-cluster returns a row one column short and shifts everything past the
+hole one column left — paint and hit test then disagree, silently, only for wide
+glyphs. So the offset is snapped *forward* to a cluster boundary, as
+`TextField#snap_to_glyph_start` does; forward is the safe direction, giving up at
+most one column of the segment left of the window and never of the one being
+revealed. A caption wider than the whole rect can't be shown whole at all: its
+head wins, being the half that identifies it.
+
+**Decision — `Tabs` owns mutable `Tab` handles; it does *not* get the
+`items=` / `item_label=` / `label_for` shell.** `add_tab("First")` mints and
+returns a `Tabs::Tab`, Vaadin-style. The test that separates the two is sharper
+than "items feel wrong": **an item is an element of a collection someone else
+owns** — assignment is whole-collection, and an item carries no per-element
+state, the renderer deriving everything from the object each paint (which is why
+`D-list-items` *removed* the appenders). **A tab is identity plus per-element
+mutable state**, minted by the widget and living as long as it, and re-assigning
+the whole set — the operation an items API is built around — is precisely what a
+strip must never offer: it would destroy tab identity and with it `TabSheet`'s
+pane mapping. Two corollaries make the ruling durable: the unbuilt half of
+`D-list-items` is a *data provider* behind `items`, and a provider cannot own
+per-tab state, so `HasItems` would arrive carrying a promise Tabs must refuse
+(paging tabs is meaningless — a million tabs is not a UI); and the growth path
+here is per-element *attributes* (hidden, disabled, closeable), which items have
+no notion of. So the `HasItems` question is closed for `Tabs`; it survives only
+for `ComboBox` / `Select` / `RadioGroup`, where the shell genuinely is three
+copies of one thing.
+
+The synthesis worth keeping: **the `Tab` object is what keeps those attributes
+from becoming framework seams.** A hidden tab is a skipped segment, not
+`Component#visible?`; a disabled tab is painted dim and skipped when arrowing,
+not a framework enabled/disabled seam; a closeable tab is an `x` in the segment.
+None touches `Component`.
+
+`Tab` is a small mutable object owned by the strip — not a frozen value type (it
+has settable attributes) and not a `Component` (it never paints itself; a
+component that never paints is a confusing new category). The contract is copied
+wholesale from `TextView::Region`: `private_class_method :new`, handed out by the
+owner, mutators invalidating the owner through a back-pointer, and **a removed
+handle raising on every mutator and on every reader that consults the strip** — a
+stale `Tab` is the same footgun as a stale `Region`. As there, the locally-held
+`caption` stays readable (so an error message can name it) and `remove` is an
+idempotent no-op. The back-pointer also closes the caption-refresh question:
+`Tab#caption=` invalidates the strip, so there is no `refresh_rows`-style
+question to answer.
+
+**Decision — no `Tab#data`.** A tab carries a caption and its own display
+attributes, nothing of the app's. The rejected slot would have let
+`on_tab_selected` hand back a domain object, and it isn't needed: the pane
+component owns its data (COP's "a component does everything its one purpose
+needs", so the pane *is* the handle), or a future binder does — the tab is on
+neither path. Anything genuinely per-tab and app-owned lives in the `TabSheet`
+or the app component that built it, keyed the way `TabSheet` keys its panes.
+This is what keeps `Tab` from becoming the items API this entry just refused.
+
+**Decision — `Tab` hand-rolls `caption` / `caption=` rather than including
+`HasCaption`.** The six duplicated lines look like exactly what a mixin is for,
+and the reason they aren't is the mixin's actual payoff: `HasCaption` earns its
+place as a **test-locator seam** — a locator walks the component tree matching
+`is_a?(HasCaption)` plus a caption compare, with no hardcoded class list. A
+`Tab` is not a `Component`, so it appears in no tree walk and that payoff is
+structurally unreachable; and there is exactly one `Tab` class, forever, so the
+"no hardcoded class list" benefit has nothing to range over either. Including it
+would be DRY-only, which is the bar the seam argument sets. The lookup debt is
+paid on the strip instead: **`Tabs#tabs`** returns the tab array (read-only by
+convention, like `Component#children`), so a test finds a tab through the widget
+that owns it — `tabs.find { |t| t.caption.to_s == "Payment" }`. That
+reader was needed anyway, since `TabSheet` keys panes by identity and nothing
+else can enumerate.
+
+**Decision — `TabSheet` holds two children, not n+1, and is not
+`HasContent`.** `children == [strip, pane]` with the strip pinned at index 0, so
+pre-order traversal yields the browser's strip-then-pane Tab order for free.
+`HasContent` stays out even though the swap looks like a content slot, for three
+concrete reasons: `content=` would become public API meaning "the visible pane",
+which is misleading (the pane is *derived* from the selection, not assignable);
+`HasContent#handle_mouse` forwards only into `content`, so the strip would never
+see a click; and `HasContent#on_focus` forwards focus into the content, which is
+the behavior this design rejects (switching a tab must not move focus into the
+new pane — browser and Vaadin behavior). What *is* reused is the slot-swap
+recipe `D-tree-api` specifies for `Window`: detach without notifying, rewire,
+then `on_child_removed` last, so the focus repair cascades into the *new*
+occupant. `TabSheet` overrides that hook to land focus on **the strip** rather
+than on itself, which is not focusable; the other candidate (the new pane's
+first tab stop) loses because the user's last action was a tab switch.
+
+Panes live in an identity-keyed `Tab => Component` map on the sheet. Licence:
+`Box`'s per-child constraint map, which AGENTS.md permits because it is "a
+per-child *attribute* map, not a second copy of ordering" — the strip's tab array
+stays the sole ordering authority. Rejected: a `component` slot on `Tabs::Tab`
+(the strip would then know about panes, which is the split this whole design
+rests on), and `TabSheet::Tab < Tabs::Tab` behind a protected factory hook (a
+framework hook existing for exactly one subclass, handing the minting decision
+to the subclass while `Tabs` still owns the array).
+
+Two implementation rulings the map earned. **One idempotent `sync_pane` is the
+sole writer of the visible pane**, deriving it from `strip.selected` on every
+call — which is what lets `add_tab` register a pane *after* the strip has already
+autoselected its tab, with no suspend-the-listener dance; the event-driven
+alternative has an ordering problem on the very first tab. And the map's keys are
+kept honest by an invariant rather than by one code path:
+`forget_removed_tabs` drops every entry whose tab is detached, because
+`Tabs::Tab#remove` reaches the strip without passing through
+`TabSheet#remove_tab` — which stranded the entry, pinned the pane against GC, and
+made `add_tab` reject that pane as still in use. Rejected there: an
+`on_tab_removed` listener on `Tabs` for the sheet to subscribe to — the tidier
+data flow, but new app-facing API whose only consumer is internal.
+
+Named `add_tab(caption, pane)`, not `add`: `Layout#add(component)` is the house
+`add`, and the explicit verb stops the two reading alike — the same reason
+`Tabs#add_tab` isn't `add`. (The brainstorm sketched `sheet.add`; its own
+argument overruled it.)
+
+**Decision — no framework key switches tabs from *inside* a pane, and no
+`Keys::CTRL_PAGE_UP` / `CTRL_PAGE_DOWN` constants are added.** Not v1, not
+later. Four reasons, the first decisive: it is **a global shortcut in disguise**
+— "one key, anywhere in the app, meaning switch tab" is app policy, and Tuile
+already has two homes for app policy (the rung-2 registry and an ancestor's
+`handle_key`), so shipping it as component behavior smuggles an app-level binding
+into a widget. Nested sheets make it ambiguous *and* the failure is silent: the
+bubble delivers to the innermost `TabSheet` first, so an inner sheet swallows the
+key and the outer one becomes unreachable by keyboard with nothing on screen
+explaining why. Vaadin apps have never needed it — the strip plus Tab is enough.
+And the editors that do have it use their own scheme, which is the argument for
+leaving the binding to the app: no choice Tuile made here would match the app's
+other keys. What Tuile owes instead is the *verbs*: `select_next` /
+`select_previous` are public (they exist for Left/Right anyway), so an app that
+wants the habit writes two lines and owns both the key and the "which sheet"
+question that sank the framework version.
+
+**Deferred, and why each lands additively.** v1 is captions, selection, mouse,
+keys and the pane swap. Nothing below is blocked, which is the payoff of the
+`Tab`-object ruling — each is a `Tab` attribute plus a branch in paint and in
+arrowing, needing no framework seam:
+
+- **Hidden tabs** — skip the segment when painting and when arrowing. Pane
+  hiding is already detachment, so this needs no `Component#visible?`.
+- **Disabled tabs** — paint dim, skip when arrowing, never select. A disabled
+  *tab* is not a component, so no enabled/disabled seam is needed. (A disabled
+  *pane* would be; still out of scope.)
+- **Closeable tabs** — an `x` in the segment, hit-tested, removing the tab.
+  Nobody else in the gem needs it and the glyph is ASCII-cheap.
+- **Lazy panes** — `add_tab("Reports") { build_reports }`, built on first
+  selection (Vaadin does it with an attach listener). Free to add: the swap has
+  one call site. Inherits auto-activation, per the activation ruling above.
+- **Clickable cues, and free scrolling** — see the scrolling decision.
+
+**Alternatives rejected** (beyond those argued inline). *Vertical orientation:*
+out of scope — Vaadin doesn't allow it in a TabSheet either, and a vertical strip
+is a `List` with a renderer (the Side Nav shape). *A border around the strip:*
+compose with `Window`; the Turbo Vision / Terminal.Gui look, with tabs notched
+into the top border, would couple `Tabs` to `Window` chrome. *Prefix/suffix
+slots* for icons and badges: unnecessary — a caption is a `StyledString`, so
+`Open [24]` is just text.
+
+**Consequences.** Selection is view state, so nothing in a forms layer will ever
+enumerate a strip. Hiding a component means detaching it, framework-wide, and
+`TabSheet` is the worked example — which also means a pane's `on_attached` /
+`on_detached` fire on every switch, and a pane cannot own a resource that must
+outlive its visibility. A tab is a handle an app holds, so tab identity is stable
+across caption edits and reorderings of nothing else. And a starved strip stays
+wholly reachable, at the cost of a scroll offset that every future paint-time or
+hit-test change has to keep threading through one place.
+
+## D-menu-bar — `MenuBar`: a focused strip driving a cascade of `ListDropdown`s (2026-08-24)
+
+**Status:** Accepted; v1 (`Component::MenuBar` with `MenuBar::Item` and the
+private `MenuBar::Cascade`) implemented 2026-08-24, demoed in the sampler, taught
+in book ch7 ("Menus"); v2 (mnemonics) the same day. Designed in a since-retired
+`ideas/menu-bar.md`, whose prior-art survey (Vaadin 25.2, Turbo Vision,
+Terminal.Gui, notcurses, MC, and the frameworks that have no menu) this entry
+only summarizes.
+
+**Update 2026-08-24: a narrow bar scrolls**, on `D-tabs`' scrolling decision,
+which both strips implement identically (one private `left_column`, one
+`adjust_left_column` as its sole writer, ASCII cues overlaid on the edge
+columns). `MenuBar`'s share of it: one private `highlight=` funnels the arrow,
+mnemonic and click paths, so a segment is on screen before `Cascade` anchors to
+it, and `rect=` still *closes* the cascade rather than re-anchoring it.
+
+**Context.** `ideas/new-components.md` listed Menu Bar as blocked on extracting a
+`Popover` from `ListDropdown#anchor_to`. It isn't: the widget needs a *second
+placement*, not a second kind of overlay.
+
+**Decision.** Focus never leaves the bar. The strip is the single tab stop, and
+the open menus are non-modal `ListDropdown`s mounted on the `ScreenPane` — owned
+by the bar, parented by nobody — so every key arrives at `MenuBar#handle_key`,
+which offers it to a `Cascade` first. That is `Select`'s architecture
+(`D-select`) extended to N levels, which is why **nothing in the key-dispatch
+ladder changes** and why the whole widget is additive: two new placement helpers
+on `ListDropdown`, one callback pass-through, and no change to `Popup`,
+`ScreenPane` or `Component`.
+
+The keyboard map is copied from Vaadin's, which is also the ARIA menubar pattern
+and what every TUI lineage surveyed does — Left/Right along the strip,
+Down/Enter/Space to open, Up/Down inside, Right/Enter to drill, Left to go back,
+ESC to close one level, and Left-at-the-top / Right-on-a-leaf stepping to the
+neighbouring menu. There was nothing to invent, and inventing would have been the
+error.
+
+**Alternatives rejected.**
+
+- **A single drill-down frame** — one panel that re-renders as you descend
+  (Terminal.Gui ships this as `UseSubMenusSingleFrame`). It needs no
+  `anchor_beside` and no stack at all, and was rejected because it loses the
+  "where am I in the hierarchy" readout that is the cascade's entire point — and
+  because it cannot be the default with a cascade bolted on later: the cascade is
+  the harder mechanism, and building it second means building it against a shape
+  that assumed one panel.
+- **A modal level-0 popup**, which would give real modality — keys scoped, clicks
+  outside blocked. Rejected on a mechanical fact, not a preference:
+  `ScreenPane#add_popup` **centers** every modal popup and focuses it, so an
+  anchored modal is impossible without changing `ScreenPane`. It would also
+  invert ownership, moving key handling off the bar and into the popup.
+- **Focusable panels**, focus descending as you drill. Rejected: AGENTS.md's
+  non-modal-overlay traps say a focus-taking non-modal overlay lands focus
+  outside the key scope and kills *every* keystroke until Tab recovers. This
+  would be that bug once per level.
+- **Extracting `Popover` now.** The roadmap's own trigger ("the second *kind* of
+  anchoring") arguably fires here, but both callers still wrap a `List`, so a
+  `Popover < Popup` would move code without a second kind of *content*. The
+  trigger is the first non-`List` content wanting anchoring (Tooltip, a
+  date-picker grid). It originally had a second half — a third placement method
+  on `ListDropdown`, from `ContextMenu`'s `anchor_at(point)` — which went dormant
+  when that widget was iced (`D-no-context-menu`).
+- **A command-code bus** (Turbo Vision's `cmOpen` + `handleEvent`) instead of
+  per-item callables. Rejected: Ruby has closures, and Vaadin, Terminal.Gui and
+  ratatui's `tui-menu` all landed on per-item listeners.
+- **`item.submenu` as a separate object** (Vaadin's `getSubMenu()`). It exists
+  because a Vaadin `MenuItem` is a DOM component; a Tuile item is a handle, so
+  `item.add_item` is one hop shorter and makes depth fall out for free.
+- **`Component::MenuItem` as a top-level constant.** Considered and reverted the
+  same day: promoting it was priced against a breaking rename once `ContextMenu`
+  names the type, and that price is zero, since no release ships in between. With
+  the cost gone the house default (`Tabs::Tab`, `List::Cursor`) wins, and
+  `MenuBar` gets to settle as one coherent component before unification is argued
+  against a second implementation rather than a guess about one. **Now settled
+  rather than deferred:** icing `ContextMenu` removed the counterparty, so
+  `MenuBar::Item` is simply the name. A revival after 0.13.0 ships pays a
+  **Breaking:** changelog line for the rename, or keeps `MenuBar::Item` as an
+  alias — cheap, and only paid if it happens, which beats paying it now for a
+  widget that may never exist.
+- **A `HasMenuItems` mixin** (Vaadin's shared `MenuBar` / `ContextMenu` /
+  `SubMenu` interface). Not needed yet, and the shape keeps it cheap: `MenuBar`
+  delegates `add_item` / `items` to a captionless root `Item`, so the method
+  exists exactly *once* and a future sharing exercise starts from one
+  implementation rather than two that drifted.
+- **Separators (`add_separator`).** Looks free, isn't: a `List` has no
+  unselectable row, so the cursor would land on a separator and Enter would
+  activate nothing. It needs a `Cursor` that hops non-selectable positions, which
+  is a `List` decision, not this one.
+
+**Deliberately not like `Tabs`.** The strip reuses `Tabs`' *hit testing* — an
+`extent`, one private `segments` method feeding both paint and click — and
+deliberately not its *look*: no separator column, no bold, and no highlight while
+unfocused. Both are one-row caption strips with one highlighted segment, so
+looking alike would leave a reader working out which control they are seeing. Two
+of the three divergences are forced anyway: bold is `Tabs`' *persistence* channel
+(the selection must survive focus moving on) and a menu bar has nothing to
+persist. The segments arithmetic is the second copy of that trio; per AGENTS.md's
+duplicate-a-shallow-shell rule a third caption strip is when to argue for
+extraction.
+
+**Consequences a contributor would trip over.**
+
+- **Activation is uniform.** Children win over a listener; a leaf closes the
+  cascade *before* firing (so an action that opens a dialog doesn't paint it under
+  a menu, as in `Select#commit`); and an item with **neither** children nor a
+  listener is legal and inert. An item that looks live but does nothing is the
+  app's error to fix, not the framework's to raise on.
+- **Stepping highlights; only Enter, Space or a click presses.** Left/Right
+  moving to a neighbouring *top-level button* (a listener, no menu) closes the
+  cascade and highlights it — it does not fire it, or walking the strip would
+  trigger every button on the bar, each one behind a menu still standing over its
+  output. Every path that *does* fire a top-level listener closes the cascade
+  first, matching `Cascade`'s own leaf activation.
+- **A resize closes the menu**, from `MenuBar#rect=` — see the AGENTS.md
+  non-modal-overlay trap for why that is the legal answer here rather than a
+  `reposition` override. Only a *changed* rect closes it, since `Layout::Box`
+  re-assigns an equal rect on any child mutation.
+- **So does detaching**, from `on_detached`: the panels are the pane's children,
+  not the bar's, so nothing else would take them down.
+- **An open menu swallows keys; a closed strip does not.** The one deliberate
+  divergence from `D-select`'s claim-the-minimum rule, and the honest reading of
+  what a menu is — an app key firing behind a visible panel is worse than a dead
+  keystroke.
+- **A click outside an open cascade is not blocked**, because non-modal overlays
+  block nothing — but it does *dismiss*. The framework-level fix this entry
+  called for (and declined to invent here) shipped as `D-outside-click`: the
+  pane closes every popup a left click missed, and `Cascade` reconciles its level
+  stack from each panel's `Popup#on_close`. The click itself still reaches
+  whatever is beneath.
+- **`Cascade` is provisional.** It is split from the strip on cohesion, not reuse
+  — otherwise `MenuBar` would both paint captions and manage an overlay stack —
+  and the test for keeping it is *the size of the interface `MenuBar` needs*: at
+  `open_below` / `handle_key` / `close` / `open?` it is a boundary; if it grows
+  accessors that expose the level stack, the "class" was only ever a seam and it
+  folds back in.
+- **Widths are measured per level, caller-side**, third repeat of the `D-select`
+  pattern (`anchor_to` and `anchor_beside` measure nothing). The submenu arrows
+  right-align against the level's *widest label*, a number the cascade already
+  has, so they line up without asking the `List` how wide it ended up.
+- **The `▸` is Neutral, not Ambiguous** — verified, like `Select`'s `▾`. The
+  obvious `▶` / `▼` are Ambiguous and would have needed an ASCII opt-in under
+  `D-ambiguous-width`.
+
+**Mnemonics (v2), and why they are legal.** `add_item(caption, mnemonic: "f")`
+at *every* depth. AGENTS.md deleted `Component#key_shortcut` and the capture
+phase that scanned a scope subtree, and forbids reintroducing them — but its
+re-grow rule sanctions exactly this: *sugar over an ancestor's `handle_key`,
+never a dispatch phase and never a gate*. A focused `MenuBar` consulting its own
+item tree inside its own rung-3 `handle_key` is unregistered, unscanned and
+invisible to every other component. This is the first thing a reviewer will
+(correctly) flag, hence the paragraph.
+
+The rule is **one live set, no fallback**: the top-level items while the cascade
+is closed, the deepest open panel's items while it is open, nothing else ever
+consulted. Cross-level collision is therefore *structurally impossible* rather
+than tie-broken — `File > Export` and top-level `Edit` may both bind `e`, and
+with File open there is nothing to arbitrate — and `f`,`q` for File > Quit falls
+out with no chord, buffer or timeout. A duplicate *within one sibling set* raises
+at `add_item`, which is the only scope where two mnemonics can race. A miss
+swallows rather than falling back to a shallower level: a mistyped letter must
+not tear down the open menu and open another, and Left/Right and ESC are the
+routes to a different menu. All of this is what Windows/GTK/Qt do; macOS is the
+only lineage without menu mnemonics, for the historical reason that it never had
+an Alt-activates-the-menubar model.
+
+Four consequences worth recording, each a road that looked open:
+
+- **The match is hoisted above the cascade delegation.** v1's cascade swallows
+  every unrecognized key while open, so a letter would never reach the strip
+  otherwise. It is guarded to a single printable non-space character so Enter,
+  Space, the arrows, ESC and `MOVE_KEYS` keep their v1 path.
+- **The cue is `Item#cued_caption`, computed once at construction.** There are
+  two paint sites (the strip's segments, the cascade's row renderer) and
+  `StyledString#slice` counts **columns** while a caption search yields a
+  **character** index, so the conversion lives in exactly one place. Safe to
+  precompute — unlike a theme value, it has no live input. Cues are **always
+  drawn**, focused or not: Tuile has no Alt to reveal them with, so the choice is
+  binary and discoverability wins.
+- **The bell is tied strictly to the swallow**, and guarded by `Keys.printable?`
+  at the swallow site. Unguarded it would ring at HOME, function keys and the
+  five-byte junk `Keys.getkey` returns for an unknown escape sequence. No bell
+  while the strip is *closed* — a bubbled key is not a miss — and none for a
+  matched-but-inert item or a clamped arrow, or "beep when nothing happened"
+  would grow into an audit of every no-op path.
+- **`List#select(index)` was the one real gap.** The cascade must move a panel's
+  highlight to the matched row *before* drilling, or a submenu anchors beside
+  whatever row the cursor was on — and a row scrolled out of view has no rect to
+  anchor against at all. `List` could move its cursor by key, by mouse and by
+  search, but not by index; that hole is independent of menus.
+
+**Type-ahead search is deliberately not built.** "Type `s` in an open menu to
+jump to the first item containing s" is nearly free — `List#select_next` already
+does substring, case-insensitive, cursor-ordered-with-wrap search — and that is
+the trap: it competes with explicit mnemonics for the same keystroke, so it owes
+a precedence rule *and* a ruling on whether a unique match fires or merely
+highlights. A separate feature, for a later session.
+
+**Deferred, each additive:** checkable and disabled items, global-shortcut
+activation (which needs `Keys` to grow function keys first — and this is the
+deferral that costs something, since with no Alt the only way to *reach* the bar
+is Tab, which is what separates `Alt+F, X` from a Tab-hunt), removal and
+reordering, dynamically computed items, open-on-hover
+(needs mouse motion — Tuile runs X10 mode 1000, press-only), and Vaadin's
+collapse-into-an-overflow-menu.
+
+**Update 2026-08-24: `ContextMenu` is iced indefinitely** — designed, priced and
+declined the same day, in `D-no-context-menu`. It would have reused `Cascade` and
+`Item` verbatim, which is why the two consequences above are worded the way they
+are: the nested `Item` name is *settled* rather than deferred, and the `Popover`
+extraction trigger keeps only its "first non-`List` content" half.
+
+## D-outside-click — An outside click dismisses a popup, by flag not by notice (2026-08-24)
+
+**Status:** Decided and implemented 2026-08-24. Designed in a since-retired
+`ideas/outside-click-dismiss.md`, itself split out of the declined `ContextMenu`
+(`D-no-context-menu`), so this entry is the whole record. Supersedes the wart
+`D-menu-bar` recorded without fixing.
+
+**Context.** Whether an open overlay closed when you clicked elsewhere depended
+on what you happened to click *on*. A click on a focusable widget moved focus,
+and losing focus is what closed `Select`'s dropdown and `MenuBar`'s cascade — so
+it worked, by accident. A click on decoration (a `Label`, a `Window` border, a
+gap between fields, the status bar row) did nothing at all, and the overlay
+stayed open over content it no longer belonged to. Three customers felt it:
+`Select`, `MenuBar`'s whole cascade, and the sampler's slash-menu demo.
+
+It could not be fixed inside the widgets. `ScreenPane#handle_mouse` routes a
+click to the topmost popup containing it, else the tiled content, else (with a
+modal open) nobody — so a click that misses every popup is never reported to the
+open overlay, no driver can poll for it, and nothing below can forward it. A
+`ScreenPane` change or nothing.
+
+**Decision.** `Component::Popup#close_on_outside_click?` (default `true`, modal
+or not), read by `ScreenPane#handle_mouse`: a left click that misses an open
+popup closes it. Beside it, `Popup#on_close`, a driver-facing callback fired from
+`on_detached`.
+
+**Why a flag and not `on_outside_click(event)`.** The rejected alternative was
+notice-shaped: every missed popup gets the event, default no-op, with a
+driver-facing proc beside it. It works, and it is more expressive. It was
+rejected because it hands a `MouseEvent` to a component that is *not* on the
+chain the event was delivered to — structurally the same second delivery this
+project already rejects for a `Screen`-level click broadcast, just with a shorter
+subscriber list. Under the flag, `ScreenPane` never delivers anything twice: it
+closes popups that asked in advance to be closed. **The popup receives a fate,
+not an event**, and "a click is delivered exactly once, down one chain" stays
+literally true.
+
+The price is expressiveness: the popup answers with a stored `true`/`false`, not
+with an opinion about the click. Paid once, by `ComboBox` — its field is tiled,
+so clicking your own input to reposition the caret closes the list you are
+filtering. Transient, because `TextField#on_change` is wired to `refill`, which
+reopens it on the next keystroke, and Vaadin's ComboBox behaves the same way. If
+per-click nuance is ever genuinely needed, widen the reader to
+`close_on_outside_click?(event)` — a pure widening, no migration — rather than
+reaching for a notice or a veto.
+
+**The ordering rule, both halves load-bearing.** Snapshot the open popups
+*before* routing, close the opted-in misses *after*.
+
+- *Snapshot before*, or a popup the delivered click **opened** is in the set and
+  dismisses itself instantly — every `Select` would be unopenable by mouse.
+- *Close after*, or a widget toggling its own overlay from a click on its face
+  sees a shut overlay and **reopens** it — a `Select`'s dropdown could then never
+  be dismissed by clicking the Select.
+
+Both are specced, and both mutations also break *pre-existing* `Select` specs.
+The snapshot is a fresh array for a third reason: a handler may close further
+popups, and `@popups` must not be mutated mid-iteration.
+
+**"Outside" spans the owner chain, and stacking order plays no part.**
+`Popup#owner` names the component an overlay is *part of* (`nil` = an overlay in
+its own right). A click keeps the popup it hit *and* every popup that one
+belongs to, transitively; everything else dismissable closes. The owner is any
+`Component` — a driver hands its dropdown `self` — and the pane resolves it to
+the enclosing popup at click time, a `Popup` resolving to itself.
+
+Two bugs forced this, both found by clicking rather than by reasoning, and both
+after the naive "closed if it missed my rect" rule had shipped:
+
+- **A cascade panel is beside its parent, not inside it.** Drilling by mouse
+  (File → Open Recent → Archive) dismissed every shallower panel, so the File
+  menu vanished the moment you clicked into its own submenu.
+- **A dropdown routinely hangs past its dialog's border.** A `ComboBox` or
+  `Select` on a dialog's lower rows drops a panel outside the dialog's rect, so
+  clicking a row dismissed the dialog. The most common form layout there is.
+
+Neither is reachable by a widget-local fix: the panels and the dialog are
+different popups with no way to speak for each other.
+
+**Two rejected rules, and why order is the wrong axis.** *Dismiss the popups
+stacked above the one you clicked* (standard light-dismiss layering) fixes both
+bugs with no new API, and was rejected because `@popups` is insertion order and
+Tuile has no click-to-raise: the same click would produce different outcomes
+depending on which overlay opened first. *A click on any overlay dismisses
+nothing* also fixes both, needs no API at all, and was rejected because it
+declares unrelated overlays related — it leaves a dropdown open when you click
+the dialog beneath it, and stops two window-like overlays from dismissing each
+other, which is exactly what they should do.
+
+Order is only ever the *shadow* of ownership: a child overlay cannot exist
+before its host, so it is always later in the stack. Reading the shadow works
+for related popups and is meaningless for unrelated ones, which is why the
+relationship is declared instead.
+
+Consequences kept: every dismissable popup closes, not just the topmost — a
+cascade must vanish whole on one background click, not peel one panel per click
+— and two *unrelated* stacked modals both close on one outside click, where
+Vaadin's curtain would close only the top. Arguably Vaadin-consistent anyway:
+the Flow Dialog docs say closing a modal Dialog also closes the dialogs opened
+after it.
+
+**The cost, stated plainly.** `owner` is a declaration you can forget, and
+forgetting it silently reproduces the two bugs above. It is the third entry in
+AGENTS.md's non-modal-overlay traps for that reason. Three sites wire it today:
+`ComboBox` and `Select` hand their dropdown `self` at construction (not per
+open, so there is nothing to forget on reopen), and `Cascade#push` chains each
+panel to the one it dropped out of. Level 0 owns nothing on purpose — a click on
+a dialog hosting the bar *should* close the whole menu and keep the dialog. A
+mis-wired cycle terminates rather than hanging, guarded by the walk.
+
+**Why `on_close` hangs off `on_detached`, never `#close`.** A popup leaves the
+screen three ways — `Popup#close`, a direct `Screen#remove_popup`, and
+`Screen#close` → `detach_all`. Hang the proc off `#close` and two of those vanish
+silently, which is the desync the mechanism exists to kill, reintroduced one
+level up. `parent=` is already the sole firing site for the lifecycle hooks, so a
+proc over `on_detached` keeps that true and makes the notice unconditional. The
+subclass trap that follows: `Notification#on_detached` already existed and now
+calls `super`.
+
+`MenuBar::Cascade` is the worked example and the reason the callback exists. It
+keeps `@levels` as the sole authority on depth, so a panel closing behind its
+back would leave `depth` / `deepest` / `highlighted` all lying. It wires an
+identity-keyed, idempotent delete — idempotent because the same notice also
+arrives from its own `truncate` (which has already popped the entry) and from
+teardown, in no guaranteed order. That is the shape the house rules ask for:
+`@levels` is a `D-tree-api`-style second copy of a list slot, and hook-owned
+state is *synced from an invariant*, not toggled by the hooks (`D-progress-bar`'s
+`sync_ticker`). Per-level truncate closures wired at `push` are the toggle
+version.
+
+**Left button only.** `MouseEvent` is X10 press-only (no release, no motion), so
+there is no drag case. Excluding scroll is `D-notification`'s stray-spin lesson;
+excluding `:right` keeps a future context action from nuking an open dropdown.
+
+**Vaadin, verified against the 24 docs.** "Modal dialogs are closable in three
+ways: by pressing Esc; clicking outside the Dialog; or programmatically", and
+"Dialogs are modal by default" — so default-`true`-even-for-modals is the Vaadin
+behavior, and that is why the default is what it is. What does *not* port: in
+Vaadin the thing catching the outside click is the modality curtain, part of the
+overlay, so light dismiss is nearly free because modality is a DOM element.
+Tuile's modality is a routing rule with nothing to click on, so the notice must
+be manufactured. Which also means Vaadin's *non-modal* behavior is no precedent
+here — a non-modal Vaadin Dialog does not light-dismiss; its ComboBox overlay
+does.
+
+**The modal/non-modal split dissolves.** The design was framed as two halves,
+only one with a customer: non-modal overlays needing a notice, and modals unable
+to hear a click at all. The flag applies identically to both, and no
+`clicked ||= modal_popup` routing change is needed, because nothing is
+*delivered* to the modal — it is just closed. An outside click on a modal both
+dismisses it and is swallowed (click once to dismiss, again to act), same as
+Vaadin's curtain.
+
+**Roads not taken.** A veto — `on_close` (or a new hook) returning false to
+refuse the close: rejected mechanically, since `on_close` fires from
+`on_detached`, after the popup is off the screen, and you cannot un-detach. Any
+veto therefore needs a *new*, earlier hook, which is the notice again with a
+return channel, and it makes every grouped overlay re-implement the geometry
+test the pane just did. A `Screen`-level "a click landed at P" broadcast any
+component can subscribe to: rejected on sight, a second mouse-dispatch path
+beside the one-chain rule. Making `ListDropdown` modal so it hears every click:
+`ComboBox` and `Select` would lose the events their own faces need. A generation
+counter to make close-and-reopen-within-one-click safe: over-engineering for a
+case nothing hits — reopening the *same* popup object during delivery of one
+click is out of contract (the snapshot holds it), and the answer is a fresh popup
+or a cleared flag.
+
+**Per-widget settings.** `Popup` defaults `true`; `ListDropdown` inherits it, so
+`Select`, `ComboBox` and every cascade panel are fixed with zero wiring;
+`Notification` sets `false`, since a toast is timed and an unrelated click is not
+about it; app modals keep `true` and opt out per dialog. The one accepted risk is
+a stray click discarding a half-filled form dialog.
+
+## D-no-context-menu — No `ContextMenu`: designed, priced and declined (2026-08-24)
+
+**Status:** Decided 2026-08-24 — **not building it**, indefinitely. Designed in a
+since-retired `ideas/context-menu.md` (opened and graduated the same day), so
+this entry is the whole record. `Context Menu` was *dropped* from
+`ideas/new-components.md` rather than demoted to its Tier 3, and nothing else
+tracks it.
+
+**Context.** The roadmap listed it as a Tier 1 near-freebie — "same as Menu Bar;
+`:right` already parses" — and after `MenuBar` shipped that looked right: the item
+tree, the mnemonics, the cascading submenus and the per-level width measurement
+all exist and would have been reused as they stand. The design confirmed it. The
+widget then failed on its *inputs*, not on its machinery, which is why this entry
+is a rejection rather than a deferral.
+
+**Decision, and the three reasons in order of weight.**
+
+1. **The gesture that defines the widget is the least reliable input Tuile has.**
+   A context menu *is* right-click, and terminal emulators routinely keep that
+   button for their own menu (some pass it through only with Shift) — on top of
+   mouse reporting being optional in the first place. The keyboard route then has
+   to be invented from nothing: no terminal sends a context-menu event, where a
+   browser hands Vaadin `contextmenu` from Shift+F10 *and* the Menu key, so
+   Vaadin's `ContextMenu` needs no keyboard code at all. **And Shift+F10 is not
+   readable today:** `Keys.getkey` gulps at most 5 bytes after `\e` — deliberately,
+   since 6 would over-read the next event on a mouse burst — while xterm sends
+   `\e[21;2~`, 6 tail bytes, so the `~` would surface as a printable keypress.
+   `\e[29~` (Menu/Apps) and plain F1–F12 *do* fit. That constraint binds anything
+   wanting an exotic key, not just menus.
+2. **No host wants one.** Not the sampler, not `file_commander`, and the TUI
+   lineages are thin: mc spends F9 on a menu bar instead, Turbo Vision and LazyGit
+   have none. LazyVim is the counterexample — it does ship one — which is an
+   argument for revisiting when a host asks, not for building on spec.
+3. **It would cost two new framework concepts to serve nobody** — an invisible
+   modal popup as a focus grab, and a `ScreenPane` notice for modality-blocked
+   clicks (the second outlived it; see below).
+
+**The design that would have been built,** recorded so a revival starts here. One
+structural fact drives all of it: **a popup can only hold focus if it is modal.**
+`ScreenPane#handle_key` scopes delivery to `modal_popup || content`, so a *focused
+non-modal* popup sits outside the key scope and every keystroke goes dead —
+AGENTS.md's non-modal-overlay trap. There is no third option, and unlike a menu
+bar a context menu has no strip to park focus on.
+
+So: `ContextMenu < Popup(modal: true)` with a **zero-size rect that paints
+nothing** — not a picture but a *grab*, playing exactly the role `MenuBar`'s strip
+plays (focus holder, key scope, lifecycle owner, outside-click sink). Every
+visible panel, level 0 included, is a `Cascade` level, so `Cascade` and `Item` are
+reused verbatim and mnemonics work with no new code at all. Modality then hands
+over focus save/restore (`@popup_prior_focus`), an inert Tab (`cycle_focus` scopes
+stops to `modal_popup`, and a grab has none) and click-blocking for free. Two
+openers, because the desktop lineages agree these are different placements:
+`open_at(point)` for the mouse, `open_below(rect)` for the keyboard — pointer
+versus selection. Framework growth: `ListDropdown#anchor_at(point)`, a second
+level-0 entry point on `Cascade`, the blocked-click notice, and overrides for
+`reposition` (or close-on-resize, as `MenuBar#rect=` does), for `q`/ESC — `q` has
+to stay available as a mnemonic — and for `keyboard_hint`.
+
+**Alternatives rejected.**
+
+- **Host-driven, no new machinery** — a plain object the host wires from its own
+  `handle_mouse` / `handle_key`, i.e. `MenuBar`'s architecture minus the
+  component. It costs the framework nothing, and that is the trap: `MenuBar`
+  encodes five invariants *once* because it is a component — close on focus loss,
+  on detach, on resize, swallow keys while open, forward the mouse — and every
+  host would re-encode all five. Forgetting `on_detached` strands panels on the
+  pane with nothing to take them down, the exact bug class AGENTS.md's
+  non-modal-overlay section exists to prevent.
+- **The level-0 panel *as* the modal popup**, which deletes the invisible
+  component. Rejected because level 0 then becomes structurally unlike every
+  deeper level, so the panel-driving logic — `MOVE_KEYS` to the highlight, Enter
+  to drill-or-fire, mnemonic match, truncate-on-cursor-move — exists twice for
+  panels that are identical on screen. It buys only the deletion of a zero-size
+  rect.
+- **Recursive modal popups, one per level, no `Cascade`** — each level an ordinary
+  modal `Popup` over a *focusable* `List`, with `Popup`'s own ESC/`q` closing a
+  level. Genuinely tiny and free of every non-modal trap, and rejected on the
+  smell: it is a *second* menu mechanism, so item trees, mnemonics, submenu
+  arrows, width measurement and the key map would all get a second
+  implementation. If it is right, `MenuBar` is wrong — a much larger argument
+  than this widget.
+- **A `Component#context_menu=` slot** checked inside `Component#handle_key`, so
+  any component gets one by assignment. Half a feature: almost no widget calls
+  `super` from its own `handle_key` (`List` doesn't), so it would work for
+  ancestors that don't override and silently not for focused leaves.
+- **Vaadin's `setTarget(component)`** — attach the menu to a target and let the
+  framework route the right-click to it. Tuile has nothing to build that on:
+  `handle_mouse` returns `void`, and a right-click already reaches *every*
+  component along the rect chain, ancestor first and deepest last, so "which
+  target owns this click" has no answer. (What that ordering *would* give free is
+  deepest-wins, if a revival adds "opening one closes any other open context
+  menu" — the `D-notification` shape, found by scanning the popups stack rather
+  than a class ivar.)
+- **Type-ahead search inside an open menu**, which `List#select_next` makes nearly
+  free. Same rejection as in `D-menu-bar`: it competes with explicit mnemonics for
+  the same keystroke and owes a precedence rule.
+
+**Two gaps it surfaced that outlive it.**
+
+- **An outside click on an open overlay notified nobody.** `Select`, `MenuBar`
+  and the sampler's slash menu all lingered on a click that landed on decoration,
+  and a modal popup could not dismiss on an outside click at all. **Closed**
+  2026-08-24 by `D-outside-click`, which also dissolved the modal/non-modal split
+  the gap was framed around.
+- **A right-click does not move a `List` cursor.** `List::Cursor#handle_mouse`
+  acts on `:left` only (specced), and there is no public `item_index_at(point)`,
+  so "act on the row I clicked" is unsayable unless the app computes
+  `event.y - rect.top + scroll_top_row` itself. Nothing needs it today; it is the
+  same shape of hole as the `List#select(index)` gap `D-menu-bar` had to fill.
+
+---
+
+## D-status-bar — Delete the framework status bar; the app owns its bottom row (2026-08-25)
+
+**Status:** Accepted 2026-08-25; unimplemented. Supersedes the shipped
+`ScreenPane#status_bar` slot and the `Component#keyboard_hint` channel that fed
+it — see *the scar* at the end. Retires `ideas/status-bar-ownership.md`.
+
+**Context.** `ScreenPane` has always reserved the bottom terminal row for a
+framework-owned `Label`, and `Screen#refresh_status_bar` filled it on every
+focus change from three sources: a hardcoded `"q quit"`, the `hint:` strings on
+registered global shortcuts, and one component's `keyboard_hint` — the innermost
+active `Window` (found by an `is_a?` scan) when tiled, the top popup's *direct*
+content when not.
+
+That last source barely worked. Of the seven `keyboard_hint` implementations,
+only `Window`, `Popup` and `PickerWindow` (a `Window`) were reachable in any
+configuration; `MenuBar`, `Tabs`, `Select` and `ComboBox` were dead
+**everywhere**, tiled and popup alike, because nothing walked down to the
+focused component and the popup path forwarded only to its direct child. The
+obvious fix — ask `screen.focused` and walk up, matching the delivery bubble —
+was drafted, and a survey of the two real consumers was run to choose between
+it and two variants. The survey concluded the channel should be **deleted**.
+
+**Decision.** Delete the status bar and the hint channel. `ScreenPane` no longer
+owns a `Label`, no longer reserves `height - 1`, and `Component#keyboard_hint`
+ceases to exist. In its place `Screen` gains one notification —
+`on_focus_changed=`, a plain proc fired from `focused=`, matching the
+`on_theme_changed=` style stock assemblies already use. An app that wants a
+status bar builds one:
+
+```ruby
+bar = Tuile::Component::Label.new
+root = Tuile::Component::Layout::Vertical.new
+root.add(main, Expand)
+root.add(bar, Fixed[1])
+screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
+```
+
+**Why deletion beat a better hint source.**
+
+- **No app has ever wanted a *widget's* hint.** Across four apps, virtui
+  advertises window-level app keys (`"p Power  v run Viewer  m Memory  d toggle
+  Disk stat  / Search"`) and pikuri-tui advertises global app keys (`"^K menu"`,
+  `"^C cancel"`). Neither has ever advertised a `Select`'s or `ComboBox`'s keys.
+  The channel was not merely unused by four of its seven implementors — the
+  thing it was designed to carry is something nobody wants carried.
+- **An app was routing presentation through dispatch.** pikuri re-registers a
+  global keybinding to change a status-bar string, and documents the technique
+  in rdoc: "`Screen` replaces the binding in place on re-register, so this is
+  also how the hint stays in sync with the counter." The bar was write-only from
+  the app's side, so a *text* change had to be expressed as a *binding* change.
+  That is the design inverted, not a missing feature — and it is the single
+  finding that settled this.
+- **The one reachable widget hint was also stale.** `MenuBar#keyboard_hint`
+  switched to `"↑↓ move  ⏎ select"` with the cascade open, but the cascade is a
+  non-focusable `ListDropdown`, so focus never changed and `refresh_status_bar`
+  never ran (it fired from `focused=`, `theme=` and the two registry mutators —
+  never from `add_popup`). Opening a menu did not update the bar; *closing* it
+  did, via focus repair. Dead twice over.
+- **The bar is a layout special case that `Box` layouts obsoleted.** The
+  `height - 1` reservation is v0.1-era, from before `Vertical`/`Fixed` existed.
+  An app-owned bar is now three lines, and buys what the framework can never
+  offer: two rows, a bar at the top, its own styling, a file-commander
+  function-key strip, or nothing at all.
+- **It is the shape the top-down re-grow rule already governs.** That rule says
+  a deleted bottom-up channel may return only as an *optional, read-only,
+  caller-side query*, never as an automatic channel the framework consults.
+  `keyboard_hint` was an automatic channel; deleting it applies the rule Tuile
+  already lives by.
+- **The framework baked an app policy.** The `"q quit"` prefix was
+  unconditional: pikuri's three apps quit via `^K → q`, and their bar read
+  `q quit  ^K menu` while `q` typed into the focused input just typed a `q`.
+
+**Alternatives rejected.**
+
+- *Walk the focus chain and concatenate (the drafted fix).* Correct as far as it
+  went — it matched the delivery bubble, subsumed the popup special case, and
+  would have deleted `active_window`. Rejected because it fixes *reachability*
+  while leaving ownership where it hurts: pikuri's re-registration hack survives
+  it untouched, and MenuBar's flickering, redundant `←→ menu  ⏎ open` becomes
+  *visible* rather than merely dead. It also forced a ruling on hint ordering
+  that is really a truncation policy, since `Label` ellipsizes and the rightmost
+  hint silently vanishes on a narrow terminal.
+- *Ask `active_window` and forward down the active chain.* Keeps `Window` as the
+  unit of "what am I looking at" but re-implements the focus walk, and preserves
+  the framework's only place where a *class* is special-cased for behavior.
+- *Keep the bar, make it optional.* A `status_bar: false` flag leaves every
+  defect in place for whoever leaves it on, and adds framework surface in the
+  middle of an argument for less of it.
+- *Drop only `MenuBar#keyboard_hint`.* Treats the symptom. Three other widget
+  hints stay dead, and the ownership inversion is untouched.
+- *Keep `Component#keyboard_hint` as a documented seam, delete only the
+  renderer.* Tempting — it preserves a common vocabulary for a future component
+  ecosystem. Rejected for now because a seam with no framework consumer is
+  precisely the automatic-channel-with-no-caller the re-grow rule exists to
+  prevent, and because the built-in hints it would preserve are the four nobody
+  wants. See the re-grow shape below.
+
+**Consequences — what was given up, honestly.**
+
+- **Zero-config batteries are gone.** `book/01-first-app.md` said "you never
+  created a status bar, yet the app has one", and `hello_world_spec` asserted on
+  `q quit`. A first app now shows an empty bottom row until it builds one. Ruled
+  acceptable: a bar the app cannot drive is not a battery, and ch1 gains a
+  better story once the bar is three lines of `Vertical`.
+- **A widget's keys are no longer self-describing.** An app that *does* want to
+  advertise a `ComboBox`'s keys must hardcode `"↑↓ select  ⏎ accept"` itself,
+  duplicating knowledge that lived in the widget. No app has ever done this, but
+  the duplication is real if one starts.
+- **`book/05-focus.md`'s "The status bar writes itself" section goes.** It
+  claimed the bar was "driven by focus" and showed "the focused context's own
+  advertised hint" — behavior that never existed; focus only triggered the
+  rebuild. Deleting it removes a documented promise the code never kept.
+- **`D-boolean-fields`' aside is retired**, not overruled: "hints are a
+  window/popup-level affordance; per-field hints would drown the status bar" was
+  an argument about where a hint belongs, and there is no longer a framework
+  hint to place.
+- **A modal {Component::Popup} no longer shows how to close itself.**
+  `Popup#keyboard_hint`'s `q Close` was the only affordance, and — unlike
+  `PickerWindow`'s hint, which merely repeated the option keys its own `List`
+  rows already paint — nothing else on screen carries it. `popup.rb`'s `q`/ESC
+  handler is untouched, so the behavior remains; only the advertisement is gone.
+  **Ruled acceptable 2026-08-25 on the Vaadin precedent:** a Vaadin `Dialog`
+  closes on ESC and no Vaadin *app* documents that anywhere — it lives in the
+  framework's own docs and javadoc, which end users never read. ESC-dismisses-an
+  -overlay is a convention the user brings with them, not something each app has
+  to teach. An app that wants it spelled out writes it into its own row.
+
+**The `q`/ESC quit fallback stays** (`Screen#event_loop`:
+`@event_queue.stop if !handled && ["q", Keys::ESC].include?(key)`). It is the
+same baked app policy as the `"q quit"` string, but it is *dispatch*, not
+presentation, and it is separable — deleting it would make every example and
+both downstream apps grow a quit handler in the same breath as an unrelated
+change. **Ruled 2026-08-25 by `D-quit-key`: it stays, unadvertised**, on the
+same convention argument as the popup's lost `q Close` above.
+
+**There is no app-facing `keyboard_hint` convention, and the book must not
+teach one.** The first cut of `examples/file_commander.rb` kept a
+`PaneWindow#keyboard_hint` and walked up the focus chain via
+`respond_to?(:keyboard_hint)` to find it — which re-created the deleted seam by
+convention, in three places at once (the example, the book, virtui), with a
+duck-type where a declared method used to be. It was also *dead*: both panes
+were `PaneWindow`s returning the same constant, so the focus hook, the walk and
+the duck-type together computed a value that never changed. The example is now
+a static `Label` and `PaneWindow` is gone; book ch5 leads with "a status line is
+a `Label` in your layout", and treats {Screen#on_focus_changed=} as the
+*exception* for a row that genuinely varies. The walk survives only in virtui,
+where three windows really do advertise different keys — as one app's design
+decision, named as such.
+
+**Re-grow rule.** A hint channel may come back only as **a query the app pulls,
+never a channel the framework pushes** — and specifically not as a
+framework-owned row. Textual is the shape to copy if it does: its `Footer` is a
+widget the app mounts in `compose()`, reading from the `BINDINGS` table the
+framework owns ⚠. That splits ownership at the right seam — the app decides
+whether a bar exists and where, the widget declares its keys — and it is already
+on record as steal-candidate #1 in `D-key-dispatch`. Bringing back a bar the
+framework *places* reopens this entry.
+
+**Prior art** (surveyed 2026-08-25; ⚠ marks memory-based claims worth checking
+before acting). The honest reading is that a framework-owned status *row* is a
+minority position, and the one framework that does it well does not own the row:
+
+| | Owns a status row? | Where the text comes from |
+|---|---|---|
+| **Turbo Vision** | yes — `TStatusLine`, always present | declarative `TStatusDef` tables keyed by help context ⚠ |
+| **Textual** | no — `Footer` is a widget you mount | the framework's `BINDINGS` tables ⚠ |
+| **Swing** | no | app-written `JLabel` in `BorderLayout.SOUTH` |
+| **ncurses / Bubbletea / Ratatui** | no | app draws every cell |
+| **Tuile (before)** | yes — `ScreenPane#status_bar` | `active_window&.keyboard_hint` + registry hints + `"q quit"` |
+| **Tuile (after)** | no | app-drawn, from `on_focus_changed` |
+
+Turbo Vision is the only real precedent for the shipped design, and it paired
+the row with a declarative binding table — the half Tuile never had, which is
+why its bar could only be fed by an inverted registration hack.
+
+**The scar.** The status bar was never designed for Tuile. It arrived whole in
+`4491a77`, the 0.1.0 commit that ported virtui's `lib/ttyui/` under the `Tuile`
+namespace — it was *virtui's* status bar, generalized by accident of extraction,
+and virtui is to this day the only app using the `keyboard_hint` half. It then
+survived every later overhaul (the top-down layout rewrite, the key-ladder
+deletion, the tree-first split) without anyone asking who it was for, while each
+new widget dutifully grew a hint nobody could see. The tell sat in the code the
+whole time: `Screen#active_window` was public API with exactly one caller —
+this one — and no app ever invoked it.
+
+---
+
+## D-quit-key — `q` / ESC quit the loop, unadvertised, as a Tuile quirk (2026-08-25)
+
+**Status:** Accepted 2026-08-25; no code change — this records a decision to
+*keep* what ships. Closes the question `D-status-bar` deferred.
+
+**Context.** `Screen#event_loop` ends with
+`@event_queue.stop if !handled && ["q", Keys::ESC].include?(key)` — after the
+three-rung ladder has declined a key, bare `q` or ESC stops the loop and the
+app exits. It is app policy the framework enforces, and no app opted into it.
+
+`D-status-bar` deleted the framework status bar and with it the hardcoded
+`"q quit"` prefix that was this fallback's only advertisement, deliberately
+leaving the behavior alone as a separate question. That left the least coherent
+state of the three: a hardcoded quit key with nothing anywhere surfacing it.
+
+**Decision.** Keep it exactly as it is, unadvertised, and stop treating it as an
+open question.
+
+- **It is a convention, not an invention.** `q` quits `less`, `man`, `top`,
+  `htop` and every pager git shells out to; ESC dismisses. A user arriving at a
+  full-screen terminal app already tries both. That is the same argument that
+  settled the popup's lost `q Close` hint in `D-status-bar` — a convention the
+  user brings is not something each app must teach.
+- **The escape hatch already exists and needs no new surface.** A component
+  keeps `q` by consuming it, which is the whole of `D-key-dispatch`'s
+  delivery rung: a focused {Component::TextField} does it for free (`q` is
+  printable — this is why pikuri-tui's shells never quit on a typed `q`), and an
+  app wanting `q` as a command binds it in the scope root's `handle_key`. ESC
+  likewise never reaches the loop while a {Component::Popup} is open, because
+  the popup consumes it first.
+- **It is genuinely useful for the small app.** `examples/hello_world.rb` is
+  eleven lines and needs no quit handler. Deleting the fallback would make every
+  example and both downstream apps grow one, buying nothing.
+
+**Alternatives rejected.**
+
+- *Delete it; apps handle their own quit.* The clean-architecture answer, and
+  the one consistent with deleting the status bar. Rejected because the two are
+  not the same shape: the status bar was a *row the app could not write to* —
+  it actively blocked apps (pikuri had to re-register a keybinding to change
+  text) — whereas this fallback blocks nothing. Any component can take the key.
+  A rule the app can override on the spot is a default, not a policy.
+- *Make it opt-in (`Screen#quit_on_q=`).* Adds framework surface for a knob
+  nobody has asked for, in the middle of an argument for less of it, and the
+  override it provides is one the key ladder already gives for free.
+- *Re-advertise it somehow.* That is the framework-owned status row again.
+
+**Consequences.**
+
+- **It is undiscoverable from inside the app**, and that is accepted. An app
+  that wants it spelled out writes `q quit` into its own status line —
+  `examples/hello_world.rb`, `examples/file_commander.rb` and virtui all do;
+  pikuri-tui deliberately does not, because its focused input eats `q` and the
+  hint would be a lie.
+- **`q` is reserved-ish for a scope root.** An app binding bare `q` in
+  `handle_key` must return `true`, or the key falls through and quits the app —
+  a surprising bug the book calls out (ch5) and this entry pins.
+- **What would reopen it:** a real app that needs bare `q` at the scope root and
+  finds consuming it awkward, or a second key wanting the same treatment (which
+  would make this a *list*, and a list wants a knob).