tuile 0.10.0 → 0.12.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):
@@ -785,18 +785,25 @@ will follow.
   the mixin's split says chrome is `caption`. Tuile has no field-label seam
   yet; when one lands, a checkbox's caption should stay what it is — the
   clickable target, not a caption *for* another widget.
-- **Space toggles; Enter is left unclaimed, but not *promised*.** Space-to-flip
-  is the native gesture (Vaadin's checkbox is Space-only too) and a checkbox has
-  no default action to confirm, so there is nothing for Enter to do here.
-  Claiming a key you don't need is the irreversible direction — teaching Enter a
-  meaning later breaks nobody, taking it back breaks apps — and that, alone, is
-  why `handle_key` ignores it. It is emphatically **not** a promise that a
-  form's Enter-to-submit can bubble past a focused checkbox: no widget owes
-  that (`TextArea` claims Enter for newline, `Button` to activate itself), and
-  book ch5's Enter table states it per widget precisely because it is per
-  widget. A checkable row in a `List` toggles on Enter (`D-checkbox-group`) —
-  `List`'s own *choose the item under the cursor*, not a checkbox gesture, so
-  the two don't read as inconsistent.
+- **Space and Enter both toggle** (Enter added 2026-08-03; unclaimed through
+  0.10.0). Space-to-flip is the native gesture (Vaadin's checkbox is Space-only),
+  and the original ruling left Enter alone on the grounds that claiming a key you
+  don't need is the irreversible direction. What tipped it is *consistency with
+  the group components*: a checkable row inside a `List` toggles on Enter, since
+  Enter is `List`'s own choose-the-item-under-the-cursor gesture
+  (`D-checkbox-group`, `D-radio-group`). So `[ ] Verbose` flipped on Enter when
+  it sat in a `CheckboxGroup` and did nothing when it sat alone in a form — a
+  distinction the user cannot see, and one that reads as a bug in the standalone
+  widget rather than as restraint. One gesture set, both shapes, is worth more
+  than the option value of a key a checkbox has no other use for.
+  The consequence is explicit and accepted: a focused checkbox now **consumes**
+  Enter, so an ancestor's Enter-to-submit does not see it. That was never
+  promised — no widget owes it (`TextArea` claims Enter for newline, `Button` to
+  activate itself), and book ch5's Enter table states it per widget precisely
+  because it is per widget (see the rejected reservation below, which is why the
+  promise doesn't exist to break). An app wanting Enter-anywhere-submits binds it
+  on the ancestor *and* accepts that its focusable widgets each get first refusal.
+  Now that Enter is claimed, taking it back is the breaking direction — don't.
 - **No constructor block, but a `value:` kwarg.** `Button.new(caption,
   &on_click)` and `PickerWindow` are the gem's only ctor blocks, and both exist
   to *produce one outcome* — the callback is mandatory in practice. A checkbox
@@ -854,7 +861,9 @@ will follow.
   `ListDropdown::Menu` shape — a non-focusable `List` subclass plus
   hand-forwarded movement keys — to protect a guarantee nothing relied on
   (`D-checkbox-group`). Enter-reaches-your-form is a per-assembly property the
-  app verifies for its own focusable widgets, not a framework invariant.
+  app verifies for its own focusable widgets, not a framework invariant. Still
+  rejected, and now moot in both directions: the standalone widget claims Enter
+  too, which is what made the two shapes agree.
 - *Hit-test the whole `rect`:* activates clicks that visibly land on nothing,
   and `Rect#contains?` spans every row, so a click two rows below a visible
   `[ ]` would toggle it. Vaadin agrees — a 100%-wide checkbox ignores clicks
@@ -995,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
@@ -1101,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.
@@ -1152,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
@@ -1197,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`
@@ -1265,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
@@ -1307,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.**
@@ -1860,7 +1869,13 @@ than sugar, since the composed label is what reads them — which is why both
 scale through one helper with exact endpoints (a full bar means done, and
 anything above zero lights a cell). And the bar is the first *animated*
 component, which is what turned an ordinary `super` in `repaint` into a
-measurable wire-traffic bug; AGENTS.md carries the resulting rule.
+measurable wire-traffic bug: `super` clears the background first, so
+`Cell#set` saw a real change on every cell of the bar and `flush` re-emitted
+the *entire* row five times a second instead of the one or two cells that had
+moved — **976 block glyphs per 1.2 s on the wire, versus 18** once the clear
+was scoped to the unpainted tail. That measurement is the evidence for the
+rule; AGENTS.md carries the rule itself ("never blank a cell you are about to
+paint over").
 
 ---
 
@@ -1931,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
@@ -1959,3 +1974,1265 @@ its row records keep character offsets and `chars_for_column` /
 plan the parked note assumed collapsed to one. Still out of scope and unfixed: a
 lone combining mark remains constructible via `text=` or by typing a mark into
 an empty field, which is input validation, not an axis question.
+
+---
+
+## D-float-field — `FloatField`: named for its Ruby type, and a deliberate copy of `IntegerField` (2026-08-07)
+
+**Status:** Accepted; implemented 2026-08-07 (`Component::FloatField`). The
+`Float` half of `D-integer-field`'s "derived parse" case — same wrapper shape,
+same taxonomy slot, so only what *differs* is recorded here.
+
+**Context.** Vaadin calls this a *Number Field*; the survey in
+`ideas/new-components.md` filed it as an "`IntegerField` twin". A second numeric
+field is where the naming rule and the shared-base temptation both had to be
+settled, because a third (`BigDecimalField`) is foreseeable.
+
+**Decision — name a typed field after the Ruby class its `value` is.**
+`FloatField#value` is a `Float`, so `FloatField`; `IntegerField#value` is an
+`Integer`. The name is then derivable rather than remembered, it says the
+precision out loud at the call site (`Float` is a binary double — the wrong type
+for money), and it leaves the obvious room for `BigDecimalField` /
+`RationalField`. `NumberField` was rejected: it names Vaadin's *widget*
+category, not this field's value, and it would force the eventual sibling to be
+"the other number field."
+
+**Decision — duplicate `IntegerField` rather than grow a base.** The two share
+~90% of their body (the `HasContent` shell, the `on_key` filter interceptor, the
+`fire_if_changed` guard) and differ in exactly the three places that matter: the
+filter, the parse, and the format. An `AbstractNumericField` with abstract
+`parse`/`format` hooks **is** the converter strategy `D-integer-field` kept out,
+reached through inheritance instead of a setter — and the `cop` rule is to
+duplicate rather than fold a shallow commonality into a base. The duplication is
+visible and boring; the base would be machinery.
+
+**Decision — the parse is lenient about partial buffers, the input filter is
+shallow.** `value` is a regexp-gated `String#to_f` — the private `NUMERIC`
+pattern: an optional sign, digits with an optional fractional part (either side
+may be empty, not both), an optional exponent. Not `Float()`, which raises on
+both `"1."` and `".5"`, so a `Float()`-based parse would blink the value to `nil` and back
+on the single keystroke between `"1"` and `"1.5"` — one spurious `nil` per
+decimal point, straight into every `on_value_change` listener. The regexp gate
+is what makes `to_f`'s garbage-tolerance harmless (it never sees garbage). The
+filter is correspondingly shallow — a digit anywhere, `-` only at index 0, `.`
+only if the buffer has none — so it keeps the buffer *typeable*, not always
+valid; `value` decides what parses. (`IntegerField` already worked this way: it
+lets a digit be typed before a leading `-`.)
+
+**Decision — the exponent is parseable but not typeable.** `Float#to_s` writes
+`1.0e-05` for extreme magnitudes, so `value = 1e-5` must read back — the parse
+accepts an exponent. No key types an `e`, though: admitting one would drag in
+"`-` after `e`" and break the "`-` only at index 0" rule for a notation nobody
+types into a form.
+
+**Decision — `value=` coerces with `Float()` and refuses a non-finite.**
+`Float::NAN.to_s` is `"NaN"`, which nothing parses, so writing one would make
+the field silently read back `nil` — a lost value with no error. It raises
+instead. Coercion also means `field.value = 3` shows `"3.0"`, which is the
+honest display of a `Float`-valued field.
+
+**Decision — Up/Down step by exactly `1.0`; there is no `step=`.** Same fixed
+spinner as `IntegerField`. A settable step is not free on a binary float:
+stepping by `0.1` accumulates `0.30000000000000004` straight into the visible
+buffer, so the knob would need a rounding policy (decimals? significant
+digits?), and rounding is formatting — a forms concern, parked with `min`/`max`
+in `D-integer-field`.
+
+**Alternatives rejected.**
+- *`BigDecimal` as the value type:* correct for money, but it needs the
+  `bigdecimal` gem, a decimals/scale policy, and `"0.1"` → `BigDecimal("0.1")`
+  string-round-tripping — a different field with a different name, not this one.
+- *Normalize the buffer on parse (`"007"` → `"7"`, `".5"` → `"0.5"`):*
+  rejected for the same reason as in `IntegerField` — canonicalizing needs a
+  blur/commit point a TUI lacks, and rewriting the buffer under the caret while
+  typing is worse than an ugly buffer.
+- *A locale decimal comma:* no locale seam exists in Tuile, and inventing one
+  for a single field would put i18n in the wrong layer.
+
+---
+
+## D-bigdecimal-field — `BigDecimalField`, and Tuile's first optional dependency (2026-08-07)
+
+**Status:** Accepted; implemented 2026-08-07 (`Component::BigDecimalField`).
+The third numeric field, so it inherits `D-float-field` wholesale (named for
+its Ruby value type, a deliberate copy rather than a shared base) — only the
+two things that are new are recorded here: exactness, and the packaging.
+
+**Context.** `D-float-field` closes with "the wrong field for money — hold that
+as `Integer` cents"; this is the field that makes the honest answer available.
+`BigDecimal`, though, is not a language built-in: it was a *default* gem
+through Ruby 3.3 and became a **bundled** gem in 3.4, so from 3.4 on a Bundler
+app must name it in its `Gemfile` or `require "bigdecimal"` raises.
+
+**Decision — ship it as an optional dependency, not a gemspec entry.**
+RubyGems has no optional/extras scope (no Maven `provided`, no Python extras),
+so the mechanism is convention: `lib/tuile/component/big_decimal_field.rb`
+carries the `require` itself, and Zeitwerk's laziness confines the cost — an
+app that never names the constant never executes the file. Three pieces make
+that hold, and all three are load-bearing:
+- The `require` is wrapped in a `rescue LoadError` that re-raises with the
+  actual fix (`gem "bigdecimal"`), since the bare message ("cannot load such
+  file") explains nothing about a gem that *is* installed but unbundled.
+- `loader.do_not_eager_load` on that one file, so a host app calling
+  `Zeitwerk::Loader.eager_load_all` — which Rails-shaped apps do — doesn't
+  raise on a component it never asked for. Pinned by a subprocess spec that
+  eager-loads everything and asserts `$LOADED_FEATURES` stays free of it.
+- The `require` **must not** be hoisted into `lib/tuile.rb` with the other
+  gem-level requires; that would impose the load on every user and defeat the
+  whole arrangement. This is the exception AGENTS.md's no-requires rule is
+  worded for.
+The accepted cost, stated plainly: the failure moves from `bundle install` to
+first use, so a missing gem surfaces mid-render in a raw-mode terminal rather
+than at boot. Worth it for one opt-in component; **not** a licence to make
+this Tuile's default posture — a second optional dependency needs its own
+argument.
+
+**Decision — normalize and format on both ends, rather than trusting
+`bigdecimal`.** Two of the three inputs behave differently across the versions
+Tuile supports: `bigdecimal` 3.1 (Ruby 3.3's default gem) *rejects*
+`BigDecimal("1.")` and `BigDecimal(0.1)`, while 4.x accepts both. So the field
+does its own work: a half-typed buffer is normalized (`".5"`→`"0.5"`,
+`"1."`→`"1"`) before parsing, and display goes through `to_s("F")` — plain
+notation, since `BigDecimal#to_s` writes `"0.1999e2"` for `19.99` and would put
+engineering notation in a form. The field's behavior is therefore identical on
+both, instead of tracking whichever parser the host resolved. Honest gap: the
+`Gemfile` resolves 4.x, so CI only ever exercises that one — 3.1 was verified
+by hand, and the normalization is what makes the difference unreachable rather
+than merely tested.
+
+**Decision — a `Float` is refused, not converted.** `field.value = 19.99`
+raises with a message naming the fix (`BigDecimal("19.99")`). The literal has
+already lost the decimal by the time it reaches the setter, and a field whose
+entire purpose is exactness should not be the place that quietly papers over
+it. That 4.x *would* accept it (via a shortest-round-trip conversion) and 3.1
+would not is the second reason: silently version-dependent precision is worse
+than a loud refusal. `Integer` and `String` coerce as normal.
+
+**Decision — the buffer is still never rewritten.** `"19.90"` keeps its
+trailing zero and `"007"` its leading ones, exactly as in the other two numeric
+fields: a display *scale* (pad to 2 decimals) is formatting, and formatting is
+the forms layer's, parked with `min`/`max`. Note the one place this shows
+through the value seam: `"1.0"`→`"1.00"` fires nothing, because the two
+`BigDecimal`s compare equal.
+
+**Alternatives rejected.**
+- *A hard `spec.add_dependency "bigdecimal"`:* makes every Tuile app carry a
+  gem for a component most won't use — and Tuile's dependency list is
+  otherwise TTY primitives and a loader.
+- *Accept a `Float` by converting through `to_s`:* that is a precision policy
+  ("shortest decimal that round-trips") hidden inside a setter. If it is ever
+  wanted, it belongs at the call site, where it is visible.
+- *A `scale=` / `decimals=` knob to pad the display:* it would have to rewrite
+  the buffer under the caret while typing (`19.9` → `19.90` mid-edit), which
+  needs a blur/commit point a TUI lacks — the same reason `D-integer-field`
+  gave for not normalizing.
+- *A settable `step=`:* `D-float-field` rejected it over binary-float noise,
+  which genuinely doesn't apply here (`BigDecimal` steps exactly). Kept out
+  anyway, so the three numeric fields stay one shape; this is the field to
+  revisit first if the knob is ever wanted.
+
+---
+
+## D-box-layouts — `Vertical` / `Horizontal`: declarative sugar with no `Auto` (2026-08-07)
+
+**Status:** Accepted; implemented 2026-08-07 (`Component::Layout::Box`,
+`::Vertical`, `::Horizontal`, and the `Fixed` / `Percent` / `Expand` / `Insets`
+value types on `Layout`). Book ch3 pre-approved the shape and named the
+acceptance criterion — "added if and when the convenience pays for itself" —
+so what this entry records is that it did, and every choice inside it.
+
+**Context.** `Layout::Absolute` was the only container: you override `rect=`
+and compute each child's rectangle. That is right for genuinely
+two-dimensional geometry and tedious for a stack. `examples/sampler.rb` carried
+**59 `Rect.new` sites**, dominated by vertical stacks with hand-accumulated
+offsets (`inner.top + 1`, `+ 4`, `+ 6`, `+ 8`, `+ 10`, `+ 12` in the
+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`.
+
+**Decision — the vocabulary is `Fixed` / `Percent` / `Expand`, and there is no
+`Auto`.** Shrink-to-fit is the bottom-up `content_size` channel deleted in
+v0.9.0, and AGENTS.md's re-grow rule allows measurement back only as an
+optional, caller-side query. So urwid's `PACK`, CSS `auto`, FTXUI's non-`flex`
+default and Swing's `GroupLayout.PREFERRED_SIZE` are all out by construction.
+**This single omission is what keeps the feature sugar rather than a reopened
+wound:** a box is an `Absolute` subclass with a `rect=` override — no new
+dispatch phase, no framework hook, no child consultation — so it deletes
+cleanly if it ever fails to earn its place.
+
+**Decision — alignment is legal because the cross extent is caller-supplied.**
+`align: :start | :center | :end` *looks* like it needs the child's width, which
+would be `content_size` again. It doesn't: it needs *a* width, and a `cross:`
+constraint provides one, so there is nothing to measure. This is the
+reframing that unblocked the cross axis after it had been parked as
+undesignable. Corollary: `:start/:center/:end` rather than
+`:left/:right` + `:top/:bottom`, because one concept should not have two
+vocabularies across the two classes.
+
+**Decision — `Expand`, not `Fill`.** Every toolkit that models *both* concepts
+reserves *fill* for cross-axis stretch, not for claiming slack: GTK's
+`pack_start(child, expand, fill, padding)` takes them as separate booleans and
+`fill` only acts when `expand` is already true; Swing splits them as `weightx`
+vs `fill`; JavaFX as `setHgrow` vs `fillHeight`. Vaadin 8 names only the first
+and calls it `setExpandRatio`. Naming our main-axis constraint `Fill` would
+therefore use the industry's word for cross-axis stretch — sitting right next to
+`Percent[100]`, the thing that actually stretches. `Expand` also leaves `Fill`
+permanently free, so it can never return as a confusing near-synonym. (ratatui
+does call it `Fill` and CSS `flex-grow`; neither models the stretch concept
+separately, so neither had the collision to avoid.)
+
+**Decision — defaults are `Fixed[1]` on the main axis and `Percent[100]`
+across it.** `Fixed[1]` because forms are the use case and almost every field is
+one row tall — the same reason Vaadin 8 bumps everything to the top by default.
+`Percent[100]` rather than `Expand[1]` because the cross axis holds exactly one
+child per slot, so nothing competes and a weight has nothing to mean there;
+**`Expand` therefore raises when passed as `cross:`**, which makes "what would
+`Expand[2]` mean across the axis?" unaskable rather than merely undocumented.
+JavaFX reached both defaults independently (`VBox.fillWidth` is `true`,
+alignment is `Pos.TOP_LEFT`).
+
+**Decision — `spacing` and `padding` are box-global, never per-child.** Beyond
+brevity: *a gap between two items is a property of the sequence, not of either
+child*, so a per-child gap has an unresolvable ownership question — does child N
+own the gap after it, or child N+1 the gap before it? Both conventions exist and
+both confuse. Non-uniform gaps are expressed by **nesting** instead: a
+`Vertical.new(spacing: 0)` inside a `Vertical.new(spacing: 1)` groups rows
+tightly within a looser stack, which *states* the grouping rather than faking it.
+`GridBagConstraints.ipadx`/`ipady` is the per-child version, and that class —
+eleven fields, and the layout manager everyone agrees is hardest to learn — is
+the named tripwire for this tuple growing past three.
+
+**Decision — `Percent` and `Expand` divide space that is actually available**
+(`extent - padding - spacing * (children - 1)`), so two `Percent[50]` children
+fit exactly instead of overflowing by the gap between them.
+
+**Decision — the weighted-`Expand` remainder goes to the earliest children, one
+cell each.** Five equal `Expand`s in 12 rows give `3,3,2,2,2`. Auditable in one
+sentence, exact sum structural (`base * n + remainder == total`), and leftmost-
+first is the ecosystem convention (CSS `flex-grow`, ratatui `Fill`, urwid
+`weight`) so a user coming from elsewhere guesses right.
+
+**Decision — over-subscription starves in declaration order; it never raises.**
+`Fixed` and `Percent` clamp to what is unassigned, so a child with nothing left
+gets an empty rect and paints nothing (`Rect#empty?` already covers zero *and*
+negative). Padding wider than the layout does the same to every child. No error,
+no solver, no reflow.
+
+**Decision — `Insets` is keyword-only.** `java.awt.Insets` orders the four
+numbers top-left-bottom-right and `javafx.geometry.Insets` top-right-bottom-left
+— the same class name and the same four numbers, silently different: a live
+migration bug between two toolkits *in the same language*. `Insets[top: 1]` has
+no order to get wrong. `Data`'s inherited `[]` never dispatches through a `new`
+override, so both class methods carry the guard (found by the spec, not by
+reading).
+
+**Decision — `Box` is a shared base, against the duplicate-don't-DRY rule.**
+`D-float-field` says duplicate rather than fold a *shallow* commonality into a
+base. This isn't shallow: the greedy pass is substantial and byte-for-byte
+identical except for which of `(left, top)` / `(width, height)` it reads, so
+`Box` parameterizes it behind two private hooks and `Vertical` / `Horizontal`
+are ~10-line concretes. That is the sanctioned cohesive base
+(`AbstractMasterDetail`), not an `AbstractView` junk drawer.
+
+**Alternatives rejected.**
+- *A constraint attribute on `Component` (`child.layout_constraint = …`):*
+  `content_size` wearing a hat. Even with the parent still doing the arithmetic,
+  it re-establishes "the child declares its size wish", and every non-layout
+  parent would have to ignore it. The constraint belongs to the parent–child
+  *relationship*, which is why it lives at the `add` call. **JavaFX is this
+  option in production and confirms the cost:** `HBox.setHgrow(node, …)` stores
+  the constraint on the node (hence `HBox.clearConstraints`), so you must recall
+  which container's static setter applies and a reparented node silently keeps
+  stale constraints.
+- *A block-valued cross constraint (`Left { |avail| [avail, 30].min }`):*
+  permitted by the re-grow rule, but no case needs it — `Fixed` already clamps to
+  available, which is exactly the `[inner.width, 30].min` the sampler wrote by
+  hand. A block is un-inspectable, awkward to spec, and `Absolute` remains the
+  escape hatch for a genuinely computed width.
+- *"Last `Expand` absorbs the remainder":* matches ch3's hand-written idiom and
+  guarantees an exact sum structurally, but degrades badly past two children —
+  five equal `Expand`s in 12 rows floor to 2 each and dump **4** on the last, a
+  visible 2× discrepancy, which is ch3's "one cell off is plainly visible on a
+  character grid" amplified rather than avoided.
+- *Trailing-first one-at-a-time (`2,2,2,3,3`):* same fairness, and it would match
+  ch3's remainder-to-the-right for the two-child case. Genuinely close; lost to
+  ecosystem convention. **Known consequence:** for two children the layout gives
+  the spare cell to the left/top while ch3's hand-written example gives it to the
+  right. Different mechanisms, no shared code; ch3 says so.
+- *Largest-remainder / Hare quota:* fairest, least auditable — reverse-
+  engineering which child got the extra cell is precisely the solver opacity ch3
+  rejects.
+- *Priority tiers instead of weights (JavaFX `Priority.ALWAYS/SOMETIMES/NEVER`):*
+  sidesteps remainder arithmetic entirely, but cannot express a 1:2 split, which
+  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.
+- *`BorderLayout` / `BorderPane` / Textual's `dock:`:* nesting
+  `Vertical(Fixed, Expand, Fixed)` covers it, and `ScreenPane` (content + status
+  bar) already *is* one, hard-coded.
+- *Swing glue (`Box.createVerticalGlue`, `createRigidArea`, struts):* invisible
+  filler *components*, needed only because `BoxLayout` has no per-child weight
+  and doesn't pack from the start. Packing from the start plus `Expand` needs
+  none, and grouped gaps are handled by nesting.
+- *Baseline alignment (Swing's `anchor` has `BASELINE`, `ABOVE_BASELINE_LEADING`,
+  …):* a text-*rendering* concept. Every row of a character grid shares one
+  baseline, so it is meaningless here.
+- *A full engine (Textual's CSS, Ink's embedded Yoga, ratatui's Cassowary
+  solver):* those frameworks must ship one — Ink and Textual are retained-mode
+  declarative, where the author never sees a rect, and ratatui's `Layout::split`
+  is the only way to obtain one. Tuile hands the author coordinates, so **once
+  `rect=` exists a layout is strictly optional sugar**, declinable per component,
+  which none of them can offer. (This nuances ch3's "validated by the ecosystem":
+  simple layout is validated by TUI *app architecture*, not by framework feature
+  sets.)
+
+**Consequences.**
+- Vaadin 8's perennial support question — *"`setExpandRatio` does nothing"*,
+  answered by "the child also needs `setSizeFull()`" — exists precisely because a
+  Vaadin 8 component has **both** its own size and an expand ratio: two size
+  channels that must agree. Tuile cannot have that bug, because there is no
+  component-side size to disagree with the constraint. The most common confusion
+  in the toolkit we took `Expand` from is a direct consequence of the channel
+  v0.9.0 deleted.
+- A future `Layout::Grid` should reuse `Fixed`/`Percent`/`Expand` verbatim per
+  row and column, as JavaFX's `ColumnConstraints(percentWidth, hgrow)` does,
+  rather than inventing a second vocabulary. That is also the path to the Form
+  Layout `ideas/new-components.md` wants — which is blocked on a field
+  label/helper seam, not on layout.
+
+---
+
+## D-wrap-leading-space — An indent is content; no flag, and no hanging indent (2026-08-12)
+
+**Status:** Accepted; implemented 2026-08-12 (`StyledString#wrap_one`). Fixes
+[issue #2](https://github.com/mvysny/tuile/issues/2). The continuation half —
+hanging indent — is deliberately deferred, see the last section.
+
+**Context.** `wrap_one` dropped a leading whitespace run whenever `line_w` was
+zero, which is equally true at the start of the *first* row as at the start of
+a continuation. So an indent never survived, even when the line fit the width
+and no wrapping happened at all. Since every `TextView` line goes through
+`wrap`, indented text could not be displayed: the downstream report was a
+nested agent/tool tree flattened into an ambiguous list, siblings and children
+indistinguishable and repeated leaf names reading as duplicates.
+
+**Decision — this is a bug, patched in place; no opt-in flag.** `wrap`'s own
+rdoc already promised the fixed semantics ("leading whitespace dropped on
+wrapped *continuations*"), so the code was not implementing a design, it was
+missing a condition. Every widely-used wrapper agrees, and they differ only on
+what happens to continuations — the half Tuile already had right:
+
+| Implementation | First-line indent | Continuation |
+|---|---|---|
+| Python `textwrap` (`drop_whitespace`) | kept — the docs carve it out explicitly | dropped |
+| CSS `pre-wrap` | kept | hangs past the margin |
+| GNU `fmt`, Emacs adaptive-fill | kept | **reused as the prefix** |
+| `fold -s` | kept (whitespace untouched) | kept |
+| Rust `textwrap`, Go wordwrap | kept (`initial_indent`) | `subsequent_indent` |
+
+CSS `white-space: normal` is the one that looks like a counter-example and is
+not: eating the indent happens in the **collapsing** stage, which also squashes
+every interior run to a single space. Tuile does not collapse (`"one  two"`
+keeps both spaces when they fit), so it is in the `pre-wrap` family, and doing
+half of collapsing — eat the indent, keep interior runs — was the incoherence.
+
+**A flag was rejected on three counts.** It has no defensible default
+(default-preserve is the patch plus dead config; default-drop keeps the bug
+reachable and makes every caller learn a piece of trivia); `TextView` calls
+`wrap` itself with the viewport width, so a flag on `StyledString#wrap` is
+useless until mirrored as a `TextView` setter, turning one wart into two knobs
+across two layers; and the blast radius of just fixing it is confined to
+strings whose first row opens with space or tab, with `TextView` the sole
+in-gem caller.
+
+**Decision — an over-wide indent is dropped, not given a row.** An indent that
+alone exceeds `width` folds into the same guard
+(`line_w.zero? && (!result.empty? || w > width)`) rather than falling through
+to the flush branch, which emitted an empty leading row. An indent wider than
+the viewport conveys no nesting, so losing it beats spending a row on it.
+
+**Decision — whitespace-only input is preserved, diverging from Python.**
+`plain("   ").wrap(5)` now returns `["   "]` rather than `[""]`. Python drops
+it (its rule is "not dropped *if non-whitespace follows*"), but matching that
+needs a lookahead and buys nothing visible: `TextView#pad_to` pads to width, so
+the two render identically. The simpler rule — the first row keeps its leading
+run, period — wins.
+
+**Deferred: the hanging indent.** A continuation still starts at column 0, so a
+leaf long enough to wrap re-lies about the tree — worse than the flattening,
+since a wrapped fragment of a deep leaf looks exactly like a new top-level
+entry. There is no app-side workaround (`TextView` owns the width and calls
+`wrap` internally, so a caller cannot wrap at `width - indent` and prefix). It
+is left out of this entry because it is a genuine behavior decision of its own:
+auto-inherit the first row's whitespace run as the continuation prefix, à la
+`fmt`/Emacs, versus an explicit knob that would again need mirroring on
+`TextView`. Current lean is auto with no flag — prose carries no leading space,
+so it is a no-op there, and the indented case is the only one with an opinion.
+
+---
+
+## D-select — `Select`: the enum field, claiming no printable key but Space (2026-08-12)
+
+**Status:** Accepted; `Component::Select` implemented 2026-08-12, demoed in the
+sampler. Builds on `D-has-value`, `D-combobox` (the chrome/value split and the
+resolve-don't-store-an-index rule, both adopted verbatim), `D-radio-group` (the
+cursor-is-chrome rule) and `D-ambiguous-width`.
+
+**Context.** A one-row closed-choice field: a face showing the selected item's
+label plus a `▾`, dropping open a `ListDropdown` of the options. `D-combobox`
+deferred it once ("filterable first"), on the assumption that it needed the
+read-only-field axis `D-has-value` parked for the forms layer. That assumption
+was an artifact of picturing a read-only `TextField` as the face; nothing gates
+this component.
+
+**Decision — the criterion is enum vs. data, not item count.** A Select is for
+labels the *developer* authored: a closed set, stable order, known when the code
+is written (log level, sort order, line endings, Yes/No/Ask). A `ComboBox` is for
+items the app supplies at runtime, open-ended, with labels you don't control
+(countries, users, branches). Count is a *symptom*: a 12-value enum is still a
+Select, and a three-row country list from a DB is still a ComboBox, because next
+release it is 200 rows and the widget choice must not have to change. The
+discarded rule — "≤ 7 items → Select" — is actively harmful: it invites that
+country list in, which is how the type-ahead hole below was found.
+
+**Decision — it claims no printable key but Space.** Enter, Space, ESC,
+`ListDropdown::MOVE_KEYS` and the mouse; *every other* printable bubbles past it
+to the app (key-dispatch rung 3). That is the capability unreachable by
+configuring a `ComboBox`, whose field eats printables unconditionally, and it is
+worth more than the type-ahead it replaces: a form's `s`-to-save and a layout's
+`1`/`2`/`3` pane jumps keep working while focus sits in a Select. Combined with
+having no caret — the strongest affordance a TTY has, not to be spent promising
+free-text entry over a four-value enum — that is the whole case for the
+component existing next to `RadioGroup`.
+
+Space is safe as the single exception because **it was never available as a
+bubble key anyway**: `Button`, `Checkbox` and `RadioGroup` all already claim it,
+so no app can rely on it reaching past an interactive widget. Contrast a letter
+like `g`, which reaches the app from every one of those and is exactly what the
+rule protects. Space mirrors Enter throughout (opens when closed, commits when
+open), as on `Button`/`Checkbox`; `RadioGroup` claiming Space but not Enter is
+inherent — it has no open/closed state to move between — not an inconsistency.
+
+**Decision — Home/End are declined, and `MOVE_KEYS` is unchanged.** They stay
+reaching the app, which `Screen::EDITING_KEYS` deliberately allows ("binding them
+app-wide to scroll the log pane is a real use case"). The PgUp/PgDn asymmetry is
+principled: those arrive *free* inside `MOVE_KEYS` and do real work on a dropdown
+that scrolls, whereas Home/End would need Select-side branches to do what a second
+arrow press already does. This also resolves what read as an open question in
+`ListDropdown`'s rdoc: the *exclusion* survives, the *rationale* doesn't — "they
+belong to the driving field, for caret movement" is a ComboBox policy, not a
+property of dropdowns. The driver decides, and both drivers decline.
+
+**Decision — `Select` paints its own row; it composes no field.** A leaf widget
+(`< Component` + `HasValue`, `tab_stop? = true`, no children) that owns the
+dropdown as an overlay. Two consequences worth naming:
+
+- **The face is *derived* from `value` at paint time, never a synced copy.** A
+  `Label` child would have meant a second copy of the face text to keep in step
+  from `value=`, `item_label=` and construction — the drift `ComboBox` pays for
+  only because its field is genuinely editable and holds a *query*. Nothing here
+  needs that, so nothing here has it. The well is read from the theme each paint
+  for the same reason.
+- **The tab-stop rule stays ordinary.** The composing wrappers (`ComboBox`,
+  `IntegerField`, the groups) leave `tab_stop?` false because their inner widget
+  carries the stop; a Select has no inner widget, so it claims the stop itself,
+  exactly as `Checkbox` does. Had the face been an (inert, non-tab-stop) `Label`
+  child, Select would have been the first composing wrapper needing to claim the
+  stop anyway — the letter of the rule reversed to preserve its purpose. Not
+  having the child removes the wrinkle instead of documenting it.
+
+**Decision — promote `ComboBox#anchor` to `ListDropdown#anchor_to`.** Select needs
+byte-identical vertical geometry, and `D-float-field`'s duplicate-don't-DRY rule
+**does not apply**: that licensed copying a *shell* around three genuine
+differences, whereas this is the same computation with zero differences, so a
+later fix to the flip rule would land in one copy and silently not the other —
+and the symptom appears only near a screen edge, which is invisible under test.
+The promotion threshold is the project's existing one (`D-color-slots`: "a
+*second* built-in needing the same thing"). Two rulings ride along:
+
+- **Width stays a caller-supplied parameter** (defaulting to the anchor's), so
+  `ComboBox` keeps its lines-up-with-the-field policy and Select keeps its
+  measured one, and `anchor_to` never measures content itself. Same shape as
+  `D-box-layouts`' "`align:` is legal only because the cross extent is
+  caller-supplied", and it keeps Select's measuring within the top-down re-grow
+  rule: an optional, caller-side query feeding a rect the caller then assigns.
+- **Horizontally we slide, vertically we flip.** Covering the driver would hide
+  the value being chosen, so vertically there are only above and below; sharing
+  the driver's columns is exactly what's wanted, so an overrun slides left and
+  keeps the left edges aligned. A horizontal flip would either overlap the face
+  or leave a gap. A label wider than the screen clips — `List` has no horizontal
+  scrolling.
+
+This is deliberately *not* the full anchored-Popover extraction, which wants
+generalizing for callers whose anchoring genuinely differs (a context menu
+anchors to a *point*, a submenu to a right edge with horizontal flipping). Build
+Popover when the second *kind* of anchoring appears, not the second caller of the
+same kind; `anchor_to` then moves down to it with nothing thrown away.
+
+**Decision — a scrolling `ListDropdown` gets a scrollbar** (a `ComboBox` fix
+shipped in the same work, and the only non-additive part of it). `anchor_to` owns
+the toggle, being the one place that knows both the row count and the height it
+just chose. *Rejected: an `:auto` mode on `List`.* It looks like the general fix
+and carries a silent corruption — visibility would become a function of
+`rect.height`, but the padded-line cache is rebuilt from `on_width_changed`, a
+width-only hook, so a height-only resize would flip the scrollbar, shrink
+`content_width`, and leave every row padded to the old width: one column off,
+no exception, nothing in the diff to notice. Making it safe means a height-change
+hook and a wider cache-invalidation surface for every `List` in the gem, to serve
+two callers that already know the answer.
+
+**Alternatives rejected.**
+- *Prefix type-ahead, single-key* (`g` jumps to the first item starting with
+  `g`): silently wrong. With Finland / Fiji / Jamaica, typing `fij` selects
+  *Jamaica* — each key is a fresh single-char match — and nothing tells the user
+  anything went wrong.
+- *Prefix type-ahead, timed accumulating buffer* (the standard GUI fix: `JList`,
+  GTK, Finder): it **is** the ComboBox query, hidden. A buffer that filters the
+  candidate set is a query string; concealing it and clearing it on a timer makes
+  it worse, not lighter, and reintroduces the second piece of state Select exists
+  to avoid. If you are holding query state, showing it is strictly better — and
+  showing it is a ComboBox. Worse here than in a GUI for a TUI-specific reason:
+  the timeout leans on inter-keystroke timing, and a terminal degrades exactly
+  that signal (bytes arriving in one read burst merge into a single key; a paste
+  has no gaps at all). Retiring type-ahead also retires the "make labels
+  prefix-unique" workaround that existed only to rescue it.
+- *Cycle-in-place* (`◂ Dark ▸`, Space/Left/Right, no popup) for 2–4 options: you
+  select blindly. The values you are choosing *between* are never on screen — you
+  discover them one at a time by cycling, with no way to see the set or know how
+  many there are. The dropdown is better at every item count, so the
+  `ListDropdown` face is the only face, and the vocabulary does not grow a fourth
+  closed-choice widget (cf. `D-box-layouts`' "there is no `Auto`"). *Re-grow
+  rule:* if it returns it is a **face** on this component (a `dropdown: false`
+  knob over the identical value seam), never a separate component, and it needs a
+  real argument about visibility rather than a row-budget one.
+- *A read-only `TextField` as the face* (the survey's framing): a read-only text
+  field is still a text field — the inherent-bg well, the caret machinery, the
+  horizontal scroll window, and an opt-out from `bg_color` inheritance. None of
+  it is wanted, and none of it has to be reasoned about once the widget paints
+  one row itself.
+- *A shared base with `RadioGroup`* (`AbstractClosedChoiceField`): the ~15-line
+  `items=` / `item_label=` / `label_for` shell is duplicated instead, per
+  `D-float-field`. The test is whether the commonality is a *shell around genuine
+  differences* or the *same computation* — `anchor_to` is the latter (extract), the
+  items shell is the former (duplicate). The three differences a base would have
+  to paper over with hooks: row rendering (`(*) label` glyphs vs. a bare label,
+  since a Select shows its selection on the *face*), cursor semantics (roams and
+  Space commits the row it's on, vs. the highlight *being* the pending selection),
+  and where the rows live (always, in the component's own rect, vs. only while
+  open, in a `Popup`'s). Three hooks over fifteen lines, reached through
+  inheritance, is the converter-strategy-by-inheritance shape `D-float-field`
+  rejected — and it would couple two widgets that should stay free to diverge.
+  This is the third copy of that shell, the same count `IntegerField` /
+  `FloatField` / `BigDecimalField` reached; a *fourth* is when to re-argue it.
+
+**Consequences.**
+- *Empty value* (`value = nil`, items present) is legal and normal — the optional
+  enum field — so there is no placeholder string: a blank face plus the `▾`, and
+  the dropdown opens with the highlight on row 0.
+- *Empty items* does not open a dropdown at all, keeping `ComboBox`'s auto-close
+  behavior: a 10-row empty tinted panel reads as a broken list rather than as
+  "nothing to pick". An item-less Select is almost always a programming bug, not
+  a state to design a UI for, so nothing is spent on it beyond not misleading the
+  user — no placeholder row, no "(no items)" label, no status hint. A
+  `Tuile.logger.warn` on the open attempt was considered and declined: the
+  attempt is keystroke-driven, so it would flood a host's log on autorepeat, and
+  an app may legitimately pass through item-less while loading. Enter/Space/Down
+  are claimed either way — one rule, no branch. (An item-less Select is arguably
+  a *disabled* field, which touches the read-only/disabled axis `D-has-value`
+  parked for the forms layer. Not designed here, not foreclosed either.)
+- The dropdown is measured to the widest label plus `List`'s **two** row gutters
+  (`pad_to_row` ellipsizes to `content_width - 2`, one leading and one trailing
+  column), plus the scrollbar column when the items outnumber the visible rows —
+  and never narrower than the Select itself. The field width is a *floor* rather
+  than an alternative to measuring: a panel narrower than its own face reads as an
+  unrelated widget instead of as that field's menu (a ~8-column menu under a
+  30-column field, in the sampler), so the common case lines both edges up exactly
+  as a `ComboBox`'s does and only an over-long label pushes it wider. A dropdown
+  the *screen* clamps shorter still scrolls without having bought the scrollbar
+  column, so its labels ellipsize one early — the `ComboBox` trade, in the one
+  case measuring cannot predict.
+- A second driver **confirms** three of `ListDropdown`'s speculative rulings
+  rather than straining them: ESC and Enter really do carry driver-specific tails
+  (Select's ESC closes without committing and has no query to revert), the
+  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.
+
+**Context.** A chat TUI keeps focus in the input field beneath its transcript,
+so the transcript's own scroll keys never fire: {Component::TextView#handle_key}
+opens with `return false unless active?`. 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)`).
+  Dead on arrival — the `active?` guard rejects it, which is the whole problem —
+  and a keystroke aimed at an unfocused widget is a lie about where focus is.
+- **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.
+
+## 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.