tuile 0.14.0 → 0.15.0

data/DECISIONS.md

@@ -117,9 +117,10 @@ chain. Self-painters route the effective bg through a single choke point,
 (`ideas/background-fill-color.md`) is retired; its invariants graduated to
 AGENTS.md ("Background color") and its reader-half to book ch6 ("Backgrounds
 are opt-in"). {Component::Label} already carried its own `#bg` (override-all
-via `with_bg`); it composes with `bg_color` (explicit span bgs survive
-`under_bg`, so `#bg` wins locally), but the two-knob overlap is a wart
-flagged for a later consolidation decision. The theme-token variant that
+via `with_bg`); it composed with `bg_color` (explicit span bgs survive
+`under_bg`, so `#bg` won locally), and the two-knob overlap was flagged here as
+a wart pending a consolidation decision — taken in `D_bg_surface`, which
+deleted it. The theme-token variant that
 surfaced during design landed separately — see `D_theme_ref`.
 
 ---
@@ -254,7 +255,7 @@ values *and* a uniform seam for free.
 
 **Alternatives rejected.**
 - *String-only value on every input:* fails "pick a domain object, get the
-  object," and bakes a `String` assumption a future `IntegerField`/`DatePicker`
+  object," and bakes a `String` assumption a future `IntegerField`/`DateField`
   would fight. Kept only as a theoretical fallback.
 - *A full Vaadin-shaped `HasValue`* (read-only, required-indicator,
   old-value/`isFromClient` event payload, converters/validators): every one of
@@ -398,12 +399,17 @@ moment to settle the input taxonomy while still pre-1.0.
 - **Value is a derived parse, fired eagerly.** `value` is recomputed from the
   buffer on read; `on_value_change` fires per keystroke but only on a real
   *value* change (`"7"`→`"07"` is silent). No normalization in v1 (`"007"`
-  shows as typed); canonicalizing needs a blur/commit point a TUI lacks.
+  shows as typed): rewriting the buffer under the caret while typing is worse
+  than an ugly buffer, so it would have to wait for a commit point. `on_blur`
+  is now that point (`D_on_blur`), which makes this re-openable on the merits —
+  it is no longer blocked on a missing hook.
 - **Up/Down are a built-in ±1 spinner**, treating an empty/un-parseable field
-  as `0`, handled inside the field's `on_key` interceptor. `IntegerField`
-  therefore does *not* expose `on_key_up`/`on_key_down` (`on_enter`, a submit
-  hook, stays delegated) — on a numeric field the arrows have a native meaning,
-  so surfacing them as app callbacks would fight the spinner.
+  as `0`. (Wired to the inner field's `on_key` interceptor originally; to its
+  `on_key_up`/`on_key_down` since `D_no_key_interceptor`.) `IntegerField`
+  therefore does *not* expose `on_key_up`/`on_key_down` *on its own face*
+  (`on_enter`, a submit hook, stays delegated) — on a numeric field the arrows
+  have a native meaning, so surfacing them as app callbacks would fight the
+  spinner.
 - **Both composed fields include `HasContent`.** `ComboBox` and `IntegerField`
   hold their inner `TextField` as their single `HasContent` child rather than
   hand-rolling `children`/`rect=`/`on_focus`. This reuses an *existing* mixin
@@ -442,8 +448,9 @@ what Java needs a class for, and `is_a?(HasValue)` is the Binder's marker.
 - `content`/`content=` are public on `ComboBox`/`IntegerField` (from
   `HasContent`) — a structural accessor, distinct from the typed `value` seam
   that stays the intended domain API.
-- The digit filter is the inner field's `on_key`, consulted *before* insertion,
-  so a rejected key never moves the caret.
+- The digit filter is the inner field's `insert_text` (originally its `on_key`,
+  which a paste bypassed — `D_input_filters`), so a rejected key never moves the
+  caret and a rejected paste lands nothing.
 - Empty is per-component: `nil` for `IntegerField`, `""` for a text input.
 
 ---
@@ -949,7 +956,8 @@ much of `List` to reuse and what the value should be. (A single-select group
 
 **Decision.**
 - **Compose a plain `List`, unmodified.** `CheckboxGroup` holds one as its single
-  `HasContent` child, which supplies the cursor, scrolling, the scrollbar and
+  child — read-only as `list` since 0.15.0 (`D_wrapping_field`), an app tunes it
+  but never supplies it — which supplies the cursor, scrolling, the scrollbar and
   per-row hit-testing. The group's own code is four lines of wiring: rebuild
   `lines=` on any change to items/labels/selection, claim **Space** in
   `handle_key`, and toggle from `on_item_chosen`. That one callback covers Enter
@@ -2003,7 +2011,7 @@ 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
+~90% of their body (the `HasContent` shell, the nested filtering `Field`, 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,
@@ -2048,11 +2056,20 @@ in `D_integer_field`.
   `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.
+  rejected for the same reason as in `IntegerField` — rewriting the buffer under
+  the caret while typing is worse than an ugly buffer, so it belongs at a commit
+  point, which `on_blur` has since become (`D_on_blur`).
 - *A locale decimal comma:* no locale seam exists in Tuile, and inventing one
   for a single field would put i18n in the wrong layer.
+  **Amended 2026-09-04 (`D_locale`):** the seam now exists, and
+  `Locale#decimal_separator` is detected and exposed — but the field still does
+  not read it, because that is field-side work this entry's own reasoning
+  constrains: `TYPEABLE` is an `insert_text` filter, so admitting `,` changes
+  what a pasted `"1,5"` does (today it lands nothing, deliberately, rather than
+  sieving to `"15"`), and `value=` writes through `to_s`, which is always a dot.
+  A comma grammar is still prefix-closed, so `D_input_filters` holds and the
+  work is tractable; it is simply not done. The member is one of the six
+  `D_locale` shipped ahead of its consumer.
 
 ---
 
@@ -2128,9 +2145,10 @@ through the value seam: `"1.0"`→`"1.00"` fires nothing, because the two
   ("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.
+  the buffer under the caret while typing (`19.9` → `19.90` mid-edit), so it
+  belongs at a commit point — the same reason `D_integer_field` gave for not
+  normalizing, and re-openable on the same terms now `on_blur` exists
+  (`D_on_blur`).
 - *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
@@ -2146,6 +2164,12 @@ 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.
 
+**Update 2026-09-04: an empty rect propagates, and a child can be re-placed.**
+`#relayout` no longer returns early on an empty rect of its own, `#add` takes
+`at:` and `#constrain` re-constrains a child already added — so hiding a pane by
+`#remove` is reversible, which is what keeps `Fixed[0]` a *collapse* rather than
+Tuile's answer to hiding. See `D_empty_ancestor`.
+
 **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
@@ -2568,6 +2592,10 @@ 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_mouse`'s keyboard-first ranking leaves this entry untouched.** The
+  dropdown is *enumeration* — options the user cannot type without seeing — not
+  a mouse affordance, and the no-printable claim is a keyboard argument; nothing
+  there demotes Select relative to `ComboBox`.
 
 ## D_list_items — `List` takes items + a renderer, rendered lazily (2026-08-14)
 
@@ -2845,10 +2873,11 @@ 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
+that already exists — `handle_text_input_key` in a 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.
+doesn't claim it. The recipe lives in the `TextArea` rdoc. (The entry originally
+offered the `on_key` interceptor as a no-subclass alternative; it is gone, and
+the readers are public, so a subclass is the one route — `D_no_key_interceptor`.)
 
 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
@@ -2859,9 +2888,10 @@ the auto-growing prompt strip — the case the name was reserved for — uses
 - **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
+  makes. Rejected on five counts. It would be a *third* key-interception
+  mechanism in a class that already has two (`handle_text_input_key` and the
+  rung-3 ancestor bubble; `on_key` was a third until
+  `D_no_key_interceptor`), 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
@@ -2873,7 +2903,7 @@ the auto-growing prompt strip — the case the name was reserved for — uses
   `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
+  subclass, where the readers serve any caller. 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
@@ -3311,8 +3341,8 @@ 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
+to `handle_paste`, 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
@@ -3320,6 +3350,21 @@ 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.
 
+**Amended 2026-09-03 — delivery is to the focused component, and stops there.**
+`ScreenPane#handle_paste` originally walked the focus chain the way
+`bubble_key` does, offering the text to each ancestor in turn. That was
+symmetry for its own sake. The three reasons a *key* bubbles (`D_key_dispatch`)
+are all about a scope-wide **binding** — a form's default button, a layout's
+one-key jumps, and the modality that falls out of stopping at the scope root —
+and none of them has a paste analogue: "the ancestor gets the clipboard the
+field declined" is not a feature, and no component in the gem but
+`AbstractStringField` overrides `handle_paste`, which is always the innermost
+component on the chain when it matters. The scoping is kept (focus outside the
+modal scope still receives nothing, so a modal stays modal); only the walk is
+gone. This is a **narrowing**, so the re-grow bar is low if a real ancestor-level
+paste consumer ever appears — but the replay-as-keys fallback rejected above
+stays rejected, which is the part that would actually hurt.
+
 **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
@@ -3338,8 +3383,8 @@ 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
+`TextField#preprocess_paste` narrows further — the newline ruling is its own
+entry (`D_paste_newlines`), 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.
@@ -3395,8 +3440,14 @@ 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) }
+    clear_outside_extent unless children.any? && children_tile_rect?
+    invalidate_children
+
+**Update 2026-09-04:** the second line is a named protected method rather than
+an inline `children.each`, so a container that skips `super` to paint its own
+rect has something to call — `Component::Window` skipped the clear it did not
+need and lost the cascade in the same edit, twice, because the cascade had no
+name (`D_component_contract`).
 
 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
@@ -3440,6 +3491,13 @@ 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).
 
+**Update 2026-09-05: the re-grow rule below has been met.** `D_visibility`
+brings `Component#visible=` back as the full focus-and-paint gate this entry
+asked for, with the `Box` arithmetic ruled, on the conditional form field as the
+second consumer. `TabSheet` keeps detaching regardless — the lifecycle hooks on
+switch are a feature — so the *decision* here stands; only the "Tuile grows no
+visibility flag" clause is superseded.
+
 **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
@@ -4531,8 +4589,9 @@ open question.
 ## D_hook_visibility — A framework-invoked hook is protected, reached with `__send__` (2026-08-30)
 
 **Status:** Accepted and implemented for {Component#on_theme_changed}
-(protected; `Screen#theme=` fans it out through `__send__`). `Component#on_focus`
-is the one framework-invoked hook still public — see *Consequences*.
+(protected; `Screen#theme=` fans it out through `__send__`) and for
+{Component#on_blur} (`D_on_blur`). `Component#on_focus` is the one
+framework-invoked hook still public — see *Consequences*.
 
 **Context — the field report.** virtui crashed on an OS appearance flip:
 
@@ -4620,10 +4679,11 @@ of bug never reached them.
   sense. {Component::HasContent} / {Component::Layout} / {Component::TabSheet}
   each override it to forward focus into their content, so it reads as part of
   the composition seam a mixin publishes rather than as a private notification.
-  It carries the same theoretical hazard (an app narrowing its override would
-  break `Screen#focused=`), and that is accepted: nothing has hit it, and
-  protecting a method three mixins present as interface would cost more clarity
-  than it buys.
+  Its narrowing hazard is nevertheless **gone**: `Screen#focused=` sends it with
+  `__send__` since `D_on_blur`, because a *protected* `on_blur` beside it makes
+  the fatal grouping likely rather than theoretical. Public-and-`__send__`-ed is
+  the combination for a hook that is genuinely interface; the rule above is for
+  the rest.
 - **Specs call the hook with `send`**, and two guards exist: `component_spec`
   asserts the visibility pair, `screen_spec` asserts that a subclass declaring a
   `protected` override is still fired *and* that the walk continues past it.
@@ -4815,9 +4875,10 @@ is a wash; what is bought is that an offset extent cannot be written.
 ## D_final_tree — `children` and `parent` are final; no shadow tree (2026-08-30)
 
 **Decision.** `children`, `parent`, `parent=`, `add_child`, `remove_child` and
-`detach_child` may not be overridden. `Component.verify_final!` resolves each
-one and compares its `owner`, raising `Tuile::Error` from `Component#initialize`
-when a subclass has taken any of them. Checked once per class and memoized.
+`detach_child` may not be overridden. `Component` declares them through
+`Tuile::Final`, whose `verify_final!` resolves each one and compares its
+`owner`, raising `Tuile::Error` from `Component#initialize` when a subclass has
+taken any of them. Checked once per class and memoized.
 
 **Why a runtime check rather than the existing prose.** `D_tree_api` already
 said "never override `children`" and `component_spec` already walked a tree of
@@ -4830,6 +4891,25 @@ is attached but never painted, a lifecycle hook fired for the wrong set, and a
 click that never reaches a widget the tree still lists. Nothing raises; the
 widget is just dead.
 
+**Amendment (2026-09-01): extracted to `Tuile::Final`.** The first cut fused the
+mechanism with this one rationale — a `FINAL_METHODS` constant plus a
+`verify_final!` whose raise recited three sentences about `attached?` and the
+parent chain. That message is nonsense printed for any *other* final method, and
+the fusion was noticed while weighing a second group (`bg_color` /
+`effective_bg_color`, so an app can't override the reader the framework reads).
+So the mechanism is now Ruby's missing `final` keyword and nothing more: a class
+`extend`s `Tuile::Final`, marks its methods, and the raise points at the
+offending method's own rdoc, which is where each *why* lives. Enforcement is
+unchanged — the resolved-`owner` check from `initialize`, memoized per class.
+
+*Declared in one call, not on each `def`.* `final def foo` parses (a `def` hands
+back its name) and reads like Java, but YARD has no handler for the macro, so
+the decorated `def` loses its parameter list and sord generates
+`def foo: () -> void` into `sig/tuile.rbs` — measured, not feared: it dropped
+`add_child`'s two parameters and both `attr_reader`s outright. CI's `sig/` drift
+gate catches the *change*, but a newly-added `final def` would just be committed
+with an empty signature. So the names are listed once near the top of the class.
+
 The check earned itself immediately: `component_spec`'s own `container_with`
 helper built its fixtures with `define_method(:children) { kids }`, i.e. the gem's
 test suite was faking the tree it was asserting about. That is now real
@@ -5420,3 +5500,3063 @@ for the 16 named colors, which a terminal's own scheme may redefine — the one
 mapping here that can be honestly wrong. It is documented on `Color#quantize`,
 and the result is a *named* color (SGR `30..37`/`90..97`), so the user's scheme
 still decides what is finally drawn. `TERM=linux` is about the only consumer.
+
+---
+
+## D_scrollbar_reserve — `TextView` reserves a blank column beside the bar; no knob, and not called a gutter (2026-09-01)
+
+**Status:** Accepted; implemented 2026-09-01 (`TextView#scrollbar_columns`).
+Fixes [issue #9](https://github.com/mvysny/tuile/issues/9).
+
+**Context.** With `D_status_bar`'s borderless panes, a `TextView` scrollbar sits
+at the pane's outermost column and text runs straight into it: `wrap_width` was
+`rect.width - 1`, `rewrap` padded every row to exactly that, and `paintable_row`
+concatenated the glyph onto the padded row, so a row wrapping at the full width
+put its last character in the column immediately left of `█`:
+
+```
+  enough that it must wrap against the pane edge to show the█
+```
+
+Inside a `Window` the gap came free from the border, which is why this survived
+to 0.14.0 unnoticed — and why no spec caught it: every scrollbar example in
+`text_view_spec` used content far shorter than the viewport.
+
+**The deciding fact: `List` already reserved it.** `List#pad_to_row` ellipsizes
+the body to `content_width - 2` and pads `" " + body + " " * (fill + 1)` — the
+"two row gutters" `D_select` measures a dropdown against — so a `List` row has
+never touched the bar. The two components only look alike at `paintable_row`.
+That reframed the request from "a new option on two components" to "`TextView`
+is inconsistent with `List`", in the direction the reporter already preferred.
+
+**Decision — always reserve, no option.** `scrollbar_columns` returns the
+columns the bar claims (`0` hidden, else `2`), `wrap_width` subtracts it and
+`paintable_row` emits the blank before the glyph. An `Integer` knob defaulting
+to `0` was the issue's own first proposal and was rejected: it would only ever
+hold `0` or `1` (a boolean wearing a number), it has no defensible default once
+`List` is known to reserve unconditionally, and it is the per-child tuple growth
+`D_box_layouts` refuses — a gap between two things is a property of the pair,
+not a parameter of one. Both affected methods are private, so nothing public
+changes; existing apps rewrap one column narrower wherever a bar is visible,
+which is invisible inside a `Window` and is the fix everywhere else.
+
+**Decision — the name `gutter` is unavailable.** The word was already spent
+twice in this tree, in the two incompatible industry senses: `List`'s
+"one-column gutter" is the blank pad (the CSS-Grid/Bootstrap *gap* sense), while
+`list.rb`/`text_view.rb` said "minus the scrollbar gutter" for the bar's own
+column (the CSS `scrollbar-gutter: stable` sense, where the gutter *is* where
+the bar goes; editors add a third — VS Code's gutter *contains* line numbers).
+So `scrollbar_gutter` would have been a third meaning contradicting a rdoc
+sentence six lines above it, which `D_scroll_nomenclature`'s one-word-per-concept
+rule forbids. The rdoc uses of the bar-column sense were reworded to "the
+scrollbar column", leaving the blank-pad sense as the only surviving one. Had an
+option shipped, the name would have been `scrollbar_spacing` — `spacing` already
+means "gap between two things" here (`Box#spacing`).
+
+**The reserve drops below width 3.** At `rect.width == 2` a bar plus a blank
+leaves no column for text at all, so `scrollbar_columns` returns `1` there and
+at width 1. That keeps `paintable_row`'s "exactly `rect.width` columns"
+contract — the thing the whole paint path rests on — true at every width, which
+is the part a naive `- 2` would break silently.
+
+**Not an AGENTS.md invariant.** The reserve lives entirely inside
+`text_view.rb`; no contributor can break it from another file, so it stays in
+that file's rdoc under the gate at the top of AGENTS.md.
+
+---
+
+## D_bg_surface — A component's own background: `default_bg_color`, keyed by state (2026-09-01)
+
+**Status:** Accepted; implemented 2026-09-01. Closes
+[issue #11](https://github.com/mvysny/tuile/issues/11). Extends `D_bg_inherit`
+and `D_theme_ref`, which built the inheritance chain but left no level for a
+widget's *own* surface.
+
+**Context.** `Component#bg_color=` documented itself as tinting a component and
+its subtree, and `#effective_bg_color` as "the background actually painted".
+Neither held for an editable field: `AbstractStringField#background` reached
+past the chain to `screen.theme` directly, so a `TextField` ignored an inherited
+tint *and* ignored a `bg_color` set on itself — the value was never read on the
+paint path. Six widgets did some version of that reach-around
+(`AbstractStringField`, `Select`, `ComboBox`'s `▾`, and the focus accent in
+`Button` / `Checkbox` / `Tabs`), which is why AGENTS.md had to describe "three
+camps, don't mix them" with a standing prohibition — *inherent-bg widgets must
+not set `bg_color`* — on the third.
+
+Diagnosis: the chain was missing a level. There were three questions and only
+two names. *What's behind me?* was `effective_bg_color`; *does the app want to
+override it?* was `bg_color`; **do I paint an opaque surface of my own, and in
+what color?** had no name, so every widget that needed one reached *around* the
+chain instead of contributing *to* it.
+
+**Decision.** Add the missing level as a protected hook, and let the app's
+answer at any level be keyed by component state.
+
+```
+effective_bg_color = @bg_color || default_bg_color || parent.effective_bg_color
+```
+
+- `default_bg_color` is protected, `nil` by default ("no surface of my own"),
+  and overridden by the widgets that paint one. A non-nil answer terminates
+  inheritance, which is what keeps a form's fields looking like fields inside a
+  tinted panel.
+- `bg_color` (and `default_bg_color`) accept a `Hash` keyed by `BG_STATES`
+  (`:normal`, `:active`) beside a `Color` / `Theme::Ref`. A missing key is not
+  answered at that level and falls through, so `{ active: blue }` means "keep my
+  own well, override the focus shade" and a flat `Color` means flat in every
+  state.
+- `effective_bg_color` becomes protected and final; `bg_color` stays the one
+  public knob.
+- `clear_outside_extent` blanks with a private `ambient_bg_color`
+  (`@bg_color`, else the parent's `effective_bg_color`), skipping the widget's
+  own default: outside its extent the widget is not there.
+- `AbstractStringField#background` is deleted; the text fields paint through
+  `draw_text` like every other self-painter.
+
+**Why a state map rather than picking one focus behavior.** The narrower
+question was where a field's focus highlight lives: *inside* the hook
+(`active? ? active_bg : input_bg`, so an app tint replaces the shade too) or
+*outside* it, as a `with_bg` layer over whatever resolved (so the shade
+survives a tint). Each solves half the problem. Inside, `select.bg_color = X`
+silently removes the *only* focus indicator a `Select` has — it paints no
+caret. Outside, an app can never produce the flat, focus-invariant surface that
+motivated the issue, and the mechanism covers only the widgets that happen to
+paint a well.
+
+The state map subsumes both, and turns the hole in the first option into a
+choice: pass a flat color and you get a flat surface; pass a pair and you keep a
+shade of your own choosing. It is also the shape the hook already wanted — one
+channel answering "what color for the state I am in" — where the layer variant
+needs a second, un-settable channel beside it.
+
+**Why this is not the CSS road.** The reflex objection was that state keys are
+pseudo-classes. They are not: what makes CSS CSS is selectors matching across
+the tree, plus specificity, plus the cascade. A small closed set of states,
+resolved on the component itself, is **Android's `ColorStateList`** — a bounded,
+well-regarded design. The guardrails that keep it there, all enforced or
+recorded: the key set is framework-defined and the setter raises on anything
+else; a key is added only when Tuile grows the *state* (hence no `:disabled`
+today — there is no disabled state, no `enabled?`, no focus-skipping and no
+theme token, and a key promising one would be a lie); and a `Hash` resolves
+against **its owner's** state only, never a descendant's.
+
+**Naming.** `normal:` over `inactive:` — a state set names its base state
+positively, or the day `disabled:` arrives `inactive` reads as a superset of it.
+`default:` was unavailable: "terminal default" is load-bearing vocabulary in
+exactly this area.
+
+**Alternatives rejected.**
+- *Override the `bg_color` **reader*** in `AbstractStringField` (`super || well`)
+  — a two-line fix needing no new API. Rejected on three counts: the reader
+  stops meaning "what the app set", which is the test the framework needs to
+  distinguish an app tint from a widget well; that distinction is exactly what
+  the dead-tail rule requires, so recovering it means reading `@bg_color` around
+  your own accessor; and a widget's private well silently becomes a subtree tint.
+  `bg_color` / `bg_color=` / `effective_bg_color` are marked final partly to
+  foreclose this route.
+- *A public `opaque=` flag* (default false, true on fields, app-flippable). It
+  found something real — a per-instance opt-out, unreachable today without
+  subclassing — but the name imports the compositing model `D_bg_inherit`
+  refused, and collides head-on with the standing "terminal cells are opaque".
+  It is also a no-op on any component with no `default_bg_color`, and dead in
+  combination with a set `bg_color`. The capability itself was real, and landed
+  the same day as the sentinel this note called for — see the amendment below.
+- *A `bg_color=` forwarded from a composed field to its inner one*
+  (`super; content.bg_color = color`) — illegal, since the setter is final, and
+  unnecessary: the composer owns the well and marks its face `BG_INHERIT`
+  instead, which also deletes the duplicated `active? ? … : …` the `ComboBox`
+  `▾` was carrying.
+- *Migrating `Button` / `Checkbox` / `Tabs` / `MenuBar` / `List` onto the hook.*
+  Expressible — `{ active: active_bg_color }` with no `:normal` key is exactly
+  their behavior — but deliberately not done here. Their accent is `with_bg`
+  (override-all) where the chain is `under_bg` (fill-unset), so an app-styled
+  caption span would start surviving the highlight; and for `Tabs` / `MenuBar` /
+  `List` the accent covers a *segment or row*, not the component, which the
+  per-component hook cannot express at all. A separate call, on its own merits.
+
+**Consequences.**
+- AGENTS.md's "three camps" becomes two, and the prohibition on a well widget
+  setting `bg_color` is gone — that is the bug, not the rule.
+- `Select#face_row` no longer stomps span backgrounds with `with_bg`, so an item
+  label carrying its own background now keeps it.
+- A new composed field owes a `default_bg_color`, or its face paints untinted;
+  a new widget with a well owes one plus an `extent`, or its dead tail lies.
+- The hook must not allocate: `TextArea` resolves the chain once per painted
+  row, so a `Hash` built per call would put an allocation on the repaint path.
+  Branch on `active?` and return one `Color`.
+**Amendment (2026-09-01): `BG_INHERIT`, and ownership is told, not inferred.**
+The first cut had `AbstractStringField#default_bg_color` return `nil` when
+`parent.is_a?(HasValue)` — the leaf working out for itself whether a composed
+field owned its surface. That was wrong in both directions, and it was
+positional where the question is structural:
+
+- *False negative.* Anything inserted between composer and field — a `Layout`,
+  a `Slot` — makes the parent something else, the field reclaims its well, and
+  the composer's `bg_color` goes inert over the field's cells again. Issue #11
+  resurrected by a refactor with nothing to do with backgrounds.
+- *False positive.* An app composite that happens to include `HasValue` and
+  holds a `TextField` alongside other widgets silently loses a well it wanted,
+  with nothing saying why.
+
+So the owner says it out loud. `Component::BG_INHERIT` (the Symbol `:inherit`)
+assigned to `bg_color` means **skip my own `default_bg_color`, take what
+surrounds me** — CSS's `background: inherit`. Each composer marks its face
+(`field.bg_color = BG_INHERIT`) at construction and declares the well itself;
+`AbstractStringField#default_bg_color` is unconditional again. `spec` pins both
+halves, including a `Layout` inserted between composer and field, which is the
+case the old rule failed.
+
+*Why the sentinel rather than a marker flag.* It is the opt-out the `opaque=`
+alternative above was groping for, and it serves a **second** caller: an app
+making a field sit flush in a tinted panel writes `field.bg_color = BG_INHERIT`
+rather than repeating the ancestor's `Theme::Ref` or subclassing (the pikuri
+prompt that opened issue #11). One property, no dead combinations, no no-op on
+components without a default. `nil` keeps its own distinct meaning — fall
+through to `default_bg_color` *first* — so the two are not redundant.
+
+*What it costs.* `ambient_bg_color` owes the same `BG_INHERIT` check as
+`effective_bg_color`, or the dead tail paints the literal `:inherit`. And the
+mark and the override are a **pair**: measured on 2026-09-01, dropping the
+composer's `default_bg_color` while keeping the mark leaves the face with no
+well at all (`nil`, a ComboBox reads as plain text); dropping both puts the
+inner field's own well back and makes the composer's `bg_color` inert over it
+(`IntegerField` entirely so) with the `▾` alone taking the tint. Neither is
+caught by the numeric fields' specs, which assert nothing about their well.
+
+*Named, not chosen:* `TRANSPARENT` — accurate about the effect, but it imports
+the compositing model `D_bg_inherit` refused and collides with the standing
+"terminal cells are opaque". `INHERIT` is the house word (this section is
+"Background color (opt-in, inherited)") and matches CSS. A bare Symbol is safe
+where `D_theme_ref` rejected one for `Theme::Ref`: that objection was
+ambiguity with `Color.coerce`'s ANSI colour *names*, and `:inherit` is not one.
+
+- **`Label#bg` is deleted** (the wart `D_bg_inherit` flagged and parked). It
+  predated the chain and did two things: fill behind the text, the trailing pad
+  and the blank rows — which is exactly `bg_color` now, down to the padding,
+  since `Label#repaint` routes every row through `draw_text` — and *stomp* a
+  span's own background via `with_bg`. Only the second was unique, and it is a
+  restyle of the text rather than a property of the component, so it belongs on
+  the text: `label.text = text.with_bg(c)`. Migration is `label.bg = c` →
+  `label.bg_color = c`, plus the `with_bg` above only if the text carries span
+  backgrounds you meant to override. Keeping it would have left two spellings of
+  "this label's background" that differ only in an edge case, one of them
+  invisible to inheritance, `Theme::Ref` and the state map.
+
+---
+
+## D_scrollbar_ink — The scrollbar's ink: a theme token, and no handle when nothing scrolls (2026-09-01)
+
+**Status:** Accepted; implemented 2026-09-01 (`Theme#scrollbar_color`,
+`VerticalScrollBar#scrollbar_char`, `VerticalScrollBar.handle_char=`). Fixes
+[issue #10](https://github.com/mvysny/tuile/issues/10). Sits beside
+`D_scrollbar_reserve`, which fixed the bar's *geometry* from the same borderless
+pane work; this fixes its *ink*.
+
+**Context.** `scrollbar_char` returned a bare `█` / `░` and both call sites —
+`List#paintable_row` and `TextView#paintable_row` — wrapped it in
+`StyledString.plain`, so the bar painted in the terminal's **default
+foreground**: on a dark scheme, near-white. And it was loudest exactly when it
+said least, because `row_count <= height` sets `handle_height = height`: a
+full-height, 100%-ink column carrying no information at all. Inside a `Window`
+this read as chrome; in a borderless pane (`D_status_bar`'s panes, a
+`LogTextView`) it became the loudest thing on screen, with `scrollbar_visibility
+= :gone` — trading the whole indicator away — as the only lever.
+
+The two halves are independent, and only one of them needs a theme.
+
+**Decision — no handle when there is nothing to scroll, and that is an *ink*
+rule.** `scrollbar_char` returns the track glyph at every row when
+`row_count <= height`. The handle geometry readers still report the covering
+handle; what changed is what gets drawn. This matters because the issue asked
+for it as an `:auto` **visibility** mode, which `D_select` refuses and still
+refuses: making visibility a function of `rect.height` makes `content_width` /
+`wrap_width` a function of `rect.height` too, while the padded-row cache is
+rebuilt from the width-only `on_width_changed` — a height-only resize would
+leave every row one column off, silently. Going quiet inside the *glyph* touches
+none of that: `scrollbar_visible?` stays true, the column stays reserved, the
+wrap width never moves (pinned by a spec in each component). So the request is
+granted without reopening the ban, and the two must not be conflated later —
+`:auto` is still the wrong name and the wrong mechanism.
+
+*Rejected: a third `scrollbar_visibility` value* (`:when_scrollable`) preserving
+the old look under `:visible`. It would spend API surface defending the exact
+behavior being complained about; a full-height solid handle has no defenders.
+The change is cosmetic and ships as a `Fix`.
+
+*Rejected: painting blanks rather than `░`.* The track keeps the affordance —
+"a bar lives here, there is nothing to scroll" — where a blank column reads as a
+layout bug. And with `DARK`'s token the sparse `░` is already near-invisible,
+which is the quiet the issue asked for.
+
+**Decision — one token, `Theme#scrollbar_color`, read at paint time.** The
+precedent is exact: `active_border_color` is framework-chrome *foreground*, and
+this is the same kind of thing. Both `paintable_row`s style the glyph span with
+`screen.theme.scrollbar_color`; `VerticalScrollBar` stays a pure geometry helper
+with no `Screen` dependency, which is why the token is read by the components and
+not by it. Two consequences fall out free: `CHROME_TOKENS` derives from
+`members`, so `Theme.ref(:scrollbar_color)` works the day it lands
+(`D_theme_ref`), and `Buffer#flush` quantizes at the wire, so nothing is
+pre-degraded (`D_color_depth`).
+
+*Rejected: a second token for the empty track*, which the issue floats on the
+grounds that `░` and `█` want different weights against the same background. They
+already have them: `░` is ~25% ink against `█`'s 100%, so the glyph delivers the
+weight difference a second token would buy. And with the quiet-handle rule above,
+`░` is the *resting* state and `█` appears only when it means something. A second
+token stays purely additive if one proves flat.
+
+*Rejected: reusing `hint_color`.* Tempting — it is the theme's "de-emphasized
+chrome" color — but since `D_status_bar` deleted the status bar in 0.13.0,
+`hint_color` is the one token **nothing in `lib/` paints with**: it is now
+app-facing. Loading framework chrome onto it means a theme author cannot retune
+their hints without retuning every scrollbar.
+
+*Rejected: a per-component `scrollbar_color=` accessor.* The same rule
+`D_bg_surface` closes with — a component does not grow a private color accessor
+beside the theme channel. An app that wants one bar different from another styles
+the theme, or (per-slot, live-resolved) uses `Theme.ref`.
+
+**Decision — the two glyphs are an app-global knob on the class.**
+`VerticalScrollBar.handle_char=` / `.track_char=`, so an app can ask for a
+lazygit-style bar (`▐` over a `│` rule) in two lines. Scope was the whole
+question, and app-global is right for the same reason `Theme` is: a scrollbar
+style is look-and-feel, which an app wants *uniform*, and per-component styling
+would make inconsistency the default. It is also the shape `D_ambiguous_width`
+already blessed — the pretty glyph offered as an opt-in knob, alongside
+`TextField#mask_char=` — and the precedent for a reassignable app-global lives
+next door in `ThemeDef.default`, whose spec-restore discipline this inherits.
+Both call sites already construct a bar per repaint, so nothing had to be
+plumbed through `List` / `TextView`.
+
+*Rejected: passing the glyphs through the constructor, or a per-component
+`scrollbar_glyphs=`.* Two components, two more setters, two more things to keep
+in sync, to serve a choice an app makes once. If one component ever genuinely
+needs to differ, an instance override is additive on top of this.
+
+**The knob validates at assignment: one grapheme cluster, one column.**
+`paintable_row` concatenates the glyph onto a row padded to fill the rest of the
+rect, so a two-column glyph pushes *every* painted row one column past
+`rect.width` — the "exactly `rect.width` columns" contract the whole paint path
+rests on, broken silently, with nothing in the diff to notice. That is the same
+silent-corruption class `D_select` refuses an `:auto` mode for, and it is why the
+check is at the writer rather than at paint, where the symptom is a corrupt frame
+with nothing to point at. Note this stays *inside* `D_ambiguous_width`'s bet
+rather than testing it: `█`, `░`, `│` and `▐` are all East-Asian Ambiguous and
+all measure 1 under the gem's policy.
+
+**The token is required, not defaulted.** `Theme` is a `Data.define` with
+required kwargs, so a new member breaks an explicit `Theme.new(...)`. Defaulting
+it would have kept those callers working while baking a dark-tuned grey into
+light themes; `theme.rb`'s own rdoc says a theme "is declared once so the
+verbosity self-documents", and the class fail-fasts on every other input
+(`TypeError` on a non-`Color`, `KeyError` on a `custom` typo). So it ships as a
+**Breaking** changelog entry with a one-line migration. `Theme::DARK.with(...)`,
+the documented construction path, is unaffected either way.
+
+**Defaults.** `DARK` reuses `GREY37` (59), the `active_bg_color` value, so the
+handle carries the same weight as the selection well — and the sparse track at
+that color is near-invisible against a #1d–#2d terminal background, which is the
+resting state we want. `LIGHT` inverts the reasoning rather than copying the
+token: a *foreground* on a pale background must be darker than it, so `GREY62`
+(247, ~#9e9e9e) sits a step below the light theme's highlights instead of
+matching them.
+
+**Parked: focus-awareness.** The bar in the *focused* pane is the one the user
+can actually drive, so it arguably wants the brighter ink — the question
+`ideas/focus-accent.md` holds. Doing it here would mean importing `BG_STATES`-style
+state-keyed maps (`D_bg_surface`) into a foreground token for one widget's sake.
+Not built, not foreclosed.
+
+## D_paste_newlines — A one-line field keeps the paste's first line (2026-09-03)
+
+**Status:** Accepted and implemented in `TextField#preprocess_paste`. Supersedes
+the flatten-to-spaces rule recorded in `D_bracketed_paste`.
+
+**Context.** `TextField` holds one row, so a pasted `\n` has to go somewhere. It
+used to become a space. That is wrong on the *dominant* real paste: a whole line
+copied from an editor or a terminal carries a trailing newline, and flattening
+turned `"widget-3141\n"` into `"widget-3141 "` — an invisible trailing space that
+survives into whatever the app does with the value, and that no user can see to
+delete.
+
+**Nobody agrees, so "what everyone does" was not available.** Measured against
+the neighbours rather than recalled:
+
+| toolkit | `"a\nb"` pasted into its single-line input | mechanism |
+|---|---|---|
+| HTML `<input type=text>` | `"ab"` — **stripped** | the spec's value sanitization algorithm ("strip newlines") |
+| Textual `Input` (a TUI) | `"a"` — **first line** | `event.text.splitlines()[0]` in `_on_paste` |
+| GTK4 `GtkText` / `GtkEntry` | `"a"` with `truncate-multiline`, else all of it | the `truncate-multiline` property, default `FALSE` |
+| Swing `JTextField` | `"a b"` — **space** | `PlainDocument`'s `filterNewlines`, set true by `JTextField` |
+| Qt `QLineEdit` | value keeps `"a\nb"`; *displays* `"a b"` | `QWidgetLineControl::updateDisplayText` rewrites C0 to spaces at paint |
+
+Three camps, and Qt is really a fourth: it never sanitizes the value at all, only
+the pixels, so `text()` hands back a string with a newline in it that the widget
+never showed. Tuile can't take that road — `Buffer` is a grid of cells and a `\n`
+reaching it corrupts the frame — but it is worth naming, because it is the road
+"just fix the paint" leads to.
+
+**Decision — keep the first line, drop the rest.** `super[/\A[^\n]*/]`, before
+the `max_text_length` trim. Of the three real options it is the only one that
+never *invents* content: stripping fuses `"John Smith\nMain St"` into
+`"John SmithMain St"`, a token that was in nobody's clipboard, and spacing
+manufactures the trailing blank above. Truncation only ever discards, and it
+discards the part a one-row field could not have shown anyway. It also agrees
+with stripping on the case that actually happens (a trailing newline), so the
+difference between them is confined to pastes that were already never going to
+fit.
+
+Textual is the precedent that counts here — same medium, same constraint, same
+ruling — over HTML's, which inherits a sanitization algorithm written for form
+submission rather than for editing.
+
+*Rejected: a `truncate_multiline` knob*, GTK's answer. It buys the caller a
+choice between two lossy behaviours neither of which they can act on, and a
+field that keeps every line is a `TextArea`. *Rejected: rejecting the paste
+outright* — that is right for a field whose grammar the paste violates
+(`D_input_filters`) and wrong here, where the first line is perfectly good input.
+
+## D_input_filters — Filter input at `insert_text`, and only where the grammar is prefix-closed (2026-09-03)
+
+**Status:** Accepted and implemented in `AbstractStringField#insert_text`
+(promoted to the documented seam), `TextField#insert` / `TextArea#insert_char`
+(both now route through it), and the nested `Field` subclasses of
+`IntegerField`, `FloatField` and `BigDecimalField`.
+
+**Context — the filter was on the wrong event, and shipped broken for it.**
+The three numeric fields kept their "digits only" rule in a `field_key` proc
+wired as the inner field's `on_key`, and `on_key` is consulted only from
+`handle_key`. A paste is not a key (`D_bracketed_paste`), so it walked straight
+past. Measured on `master` before this entry:
+
+```
+typed "xyz"            → text ""        value nil    # filter works
+pasted "xyz"           → text "xyz"     value nil    # filter bypassed
+42, pasted "abc" at 0  → text "abc42"   value nil
+FloatField, "1,5"      → text "1,5"     value nil    # a plausible real paste
+```
+
+So all three fields could be put in a state their own rdoc said was impossible,
+with one Ctrl-V. The deeper fault is one of *altitude*: the rule constrains the
+**buffer**, and it was written against the **event**, which is why there were two
+paths and only one of them was guarded.
+
+**Decision — one seam, at the text mutation.** `insert_text` is now the sole
+insertion point for every string field: a typed character
+(`TextField#insert`), the ENTER newline (`TextArea#insert_char`) and a whole
+pasted clipboard all land there. A field constrains its contents by overriding
+it. There is no second thing to remember, and no way to guard typing and forget
+paste — the shape of the code makes that misfeature unwritable.
+
+**Decision — judge the result, not the fragment.** The override tests the whole
+resulting buffer against a `TYPEABLE` regexp rather than sieving the inserted
+string character by character. Sieving is the seductive one — it "salvages" a
+messy paste — and it is how `"1,5"` becomes `"15"`: a plausible number, off by a
+factor of ten, that the user never copied and cannot see is wrong. Rejecting the
+paste whole is also exactly what typing the comma does, so the two paths stay
+indistinguishable to the user.
+
+**Decision — prevention requires a prefix-closed grammar; otherwise report.**
+This is the criterion that says which mechanism a field gets, and it is the
+useful half of this entry:
+
+- A grammar is **prefix-closed** when every valid value can be reached through
+  valid intermediate states. An integer buffer is (`""`, `"-"`, `"-1"`), so is a
+  decimal (`"1."` must be reachable, and is a member of `TYPEABLE` even though
+  `value` reads it as `1`). Such a field can *prevent* bad input, and then it
+  has none: `IntegerField#value` is now `nil` only for the two half-typed states,
+  never for garbage.
+- A date is **not**: `"2020-13-45"` is well-formed at every character and denotes
+  nothing, and month lengths and leap years are whole-string facts, so no filter
+  over insertions can decide it. A field like that must accept the input and
+  report it bad — the `HasBadInput` channel (`D_bad_input`).
+
+The two are complements, not rivals: prevention where it is total, reporting
+where prevention is impossible. What must not happen is a *partial* filter, which
+is the worst of both — it looks like a guarantee, and isn't.
+
+**Roads not taken, for keeping a value out of a field.**
+
+- *Watch `on_change` and revert.* The callback has already fired for the state
+  you are about to undo, so every other observer sees the bad value and acts on
+  it; the revert fires a second round; and the caret has nowhere sensible to
+  land. It also cannot distinguish a bad *user edit* from a bad programmatic
+  `value=`.
+- *A veto seam on `HasValue`.* Wrong layer twice over. `HasValue` is deliberately
+  thin (`D_has_value`), and for the composed fields `value` is a **derived
+  parse** of the buffer (`D_integer_field`) — there is no "value is being set"
+  moment to veto while the user types, so any veto would have to run on the
+  buffer anyway, which is where it now is.
+- *Keep the per-key filter and add a parallel paste filter.* The two-seam design
+  that caused this. A future field would have to remember both, and the one that
+  forgot would fail silently and only under Ctrl-V.
+- *Filter in `text=`.* Too wide: it would police the programmatic `value=`, which
+  legitimately writes shapes no key types (`FloatField`'s `"1.0e-05"`). Only
+  *user input* is filtered, which is exactly what `insert_text` means.
+
+**Consequence — `e` became typeable in a `FloatField`.** The old per-character
+rule admitted no `e`, while `value = 1e-5` writes `"1.0e-05"` into the buffer, so
+the field could display a value the user was then unable to edit — every
+insertion into it would now be rejected by a `TYPEABLE` without an exponent. The
+grammar therefore admits the exponent, which widens typing slightly and closes
+that hole. A displayed buffer should always be one the user can go on editing;
+that is a general rule for a field with a `TYPEABLE`.
+
+## D_no_key_interceptor — No `on_key` callback: a component that wants a key subclasses (2026-09-03)
+
+**Status:** Accepted. `AbstractStringField#on_key` is **deleted**; its three
+consumers moved to `ComboBox#handle_key` + `on_escape`, the sampler's
+`SlashCommandTextArea`, and (downstream) a `TextArea` subclass in pikuri-tui's
+`ConfirmerPopup`.
+
+**Context — it was a veto wearing a listener's clothes.** `on_key` was a proc
+consulted *before* the field's own key handling, with a truthy return consuming
+the key. Every sibling seam on the class either reports something
+(`on_change`, `on_value_change`) or claims **one named key** (`on_enter`,
+`on_escape`, `on_key_up`, `on_key_down`). `on_key` claimed *all* of them,
+pre-emptively. That is a behavior override, and COP's answer to a behavior
+override is the sanctioned inheritance carve-out — subclass the widget to *be*
+the component — not an injected proc.
+
+**Decision — delete it; `handle_key` (and its `handle_text_input_key` hook) is
+the seam.** Three properties decided it:
+
+- **It duplicated an existing, better seam.** `Component#handle_key` is already
+  the per-component key hook, and it composes two ways `on_key` could not:
+  through `super` (a subclass claims one key and inherits the rest) and through
+  the rung-3 bubble (an ancestor sees what the focused component declined).
+  `on_key` was one slot, no chaining.
+- **The slot was contended, and losing it was silent.** A composed field must
+  claim its inner field's single `on_key` to do anything with keys — all four
+  did — so an app writing `combo.content.on_key = mine` silently disabled the
+  widget's own behavior, and the widget writing it silently disabled the app's.
+  There is no such contention on a subclass.
+- **It sat at the wrong altitude for what people reached for it for.** The
+  three numeric fields put their input filter there, and a paste walked past it
+  for two releases (`D_input_filters`). By the end its own rdoc had to warn
+  readers off the obvious use — a doc that says "don't use this API for the
+  thing it looks like it's for" is the API being wrong, not the doc.
+
+**And *not* promoted to `Component`.** The tempting generalization — if
+`handle_key` is on `Component`, why is `on_key` only on string fields? — points
+the other way. A universal pre-dispatch veto is a **fourth rung on the key
+ladder**: a per-component gate consulted before delivery, which is exactly the
+capture phase `D_key_dispatch` deleted in 0.10.0 and exactly what AGENTS.md's
+"no gate, no predicate and no mode flag anywhere in it" forbids. The right
+generalization was the one already there: `handle_key`.
+
+**Each consumer got *better*, which is the evidence the seam was wrong.**
+
+- **`ComboBox` needed no subclass at all** — it uses the **bubble**.
+  `ListDropdown::MOVE_KEYS` is `UP/DOWN/PAGE_UP/PAGE_DOWN/^U/^D`, deliberately
+  excluding Home/End *because the combo's field needs them for the caret*; the
+  field claims just one of the six (no `on_key_up`/`on_key_down` set; `^U` clears
+  the query as of `D_kill_keys`) and exposes no `on_enter`, so the other five
+  plus ENTER decline and reach `ComboBox#handle_key` untouched, while printables
+  and editing keys are consumed below and never arrive. The whole `field_key` if/elsif tree became a seven-line `handle_key`.
+  ESC is the one exception — the field consumes it — so the combo takes it
+  through the purpose-fit `on_escape`. All 39 combo specs passed unchanged,
+  driving real dispatch, which is what makes the equivalence a measurement
+  rather than an argument.
+- **The sampler's slash menu became `SlashCommandTextArea`.** Note what does
+  *not* work here: routing it "through the value". `on_change` already does the
+  refill that way, but Up/Down/PgUp/PgDn over a dropdown have no value
+  semantics at all — navigation is irreducibly about keys. It just doesn't need
+  a *callback*; it needs an override.
+- **pikuri-tui's `ConfirmerPopup`** claims ENTER on a `TextArea`, which is the
+  exact case book ch5 already teaches as `PromptTextArea < TextArea`. The gem
+  documented the subclass route *and* shipped the callback, and the downstream
+  app reached for the callback — the clearest sign the two-ways-to-do-it was
+  costing something.
+
+**What is deliberately kept.** The *named* key callbacks stay:
+`TextField#on_enter` / `#on_key_up` / `#on_key_down` and
+`AbstractStringField#on_escape`. They are not vetoes — each claims one key whose
+meaning the widget itself has no use for, they compose (four can coexist), and
+ESC in particular *must* be a callback rather than a bubble, since the field
+consumes it before any ancestor could see it.
+
+**Re-grow rule.** A general key callback comes back only if a caller appears
+that genuinely *cannot* subclass — which today means the framework would first
+have to grow a way to inject an inner field into a composed widget. Even then it
+would be a constructor-injected component, not a proc slot.
+
+## D_bad_input — `HasBadInput`: the field reports input its value cannot represent (2026-09-03)
+
+**Status:** Accepted; **v1 (the pull) implemented** in
+`Component::HasBadInput`, included by `IntegerField`, `FloatField` and
+`BigDecimalField`. The push notice (`on_bad_input_change`) is **deferred
+indefinitely, not rejected** — see "No push notice yet" below; the `on_blur`
+hook it was waiting on has since shipped for its own reasons (`D_on_blur`).
+
+**Context — `on_value_change` is structurally incapable of carrying this.** It
+is a diff over **values**, and the map from input to value is not injective:
+every unrepresentable input collapses onto the same `nil`. The information was
+destroyed by the parse before the diff ran. With a *derived* parse
+(`D_integer_field`) that leaves four cases, and only one of them fires anything:
+
+| input before | input after | `value` before | after | `on_value_change` |
+|---|---|---|---|---|
+| `"2020-01-01"` | `"xyz"` | a date | `nil` | **fires** (`nil`) — but says *empty*, not *bad* |
+| `""` | `"xyz"` | `nil` | `nil` | **silent** |
+| `"xyz"` | `"xyzw"` | `nil` | `nil` | **silent** |
+| `"xyz"` | `""` | `nil` | `nil` | **silent** — and the field is now *genuinely* empty |
+
+The silent rows are the plumbing problem; the first row is the semantic one —
+even when an event fires it reports the wrong fact, and a form reading "empty"
+as "the user cleared it" saves `nil` over a value they believe they typed.
+Vaadin hit this and named it (v25.2 `components-binder-validation.md`): *"Since
+the field is optional, the binder doesn't complain… This behavior can create the
+illusion for the user that they were able to save an invalid value."*
+
+**Decision — a mixin with one override point, returning a message or `nil`.**
+`bad_input_message` is the whole seam; `bad_input?` is its presence. A message
+rather than a boolean because the *reason* differs per field kind and the field
+is where that constant belongs. `nil`-means-fine is the convention
+`Component#extent` already uses. Being a mixin is what makes
+`is_a?(HasBadInput)` a locator seam for a future forms layer and for tests — the
+same argument that keeps `HasCaption` a mixin (`D_has_value`). Both members are
+**public**: the reader is the *app*, not the framework, so `D_hook_visibility`'s
+protected-hook rule doesn't apply. The default raises `NotImplementedError`
+(`Layout::Box`'s precedent) rather than returning `nil`, so including the mixin
+and forgetting the override is loud instead of a silent "never bad".
+
+**Decision — empty input is not bad input.** An empty buffer parses to nothing
+too, so the naive predicate is `value.nil?` and it is wrong: an optional field
+left blank would block every save, which is the exact failure this channel
+exists to prevent, inverted. Each override therefore reads
+`value.nil? && !content.text.empty?`. Emptiness is `HasValue#empty?`'s fact;
+this one is about input the value *could not use*. The three-line rule is
+duplicated per field rather than derived in the mixin from an abstract `input`
+reader: that base would need two hooks over one expression (`D_float_field`'s
+duplicate-rather-than-DRY rule), and a `DateField` will not share the shape
+anyway — a mask distinguishes *incomplete* (`"__/05/2026"`) from *invalid*, which
+Vaadin gives its own message (`setIncompleteInputErrorMessage`).
+
+**Decision — the field reports; it never stores a verdict.** Two error
+categories exist and exactly one belongs to the component:
+
+| | **bad input** — this entry | a rule's verdict — elsewhere |
+|---|---|---|
+| example | `"xyz"` is not a date; a lone `"-"` | must be in the past; age ≥ 18 |
+| authority | **the field, and only the field** (it owns the format) | the app / a binder (it owns the domain) |
+| when known | on every input mutation | when the rules run |
+| the field's role | **it is the fact** | a mailbox it cannot fill, defend, or recompute |
+
+The tempting economy is one `invalid?` flag both write. Vaadin's own custom-field
+guide warns against it (*"Do not rely on the same `invalid` and `errorMessage`
+properties for internal validation. Otherwise… external validation is likely to
+override or ignore the internal state."*) and then needs two mechanisms to stop
+the shared flag lying — a pull via `getDefaultValidator` and a push via
+`ValidationStatusChangeEvent`. Tuile inherits neither, because it puts the two
+facts in two *places* rather than sharing one cell — which is exactly what
+`D_has_validation` then built: `error_message` is a *stored* member only an
+outside validator writes, beside this *derived* one only the field answers, and
+there is still no `invalid?` anywhere.
+
+**Decision — fixed English, one frozen constant per field kind, no
+interpolation.** `"not a whole number"`, never `"'xyz' is not a whole number"`:
+the method is called per read and a future error ink would call it per paint, so
+interpolating allocates a fresh `String` every call (the rule `default_bg_color`
+already follows), and it sidesteps quoting a 500-character paste into a message.
+There is no wording knob even though every *other* user-facing string in the gem
+is an overridable default (`ConfirmWindow.alert(..., button: "OK")`), because
+**the message is advisory and `bad_input?` is the escape hatch**: a consumer
+wanting its own prose, in any language, reads the boolean and composes its own.
+That is what makes fixing the language cheap *and* reversible. **Re-grow rule:**
+when i18n arrives it arrives as the *wording* fork — a settable message, or a
+catalogue lookup inside `bad_input_message` — never as a redesign of the channel.
+
+**Decision — the fact is continuous; the consumers settle. No push notice yet.**
+Every prefix of a valid date is bad input, so typing `2026-05-01` walks nine bad
+states before one good one. The signal is correct at every instant and unusable
+if consumed naively — an enabled-state Save button would flicker while the user
+types *correctly*. Rather than settle centrally, the fact stays continuous and
+each consumer settles for itself; and v1 has no continuous consumer at all, so
+none is needed. A save gate asked at the click (`ideas/binder.md`) sees one
+settled state, and the red well reads the pull per paint. The push therefore
+lands with the first consumer that must react *between* keystrokes without
+being asked — which is also whoever owes the settling rule. Nothing is waiting
+on machinery any more: the commit point it would settle against is
+{Component#on_blur} (`D_on_blur`), which shipped for its own reasons, and the
+notice itself is one `attr_accessor` plus a sole-writer `sync_bad_input` in
+`ProgressBar#sync_ticker`'s discipline — called from every input mutation,
+never toggled by whichever event noticed. It is deferred for want of a
+*consumer*, and re-derivable in a sitting when one appears.
+
+**Population — include it iff your parse is partial.** That is
+`D_integer_field`'s compose-vs-subclass taxonomy read from the other side:
+
+- **Yes:** the three numeric fields, and a future date or masked field. Note the
+  first three reach this list *after* prevention (`D_input_filters`): their
+  grammar is prefix-closed, so their residue is the half-typed prefixes a filter
+  must admit — `"-"` for `IntegerField`, and for `FloatField` an infinite family
+  (`"e"`, `"1e"`, `"1.0e-"`, …). They need the channel least and are the only
+  place to exercise it before a date field exists.
+- **No, the parse is identity:** `TextField`, `TextArea`, `PasswordField`. A
+  string field's value *is* its input. `PasswordField` also pins a vocabulary
+  boundary — **input is what the user put in, never what is painted**; the
+  asterisks are `display_text`, one level below.
+- **No, input and value are one act:** `Checkbox`, `Select`, `RadioGroup`,
+  `CheckboxGroup`. Nothing sits between the keystroke and the value.
+- **No, and it is the interesting exclusion:** `ComboBox`. It has an input layer,
+  but the input is a **filter**, not a formatting of the value, so a no-match is
+  not a failed conversion — it resolves the desync by *reverting* the query. A
+  third strategy beside nil-out and report, and the reason the mixin is not
+  called `HasInput`.
+
+**Roads not taken.**
+
+- *A `bad_input? = false` default on `HasValue`*, to spare consumers the
+  `respond_to?`. It would put a field-kind concept on every `Checkbox` and
+  destroy the locator seam — the same argument that kept `tab_stop?` out of
+  `HasValue` (`D_has_value`). The capability is a class fact a consumer may cache
+  at bind time; the status may never be.
+- *Cache the status in an ivar and diff it.* Caching a derived fact has bitten
+  three times (theme accents, `bg_color`, `TextArea#@wrap`). Deriving it also
+  makes notice *order* immaterial: when `"2020-01-01"` becomes `"xyz"`, both
+  `on_value_change(nil)` and (once it exists) the bad-input notice fire, and
+  whichever a consumer receives first, asking `bad_input_message` yields the
+  current answer. The residual trap is a consumer that reacts to
+  `on_value_change` *without* re-asking — it concludes "the user cleared the
+  field", which is the illusion in the table above.
+- *Vaadin-faithful: one shared flag plus a pull seam and a push event.* Rejected
+  on the strength of Vaadin's own warning above — the repair mechanisms exist
+  *because* the flag is shared.
+- *Do nothing; bad input reads as empty.* The prior behavior. Defensible for the
+  fields Tuile has now that prevention is in place — their residue is visibly
+  half-typed — and not defensible at all under a text-input date field, where no
+  filter can shrink the residue in the first place. Shipping the seam now is what
+  keeps that field from inventing an ad-hoc `parse_error` accessor.
+
+**Consequences elsewhere.**
+
+- **`HasValue#empty?` gained an rdoc caveat** — it is empty of *value*, and a
+  required-field rule must ask `bad_input?` first or it reports "required" for a
+  field that is full.
+- **`clear` clears the *input*, not the value.** `HasValue#clear` is
+  `self.value = empty_value` and the mixin's default `value=` returns early when
+  the value is unchanged — so on a field holding bad input, whose `value` already
+  reads `nil`, an inherited `clear` would be a silent no-op leaving the garbage on
+  screen. Today's three are safe because each overrides `value=` without that
+  guard; the rule is now written on `HasValue#clear` and specced per field.
+- **A field holds bad input *or* a value, never both**, which is why nothing
+  here needs revert-on-commit machinery: with a derived parse, `value=`
+  overwrites the input by formatting it, so setting a value *is* clearing the
+  bad input and there is nothing left to revert. `ComboBox` is outside the
+  population precisely because it breaks that — it holds both a query and a
+  selected item, and resolves the divergence by reverting the query. Don't
+  generalize either half.
+- **Items-plus-value components stay out of it.** `Select`, `ComboBox`,
+  `RadioGroup` and `CheckboxGroup` deliberately allow a `value` their `items` do
+  not contain, with no reconcile and no clamp (`D_combobox`, `D_checkbox_group`,
+  `D_radio_group`). That is a domain rule, not bad input, and wiring it up here
+  is the obvious wrong move now that a channel exists.
+- **`EmailField` is not blocked on this, and is probably not a component.** Its
+  value *is* its input, so it has no bad-input state at all and contributes only
+  a packaged regex — re-tiered toward reject in `ideas/new-components.md`.
+
+## D_caption_ownership — A field carries no caption; the layout around it does (2026-09-03)
+
+**Status:** Accepted; the code side is a **non-change** — no field has ever
+included `HasCaption`, and this entry is what keeps it that way. The container
+half (`FormLayout`) is unbuilt. Graduated from
+`ideas/caption-and-error-ownership.md`, retired 2026-09-03; what it kept — the
+`FormLayout` geometry — is now `ideas/form-layout.md`.
+
+**Context.** Vaadin shipped both answers, which is what made this a real fork
+rather than a preference. Vaadin 8: `field.setCaption("Name")`, the component
+renders its own label. Vaadin 25: `formLayout.addFormItem(field, "Name")`, the
+form item owns the geometry. Tuile had to pick before a `FormLayout` could
+exist, and the answer decides whether `HasCaption` reaches `HasValue`.
+
+**Decision — the caption is the container's.** Three reasons, any one
+sufficient:
+
+- **A field cannot paint one.** Layout is top-down: a field is handed one row
+  and cannot grow a second, and advertising a wanted height is the bottom-up
+  channel v0.9.0 deleted. A caption inside the row displaces the value. So
+  `field.caption = "Name"` would be a stored string with *no reader on the
+  component's own face* — the mailbox shape `D_bad_input` refused for a rule's
+  verdict, in the other channel.
+- **The rendering is not the field's to fix.** Caption left, caption above,
+  caption column aligned across a form — all three are legitimate, all three
+  are the container's arithmetic, and storing the string on the field implies a
+  rendering it never performs.
+- **Nothing above needs it there.** A binder binds values and writes verdicts;
+  a caption is presentation. `D_has_value` already parks model-mapping above the
+  field.
+
+**The axis is "paints it", not "is a field",** and the existing membership
+already discriminates correctly: `Checkbox` is `HasValue` **and** `HasCaption`
+because it draws `[x] Enable logging` inside its own rect, as `Button` and
+`Window` draw theirs. So this entry bans a caption on `TextField`, not on every
+input.
+
+**Consequence — caption-based lookup relocates, it does not die.** AGENTS.md's
+mixin-for-lookup rule (a tree walk finding "the Button captioned Submit" via
+`is_a?(HasCaption)` plus a compare) still holds for the three painters, which
+still pass the reachable-plus-more-than-one-class test (`D_tabs` is where that
+test stops). For a field, the caption lives in the `FormLayout`'s per-child map
+— held by the thing that actually knows the caption↔field association — so a
+locator asks the authority (`form.field_for(caption: "Name")`), which is what
+Karibu-Testing does against Vaadin 25 form items. A direct handle
+(`Component#id`, reached through `Tuile::Testing.get`) is a separate decision,
+since made: `D_component_lookup`.
+
+**Consequence — a field outside a form has no caption**, and an app puts a
+`Label` beside it, exactly as every pane in the sampler already does. This
+declines to add a capability; it removes none.
+
+**Roads not taken.**
+
+- *`HasCaption` on `HasValue`, painted by the container anyway.* The worst of
+  both: the field stores a string it never reads, and two places can now claim
+  authorship of the same text.
+- *A caption that grows the field a row.* The deleted bottom-up channel, and
+  `D_status_bar` refuses the framework-placed row from the other side.
+- *Vaadin 8 wholesale (caption **and** error ink on the field).* Half of it
+  survived on the merits — see `D_has_validation`, which keeps the *verdict* on
+  the field for a reason that does not apply to the caption: a field can paint
+  invalidity inside its rect without displacing the value, because ink is a
+  restyle of cells it already paints.
+
+## D_has_validation — `HasValidation`: the field holds the verdict, the container paints the message (2026-09-03)
+
+**Status:** Accepted and implemented in `Component::HasValidation`
+(`error_message`, `on_error_message_change`, the protected `error_ink?`),
+included by `HasValue`; plus `Theme#error_color` / `#error_bg_color` /
+`#error_active_bg_color` and `Component#error_bg_color`. The container that
+renders the *message* is unbuilt — `FormLayout` — so the sampler's Validation
+pane is the only consumer today. Graduated from
+`ideas/caption-and-error-ownership.md` (retired 2026-09-03; its container half
+lives on as `ideas/form-layout.md`), then amended the same day from
+`ideas/error-background-tint.md`, which reversed the ink ruling below.
+
+**Context — `D_bad_input` shipped a channel and then could not say where a
+rule's verdict lives**, because the answer depended on who paints. That entry's
+authority table is still correct; what it left open is this.
+
+**Decision — split "invalid" by geometry, and the fork dissolves.** It was
+being treated as one thing and it is two:
+
+| | the **verdict** | the **message** |
+|---|---|---|
+| what | this field is invalid | "Username is required" |
+| cells | fits the one row the field has — ink is a restyle of cells it already paints | needs cells the field does not own |
+| so it lives | on the field (`error_message`) | wherever the cells are: a `FormLayout`, or an app's own `Label` |
+
+So the field stores the fact and paints itself; whoever has the cells reads the
+text off it. The re-grow rule that governs both halves —
+*a component gets a member only when something on its own face reads it*, and
+never as a mailbox for a value it cannot compute or paint —
+passes here and fails for the caption (`D_caption_ownership`), which is why the
+same rule gives the two halves opposite answers.
+
+**Decision — one member, no `invalid?`.** A second predicate beside
+`bad_input?` gives a caller no way to know which to ask, and the two differ in
+authority, population and lifetime (`D_bad_input`'s table). Invalid *is* a
+non-nil message; `""` is the flag with nothing to say.
+
+**Decision — the field never writes it, which is the whole answer to Vaadin's
+warning.** `D_bad_input` quotes the custom-field guide: *"Do not rely on the
+same `invalid` and `errorMessage` properties for internal validation.
+Otherwise… external validation is likely to override or ignore the internal
+state."* Tuile's two facts stay in two members: the field's own report is
+`bad_input?` (derived on read, never stored), and `error_message` is written
+only from outside — the field computes no verdicts, so it has nothing to write.
+That leaves exactly one writer, and the discipline that writer owes is one
+sentence: **set *or clear* it on every validate pass.** Vaadin needs
+`getDefaultValidator` and `ValidationStatusChangeEvent` to repair a shared
+cell; Tuile inherits neither, for the same reason it inherited neither in
+`D_bad_input`.
+
+**Decision — it carries a change notice, where `bad_input?` deliberately does
+not.** Not an inconsistency: `bad_input?` is *continuous* (every prefix of a
+date is bad input), so a display consumer owes a settling rule first — the ink
+has since paid that (`bad_input_settled?`, `D_date_field`) — while
+`error_message` is *discrete* — asserted at a click or a binder pass. So the
+notice is plain listener inversion, and it is load-bearing rather than
+speculative: the message is painted in cells the field does not own and does not
+invalidate, so without it a `FormLayout` cannot know to repaint.
+
+**Decision (amended) — the verdict is a red *well*, not red text.** The first
+cut made it a foreground, reasoning that `invalid` and `focused` co-occur so an
+error background would put two meanings in the channel `bg_color` owns and would
+owe a 2×2 precedence ruling. That shipped with a gap the entry admitted — *an
+empty invalid field has no glyphs to tint*, which is the required-field case,
+i.e. the commonest validation failure there is — and a second one it missed:
+`under_fg` was fill-unset, so a span already carrying a color never reddened
+(a `RadioGroup` row with a styled label, a `List` with per-item colors). The fg
+channel needed glyphs **and** needed them unstyled.
+
+The reframe that unblocked it: *why does a field have a well at all?* To show
+its boundary. A red well shows the boundary **and** the verdict, so nothing is
+lost — and the 2×2 dissolves because the pair is *declared*, not derived:
+`Theme#error_bg_color` / `#error_active_bg_color` are `input_bg_color` /
+`active_bg_color`'s red counterparts. Two tokens rather than one flat error
+color, because otherwise a focused invalid `Select` shows no focus at all —
+`D_bg_surface` already found that exact bug ("`select.bg_color = X` silently
+removes the only focus indicator a `Select` has — it paints no caret").
+`BG_STATES` stays closed either way: error is a *level in the chain*, not a
+state key. This still re-weighs `D_color_slots` (a chrome token over a
+per-component slot), which validity spanning every `HasValue` field is the case
+that argument was waiting for.
+
+**The hook sits above `bg_color`, not under it.** `Component#error_bg_color`
+(protected, nil by default) resolves first:
+`error_bg_color || @bg_color || default_bg_color || parent`. Under it — the
+obvious placement, and where the `default_bg_color` precedent points — an app
+tinting a panel would silently switch the validation signal off on the fields
+inside, which is the issue-#11 bug class again. It also keeps the change to one
+site: `default_bg_color` is overridden by six widgets that would each have
+needed a `return super if invalid` line, and the seventh would forget it. So
+**no widget needed a line of paint code**, and the ordinary background chain
+does the composing — a composed field's inner face is already `BG_INHERIT` and a
+group's `List` declares no background, so both walk up and land on the
+composer's answer with nothing forwarded. `ambient_bg_color` skips this level as
+it skips `default_bg_color`: outside its extent the widget is not there.
+
+**The well ORs `bad_input?`,** through the protected `error_ink?` hook that
+`HasBadInput` widens — so `HasBadInput` `include`s `HasValidation` to pin the
+ancestor order its `super` needs. This knowingly inherits `D_bad_input`'s
+continuity problem on the *face* only: a `FloatField` reddens at the half-typed
+`"1."`, an `IntegerField` at a lone `-`. Accepted because a save gate that lets
+you press Save on a field it will reject is the worse failure.
+
+**Amended 2026-09-04 — the flicker bit, and the settling rule landed exactly
+where this entry parked it.** `DateField` took the measurement nobody had taken:
+where *every* prefix of the grammar is bad input, the OR holds the well red for
+the whole time the user types a correct date, which reads as "you are wrong"
+rather than "you are not finished". So `HasBadInput` grew the protected
+`bad_input_settled?` and `error_ink?` became
+`(bad_input? && bad_input_settled?) || super`. As predicted, it gates **the ink
+only** — `bad_input?` stays derived-on-read, so a save gate asking at a click is
+untouched. Its default is `true`, so the numeric fields still redden
+immediately, and that is a ruling rather than inertia: their residue is one or
+two transient buffers (`-`, `"1."`, and the `-`/`-0.` pair while `-0.5` is
+typed), so the flicker is brief and the early warning beats the quiet.
+`DateField` overrides it with a latch on its commit gestures (`D_date_field`).
+
+**Rejected — blending the well toward `error_color`.** Attractive because it
+composes with an app's own panel tint, and because modelling error as a
+*transform over* the resolved background is what dissolves the 2×2 (that
+reframe survives; the transform did not). It dies on quantization: a lerp is a
+contraction, `|tint(active) − tint(normal)| = (1−w)·|active − normal|`, so the
+tint squeezes out the focus shade it composes with. Under `palette256` only
+`w = 0.40` keeps all three conditions in both schemes, and 0.40 is `#8f4f4f` —
+not "slight". The elegant repair (add chroma, preserve luminance, so the delta
+survives by construction) is *worse*: it fails on `DARK` at every weight,
+because the dark grey ramp is dense enough that a chroma-only shift off a dark
+grey snaps back onto it. Two further reasons not to revisit: `Theme` validates
+every member `is_a?(Color)`, so a per-scheme *weight* token would mean loosening
+that check; and the blend's own best outputs were palette 95/131 and 174/181 —
+opaque cells an opaque token can simply name, which is what made picking one
+per state the cheaper answer (and what then let the pair be *retuned* to the
+cells below without touching a line of resolution code).
+
+**Rejected — real alpha in `Color`.** It buys multi-layer composition and
+nothing needs more than one layer. Also settled while deciding, and worth not
+re-deriving: alpha could never reach the `Buffer` — terminal cells are opaque
+(`D_bg_inherit`), a cell holds one final color, and there is nothing underneath
+to composite against except the previous frame — so it would have to be
+flattened during resolution, and putting it in `Color` makes that value type
+partial (a translucent color has nothing to hand `sgr_codes`). If a dim factor
+is ever needed, `ideas/modal-backdrop.md` owns both `Color#mix` and the type
+question, and has the harder version of it: a fan-out over unknown,
+app-authored bases rather than one known one.
+
+**Token choice.** `DARK` uses palette 88 (`#870000`) / `LIGHT_PINK4` (95,
+`#875f5f`), `LIGHT` uses `MISTY_ROSE1` (224, `#ffd7d7`) / `LIGHT_PINK1` (217,
+`#ffafaf`). Three conditions were measured on every candidate, at each depth:
+**A** resting well ≠ `input_bg_color`, **B** focused well ≠ `active_bg_color`,
+**C** focused ≠ resting. C is the one that kills candidates — losing it means a
+focused invalid `Select` shows no focus at all, since it paints no caret. Both
+pairs hold all three at `truecolor` and `palette256`, and each keeps **A and C**
+at `ansi16`, where the shipped 95/131 and 181/174 had failed all three.
+
+Each pair also **splits in the same direction as its own valid pair**, so an
+invalid field feels like the same widget: `DARK` darker → lighter on focus
+(`GREY27` → `GREY37`, 88 → 95), `LIGHT` lighter → darker (`GREY85` → `GREY82`,
+224 → 217).
+
+Two things not to re-derive:
+
+- **The `DARK` focused well must avoid the bright mid-reds around `#af5f5f`.**
+  That is where terminals put the *cursor*, so `INDIAN_RED` (131) made a caret
+  sitting in an invalid field blur into the well — reported from real use, not
+  from the arithmetic. Tuile cannot know the cursor color (it is the terminal's;
+  OSC 12 would report it, `D_background_rgb` is the precedent) and deliberately
+  chooses rather than queries, exactly as `D_background_rgb` argues a theme
+  picks colors to sit *against* the terminal.
+- **224 is the floor on `LIGHT`, not a preference.** Anything paler quantizes
+  onto the grey ramp — `#ffeaea` → 255 — so a subtler well is *colorless* on a
+  256-color terminal; `#fbdede` and `#f7d0d0` both land back on 224. The cost is
+  that 224 sits a shade above `GREY85` in luminance, so an invalid field reads
+  level with a valid one rather than more recessed. Accepted: near-white was the
+  ask, and the tint carries the signal by hue.
+
+The remaining live trade is `ansi16`, where B is unreachable for both pairs — but
+focus is *already* invisible there (`GREY27` and `GREY37` both quantize to
+`:bright_black`), so nothing is lost that was not already gone, and
+`D_color_depth` rules out solving it with a depth-conditional strategy. A/B/C
+are asserted at both depths in `theme_spec`'s "the error wells" context, so a
+future retune is measured rather than eyeballed.
+
+**Decision — a separate mixin, included by `HasValue`, not members on
+`HasValue`.** Four reasons:
+
+- **Different authorities.** `HasValue` is the field's own state;
+  `error_message` is written from outside. `D_has_value` keeps that seam
+  deliberately thin and self-owned, and a foreign-written member sits better
+  behind its own name.
+- **Lookup.** A binder or a test locator iterating "everything that can carry a
+  verdict" walks `is_a?(HasValidation)` — reachable, more than one implementing
+  class, the test `D_bad_input` and `D_tabs` both apply.
+- **A non-field can be invalid** — a composite custom field, a form section
+  wrapping several — and includes it alone.
+- **It is Vaadin's split**, so the binder port reads familiar.
+
+Cost is ~12 lines, the same trade `HasCaption` made.
+
+**Population — every `HasValue`, and nothing else.** Unlike `HasBadInput`
+(include it iff your parse is partial), any field can be the subject of a rule,
+including a `Checkbox` ("you must accept the terms"). `ProgressBar` stays out
+for the reason it stays out of `HasValue`: a display widget is not a field
+(`D_progress_bar`).
+
+**Roads not taken.**
+
+- *The container stores the message, in its per-child map.* The shape
+  `D_box_layouts` already uses for constraints, and the first instinct — a field
+  should not have to know what its parent is. It dies on the binder: `binder` is
+  handed *fields* and has no reference to the layout they happen to sit in, so
+  the only thing that ever computes a verdict could not report one. A click
+  handler is the same — it holds `username` and `password`, not `form`. And it
+  would leave a field outside a `FormLayout` with no way to show anything at
+  all.
+- *Vaadin 25 read as "the container owns errors too".* A misreading worth
+  recording, because it nearly settled this the other way: Vaadin 25 moved the
+  *caption* to the form item and kept `invalid` / `errorMessage` on the field
+  (`HasValidation`), which renders both. Even the container-owns precedent does
+  not put the error on the container.
+- *An `invalid?` boolean plus a separate message.* Two members for one fact, and
+  the predicate collides with `bad_input?` as above.
+- *A red foreground on the glyphs.* The first cut, argued from the
+  co-occurrence with focus and **reversed by the amendment above** — that worry
+  dissolved once the pair was *declared* rather than derived, and the fg channel
+  turned out to need glyphs it does not have on the required-field case.
+- *Leaving `bad_input?` out of the well.* Also the first cut, on
+  `D_bad_input`'s continuity grounds; the amendment ORs it in through
+  `error_ink?` and accepts the flicker, for the reason given above — a Save
+  gate that rejects a field the face called fine is the worse failure. A
+  settling rule has since been written and softens the *well* only, as this line
+  predicted (the amendment above; `D_date_field`).
+- *Forwarding the message down to a composed field's inner widget.* What a
+  push-it-down design would have needed on four composed fields and two groups;
+  resolving the well through `effective_bg_color` deletes the whole category,
+  since that chain already inherits.
+
+## D_component_lookup — `Component#id` plus `Tuile::Testing`: scope is an argument, not a receiver (2026-09-03)
+
+**Status:** Accepted; **v1 implemented** — `Component#id`, `Component#inspect`
+plus the protected `inspect_details` hook, and `Tuile::Testing.find` / `.get` /
+`.dump`. Graduated from `ideas/component-lookup-for-tests.md`. The checked
+interactions, a `value:` match and a `test_id`/`name` split are deferred, not
+rejected (listed at the end).
+
+**Context — the specs had already written this locator, twelve times.**
+`sampler_spec` alone carried ten walks shaped
+`on_tree { |c| combo ||= c if c.is_a?(ComboBox) }`, plus one each in
+`confirm_window_spec` and `has_caption_spec`. They were the reason to build it,
+and one of them named the trap in a comment: *"demo_window, not the sampler:
+the jump box is a ComboBox too, and it comes first in tree order."* The `||=`
+resolves ambiguity by silently taking whichever component the tree walk reached
+first — so a pane that grows a second `ComboBox` re-points the spec at a
+different widget and nothing goes red. Reporting that as an error, rather than
+picking a winner, is most of what `get` buys.
+
+**Decision.** A `Symbol` `id` on `Component`, and a `Tuile::Testing` module
+with three public methods: `find` (every match, optional `count:`), `get`
+(exactly one) and `dump` (the tree, for a failure message).
+
+**Scope is the `in:` keyword, not a `Component#get`.** The open question in the
+note was whether the module should also install a receiver-style subtree
+lookup. It should not, on four counts:
+
+- Scope is a parameter *of the search*, not a property of a component. Both
+  spellings end in the same `on_tree` walk, so the receiver form adds surface
+  without adding power.
+- `get` is a generic name on a class apps subclass freely — the sampler alone
+  has `Panel`, `ShortcutBox`, `TickingBox`. `id` is already one squat on every
+  subclass; take one, not two.
+- Test-only API stays off production classes. The precedent is
+  `Screen#invalidated?`, which lives on `FakeScreen`.
+- **Re-grow rule:** if receiver syntax is ever wanted, it comes back as a
+  *refinement* inside `Testing`, so `component.get(Button)` exists only in
+  files that `using` it. Never as a method on `Component`.
+
+For the same collision reason the *documented* call form is qualified —
+`Testing.get(...)` — and `config.include Tuile::Testing` is deliberately not
+recommended: `find` and `get` are the two most collision-prone names in a spec
+suite (an app driving Capybara already has a `find`). Karibu-Testing solved
+this with the `_get` / `_find` prefix, which Ruby idiom rules out. Tuile's own
+specs sit inside `module Tuile`, so they get `Testing.get` with nothing to
+include.
+
+**`find` returns an Array and takes `count:`; that is Karibu's `_expect`.**
+`count:` accepts an Integer (exactly) or a Range (a bound), raises
+`Testing::LookupError` on a mismatch, and defaults to any number. `get` is then
+defined as `find(count: 1).first` rather than as a second search, which is why
+it reports an ambiguous spec instead of resolving it. `count: 0` is legal
+because it falls out of the same check, but it is **not** the idiom for
+"nothing is open" — a spec asserting that keeps `assert_empty
+Screen.instance.popups`, a direct assertion on the list beating a lookup that
+finds nothing.
+
+**`caption:` and `count:` both match with `===`.** A String caption is exact
+and a Regexp partial; an Integer count is exact and a Range a bound. The
+polymorphism is the feature, and it is why the one `spec_match?` helper carries
+a `Style/CaseEquality` disable rather than being rewritten into two branches.
+Karibu needed separate exact and regex knobs for the same job.
+
+**The class positional accepts a Module, so a mixin is a first-class spec.**
+`find(Component::HasValue)` finds every field, `find(Component::HasBadInput)`
+every field whose parse can fail. This is the mixin-as-locator-seam rule
+(AGENTS.md, *Input values*) finally having a consumer: `has_caption_spec`'s
+seam example now asserts through `Testing.get` rather than hand-rolling
+`is_a?(HasCaption)` plus a compare. The limit stated in `D_tabs` is unchanged —
+a `Tabs::Tab` is not a `Component`, appears in no `on_tree`, and so is
+unreachable by any of this.
+
+**Uniqueness is enforced at lookup, never at assignment, and production never
+checks it.** A detached tree cannot know the screen, so an assignment-time
+check would have nothing to check against; and two `TabSheet` panes may
+legitimately carry the same `id`, since only one is attached at a time.
+`get` raising on two matches is the whole mechanism, and it costs nothing.
+The setter's one guard is a type check: `id = "save"` is refused rather than
+coerced, because a String would never match a `get(id: :save)` — silently.
+
+**An `id` is not the mailbox that `caption` and `error_message` are.** The
+re-grow rule those two live under is "a component gets a member only when
+something on its own face *reads* it". An identifier inverts it: identification
+*is* the purpose, nothing is expected to paint it, and inertness is therefore
+not a smell. Worth stating because the shape looks identical and isn't.
+
+**`Component#inspect` is part of v1, not a nicety.** The tree dump in a failed
+lookup is most of a locator's value — Karibu's real lesson — and there was no
+`Component#inspect`, so `Object#inspect` would have walked `parent`, `children`
+and the `Screen`, dumping the whole UI for one component. The base line is
+class, `id` and rect; mixin details arrive through a **protected
+`inspect_details` hook** that each mixin extends with `super + [...]`, so the
+base stays ignorant of which mixins a component includes — the same rule that
+rejected a leaf checking `parent.is_a?(HasValue)` (`D_bg_surface`). They appear
+in reverse include order, the last-included module calling `super` first.
+`HasValue` truncates a String value at 40 characters *before* calling
+`inspect`, since a `TextArea`'s value is its whole buffer. The dump strips the
+`Tuile::` namespaces so a fifty-row tree stays readable, and flags the matches
+with a leading arrow; an app's own classes keep their full name.
+
+**It ships in `lib/`, not as a separate gem.** Zeitwerk loads
+`lib/tuile/testing.rb` on the first reference, so an app that never names
+`Tuile::Testing` pays nothing. Karibu is separate from Vaadin because Vaadin
+was someone else's project; here one author owns both sides, and a spec suite
+that has to add a gem to locate a component will keep hand-rolling `on_tree`
+instead. The `Testing` name signals intent rather than a hard boundary: if an
+app ever needs the id walk in production (a `FormLayout#field_for`), that is a
+re-grow onto `Component`, not a reason to rename the module.
+
+**This is additive to the assertion channel, not a replacement.** A spec
+asserting what a component *shows* still asserts `Screen#buffer`
+(`D_list_items`). What the locator replaces is the *driving* half — and, as a
+side effect, about a dozen `instance_variable_get(:@overlay)` reach-ins, since
+an open overlay is a popup under the pane and so reachable by class.
+
+**Deferred, not rejected.**
+
+- **Checked interactions** (`_click` / `_setValue`): refuse when the component
+  could not have received the interaction for real — not attached, not
+  focusable, not on the focus chain. Needs a modal-scope predicate, which
+  already exists as `bubble_key`'s `modal_popup || content` rule, and a ruling
+  on whether a key is simulated through the ladder or handed to `handle_key`.
+- **`value:` in the match spec**, and an `error_message:` one now that
+  `HasValidation` has merged (`D_has_validation`) — the mixin itself is already
+  matchable as a class positional, like every other seam.
+- **A `test_id` / `name` split** — a stable test handle distinct from an
+  app-meaningful identifier. One member until a second meaning actually turns
+  up.
+- **An `id:` constructor kwarg.** No component constructor takes kwargs today,
+  so it is a sweep over ~30 classes to save one line per call site.
+
+## D_on_blur — `on_blur`, the commit point Tuile lacked (2026-09-04)
+
+**Status:** Accepted; implemented — the protected `Component#on_blur`, fired
+from `Screen#focused=`. Graduated from `ideas/bad-input.md`, now retired; the
+push notice that note also carried is **postponed indefinitely** (last section).
+
+**Context — the gap was on record three times, from three directions.**
+`D_integer_field` declined to canonicalize `"007"` and `D_bigdecimal_field`
+declined a `scale=` knob, both citing *"a blur/commit point a TUI lacks"*;
+`D_bad_input` needed the same thing for a settled bad-input notice. And
+`on_enter` is not that point: Tab is unconditional (rung 1, `D_key_dispatch`),
+so tabbing out of a half-typed field is the *likely* exit, not the exotic one.
+
+**Decision — one hook, at the site that already existed.** `Screen#focused=`
+already held `previous` and already diffed it for `on_focus_changed`, so the
+whole implementation is the private `fire_focus_hooks`: blur, then focus, then
+the app notice. The rulings on its shape:
+
+- **Protected, reached with `__send__`** (`D_hook_visibility`). The same call
+  now reaches `on_focus` too, and that is a fix this entry owes rather than a
+  drive-by: shipping a *protected* sibling makes the natural grouping
+  (`protected` / `def on_blur` / `def on_focus`) likely, and it would have
+  broken the explicit-receiver `@focused.on_focus` — precisely the landmine
+  `D_hook_visibility` accepted while `on_focus` stood alone. `__send__` at the
+  site retires it without protecting `on_focus`, which three mixins present as
+  a composition seam.
+- **Blur before focus** — the DOM order, and the order `ideas/hover.md` had
+  already settled for its own exit/enter pair, so the framework has one answer
+  to the question rather than one per notice.
+- **Edge-triggered and fired on one component**, exactly like `on_focus`: not on
+  the ancestors that drop off the active chain. They already have a better seam
+  for it — `Component#active=`, which `ComboBox` overrides to close its dropdown
+  and revert a half-typed query when focus leaves the *widget* (focus sits on
+  its inner field, so a chain-wide `on_blur` would still be the wrong shape:
+  it would fire on the field, which is not who owns the dropdown).
+  Focus that merely *passes through* still blurs, so a container
+  forwarding focus from `on_focus` blurs itself one hop later. Accepted: the
+  pointer really did move, and suppressing it would mean remembering which
+  assignments were forwards.
+- **A notification, not a veto.** No return value and no refuse-to-leave, which
+  would have to fight the one key nothing can suppress. A handler *may* reassign
+  focus: the nested assignment wins and the outer one stops, so `on_focus` never
+  fires for a component that no longer holds focus (`screen_spec` pins it).
+- **No listener writer.** `on_focus` has none either, and `on_blur=` is additive
+  whenever a stock-assembly consumer turns up — in the `on_theme_changed=`
+  shape, public writer over protected hook.
+- **It fires wherever focus is *dropped*,** not only where a user moved it: the
+  popup-close repair blurs an **already-detached** component (an `invalidate`
+  there is a silent no-op, as in `on_detached`), and `Screen#close` blurs on the
+  way out, while the tree is still mounted. Written down here because both are
+  invisible from the call site and specced for the same reason.
+
+**Alternatives rejected.**
+
+- *`Screen#on_focus_changed` alone.* It exists, and it is the app-level channel
+  (`D_status_bar`) — but a *field* cannot commit itself from it, so every app
+  would rewrite the same dispatch-by-identity. `ideas/hover.md` asks the mirror
+  question for hover (does `on_hover_changed` make `on_mouse_exit` unnecessary?);
+  this is the focus half of the answer, and it is no.
+- *A public hook, for symmetry with `on_focus`.* The symmetry is real but
+  cosmetic; `D_hook_visibility`'s shape wins, and `__send__`-ing both hooks buys
+  the symmetry back where it matters — an override may declare any visibility.
+- *Reuse `on_detached` as the commit point.* Wrong axis: focus leaves a field
+  that stays mounted for the rest of the session, and by the time one detaches
+  the container it should report to may be gone.
+- *Name it `on_focus_lost`.* Longer, and `blur` is the word every neighbouring
+  toolkit uses (DOM, Swing's `focusLost`/`FocusEvent`, Textual's `Blur`); the
+  hover note independently reached for `enter`/`exit` from the same instinct.
+
+**Consequences.**
+
+- **Two entries' "a TUI lacks a blur/commit point" is now false**, and both were
+  edited: `D_integer_field`'s no-normalization and `D_bigdecimal_field`'s no-
+  `scale=` now rest on the half that survives — rewriting the buffer under the
+  caret while typing. They are re-openable on the merits, no longer blocked.
+- **The bad-input push notice stays deferred, and the design sketch is
+  deliberately not preserved.** `on_bad_input_change` was blocked on this hook
+  *and* on a consumer; the hook has landed and the consumer still has not asked.
+  The shipped red well reads the pull per paint (`D_has_validation`) and a Save
+  gate asks at the click (`ideas/binder.md`), so nothing is waiting. If one ever
+  is, the shape is an hour's work re-derived from scratch — one `attr_accessor`
+  plus a sole-writer `sync_bad_input` in the `ProgressBar#sync_ticker`
+  discipline, called from every input mutation — and it arrives together with
+  the settling rule its first *continuous display* consumer owes. Half of that
+  debt is now paid: the **ink** settles via `HasBadInput#bad_input_settled?`,
+  latched by `DateField` on its commit gestures (`D_date_field`). That is the
+  template a push notice copies, not an argument for building one — the pull
+  plus a latch covered the only consumer that could not be asked at a click.
+
+## D_placeholder — `HasPlaceholder`: a hint in the field's own cells, in ink tuned to be missed (2026-09-04)
+
+**Status:** Accepted; implemented — `Component::HasPlaceholder`, painted by
+`TextField` and forwarded by the four composed fields, in the new
+`Theme#placeholder_color`. Graduated from `ideas/text-field-placeholder.md`, now
+retired.
+
+**Context.** `DateField` wanted it first (`D_date_field`): a date field must
+tell the user *which* of its formats it writes back, information available
+nowhere else.
+But that is a general text-input affordance, so it ships as one rather than as a
+private `DateField` trick.
+
+**Decision — a paint-time branch, not a `display_text` substitution.** The seam
+that *looks* right is `TextField#display_text`, and it is the wrong one: its
+contract is one display character per `text` character, in order, because
+`column_at`, `index_at`, `visible_text` and `adjust_left_column` all measure it
+as the rendering of the buffer. An empty buffer showing ten glyphs of hint
+breaks that in the most visible way there is — `cursor_position` would park the
+caret past the hint instead of at column 0. So the hint is a branch in
+`repaint`, beside `visible_text`, and the rest of the class is untouched: with an
+empty buffer `caret` and `left_column` are both 0, so the caret lands correctly
+and the scrolling machinery has nothing to do.
+
+The rulings on its shape:
+
+- **Paint-only, in every direction.** Not in `text`, `value`, `empty?`,
+  `on_value_change`, a paste, or `max_text_length`'s budget. That asymmetry *is*
+  the feature — a placeholder living in the buffer would be a default value, and
+  a form saving it would write `"dd.mm.yyyy"` to the database.
+- **The condition is `text.empty?` alone — no focus term.** Browsers used to
+  hide the hint on focus and HTML5 stopped; here the argument is stronger than
+  convention, because the format hint is wanted *precisely* while the user is
+  typing into the field. One condition also means no `on_focus` bookkeeping.
+- **A plain `String`, and `placeholder=` raises on a `StyledString`** rather
+  than flattening it. Two reasons, and the second is the durable one: an
+  app-supplied `StyledString` bakes its colors at construction and would need an
+  `on_theme_changed` rebuild to survive a flip (the trap `D_theme_ref` exists to
+  keep off chrome); and the ink is deliberately calibrated to be *barely*
+  visible, so a per-app color is not a missing knob but a knob for defeating the
+  design.
+- **It ellipsizes rather than clips.** A middle-cut `dd.mm.yyy` reads as a
+  *complete* format that happens to be wrong, where `dd.mm.y…` reads as
+  truncated — and for the motivating case that difference is the whole point.
+  Free, too: `StyledString#ellipsize` already defaults to the one-column `…`,
+  which is East-Asian Ambiguous and already inside `D_ambiguous_width`'s
+  inventory (`Checkbox`, `ComboBox`), so this adds no glyph and reopens no bet.
+- **An invalid field still shows it.** An empty *required* field is the
+  commonest invalid state and exactly when a hint about what belongs there is
+  worth most: the red well says *something is wrong*, the hint says *what goes
+  here*, and they are complementary rather than competing.
+- **`Select` does not include it** — not a contradiction of this entry but the
+  case `D_select` already ruled: a blank face plus `▾` is self-evidently
+  "nothing picked", so an absent enum *value* needs no hint the way an
+  unguessable input *format* does.
+
+**The ink — `hint_color` was the obvious choice and is wrong.** The idea note
+filed it as "the subdued-secondary-text token". It is not: it is
+`LIGHT_SKY_BLUE3` (109) on dark and `TURQUOISE4` on light, a saturated accent
+whose two consumers both use it to *pull* the eye (the shortcut caption in
+`"q quit"`, `PickerWindow`'s option captions). A placeholder painted in it makes
+an empty field *louder* than a filled one, which is the affordance backwards.
+`hint_color`'s own rdoc was widened to say "subdued **accent** text" in the same
+change, since that is what it has always been.
+
+So a new token, `placeholder_color` — and the shade is a *rule*, not a taste
+call, because the hard part is that the background varies: one ink must survive
+`input_bg_color`, `active_bg_color`, both error wells, and terminal-default
+under `BG_INHERIT`. Quantizing the candidates settles it:
+
+| shade | → `ansi16` |
+|---|---|
+| `GREY27`, `GREY37` — the *dark* wells | `:bright_black` |
+| `GREY42` … `GREY62` (247) | `:bright_black` |
+| `GREY66` (248) … `GREY85` — incl. the *light* wells | `:white` |
+
+On a 16-color terminal there is **no middle ground in either theme**: every grey
+subtle enough to want collapses onto its own theme's wells and the hint is not
+subtle but *gone*, while the first shade that separates is already at full text
+brightness. So each token is the boundary value on its side — `DARK` takes
+`GREY66` (248), the dimmest that still reads `:white`; `LIGHT` takes `GREY62`
+(247), the palest that still reads `:bright_black`. **A hint the user is allowed
+to miss must fail loud, never absent**, which is the tie-break, and
+`theme_spec`'s "the placeholder ink" pins the whole rule at all three depths
+(unlike the error wells beside it, `ansi16` *is* asserted here — that is the
+depth the shade was chosen for).
+
+**The token is required, not defaulted**, following `D_scrollbar_ink`'s
+precedent exactly: a default would keep hand-rolled themes working while baking
+a dark-tuned grey into light ones. One `**Breaking:**` line, and
+`Theme::DARK.with(...)` — the documented path — is unaffected.
+
+**The seam is a mixin, and it is the odd one in the `Has*` family.** Every other
+`Has*` shares real behavior (`HasCaption` *stores* the caption for all its
+includers, which own only the rendering). This one cannot: the leaf `TextField`
+stores and paints, while each composed field **delegates** to its inner field,
+because a copy in the composer beside the copy in the field is two sources of
+truth for one fact — the desync `D_tree_api` forbids for slots, in miniature. So
+every composer overrides both accessors, and what the mixin buys is the contract
+in one place, a shared `inspect_details`, storage for the single leaf, and
+`is_a?(HasPlaceholder)` as a lookup seam. Written down because a reader who
+assumes it works like its siblings will "fix" the composers onto the mixin's
+storage and reintroduce the desync.
+
+**Why the composers forward at all**, when `content` is public on `HasContent`
+and `content.placeholder =` already works: an app should not have to know that
+an `IntegerField` is a `TextField` in a trenchcoat. The counter-argument — that
+`content` is already the seam for every other inner-field knob
+(`max_text_length`, `mask_char`), so promoting this one implies the others are
+unreachable — was weighed and lost. A placeholder is part of a field's *public
+face* in a way a scroll or masking detail is not.
+
+**Alternatives rejected.**
+
+- *A `dim` (SGR 2) attribute on `StyledString::Style`, instead of a token.*
+  Conceptually the nicest: dim is *relative* to whatever foreground is in play,
+  so it inherits the terminal's own fg the way the no-global-fg rule wants,
+  needs no token, and does not quantize at all — it is the only design that
+  keeps subtlety on an `ansi16` terminal. Rejected for v1 because it changes the
+  most-specced frozen value type (parse, `to_ansi`, the diff, the sig) and
+  deserves its own argument rather than riding in on a placeholder. **Its
+  trigger condition is precise:** reach for it if and only if the two greys
+  cannot be tuned, or `ansi16` subtlety turns out to matter.
+- *Painting it on `TextArea` too.* Deferred, not refused. The state is generic
+  but the paint is not — `TextField` writes one windowed row, `TextArea` wraps
+  into a viewport — and putting the accessor on `AbstractStringField` while only
+  one subclass paints it ships a public setter that is silently inert on the
+  other. A multi-line free-text box rarely has an unguessable *format*, so there
+  is no near-term second caller; if one appears the accessor moves up **with
+  both paints written**.
+- *Treating it as a caption.* `D_caption_ownership` says a field paints no
+  caption, its container does, and the boundary is exactly the cells: a caption
+  sits *outside* the field's rect, in cells the field neither owns nor
+  invalidates. A placeholder is inside the field's own rect, on cells it already
+  paints and already invalidates. Sharper still: **a caption is unconditional
+  and describes the *field*; a placeholder is conditional on emptiness and
+  stands in for the *value***. Which yields the corollary an app needs — never
+  use a placeholder *as* a caption to save a row in a tight form, because the
+  hint disappears the instant the user types.
+
+**Consequences.**
+
+- **`TextField#repaint` does not call `super`, so the padded row *is* the
+  well** — `visible_text` has always padded itself to `rect.width`, and nothing
+  else clears the rect. The placeholder branch therefore ellipsizes to
+  `rect.width` **and pads back out to it**; a row only as wide as the hint would
+  leave the rest of the field holding whatever was painted there before, with
+  the background stopping mid-way. The idea note's first sketch got this wrong.
+- **`PasswordField` inherits it and should.** "password" under an empty masked
+  field is the standard look, and the mask only ever applies to buffer content —
+  a field showing its hint has none. Pinned in `password_field_spec`.
+- **`DateField` derives its hint after all — amended 2026-09-04.** This entry
+  ruled the other way first: an explicit default string, because the formats are
+  strftime, so a `"%d.%m.%Y"` → `"dd.mm.yyyy"` mapping table is a second grammar
+  that will drift out of step with the format list. `D_date_field` lifted that by
+  making the table **best-effort** — it serves the placeholder and nothing else,
+  so it is allowed to *abstain*: a primary format holding any directive the table
+  does not cover derives `nil` rather than a half-translation. A table that
+  abstains cannot drift *against* the format, because it makes no claim about
+  what it does not cover. The mixin needed no change for it, and the question
+  this entry flagged (a *settable* accessor on a field whose hint is *computed*)
+  answered itself: `DateField` overrides the accessor pair, holds the app's
+  override in an ivar of its own, and the storage that matters still lives on the
+  leaf `TextField` — `nil` restores the derived hint, `""` suppresses it.
+
+---
+
+## D_wrapping_field — `AbstractWrappingField`, and what `HasContent` actually means (2026-09-04)
+
+**Status:** Accepted; implemented 2026-09-04 (`Component::AbstractWrappingField`;
+`IntegerField` / `FloatField` / `BigDecimalField` migrated). Graduated from
+`ideas/composed-field.md`, which retains only the unbuilt `CompositeField`
+sketch.
+
+**Context — a fourth copy, and a rule that was backwards.** `D_float_field` and
+`D_select` both ruled *duplicate rather than DRY a shallow shell*, and set the
+bar at a **fourth** copy. `DateField` (`D_date_field`) is that copy, and
+by then the shell was not shallow: six obligations sat in all four composed
+fields — the mixin set, `bg_color = BG_INHERIT` on the inner field, a
+character-identical `default_bg_color`, `cursor_position`, the `placeholder`
+pair, and the `@last_value` change guard. One of them already carried a warning
+in AGENTS.md ("a **new** composed field owes both or its face paints untinted"),
+and a rule that needs a warning in the contributor doc wants to be code.
+
+Underneath sat a worse problem. `HasContent`'s own rdoc said to include it *"when
+the child is permanent and integral — a typed field's inner `TextField`"*, which
+is exactly backwards: the mixin ships a **public `content=`**, so
+`integer_field.content = Button.new` succeeded and left the widget permanently
+broken (`value` then raised `NoMethodError`). Six components had followed that
+rule correctly into a hole.
+
+**Decision — `HasContent` is a statement about the public surface.** *I have a
+primary child named `content`, this is my content which you populate; my other
+children are chrome, mine to manage.* Not arity (a `Window` has two app-settable
+children and the mixin names which is *the* content) and not
+permanent-vs-swappable (an `Overlay`'s body is permanent **and** public; that
+correlated for `Slot` alone). Legitimate includers: `Slot`, `Window`, `Overlay`.
+
+**Decision — a class, not a mixin, and one for the editor-faced fields only.**
+A class because it has a constructor obligation and two ivars: a mixin would need
+an `init_wrapper(editor)` an includer must remember to call, which is the very
+footgun this deletes (`AbstractStringField` is the precedent for an `Abstract`
+component base, and composition-over-inheritance permits a *cohesive* one). The
+`Abstract` prefix follows a rule rather than habit — Tuile's precedent is split,
+`AbstractStringField` carries it and `Layout::Box` does not — **prefix when the
+unprefixed name would read as an instantiable widget**.
+
+**Decision — the commit point is `Component#active=`, not `on_blur`.**
+`D_on_blur` had already ruled this and named the seam; `ComboBox` already
+implemented it. It is right at both tiers for free: "the widget left the focus
+chain" is what a commit means, and moving focus *between* two editors of a future
+composite keeps the composite active, where an `on_blur` design would fire on
+every internal hop.
+
+**Amended 2026-09-04 — ENTER is the second commit gesture, and the base owns
+it.** A form whose default button is reached by ENTER never moves focus, so
+leaving the focus chain is not enough: `DateField` would canonicalize *after*
+the save. So `handle_key` commits on ENTER, and `on_enter=` is **wrapped rather
+than forwarded** — the editor's slot runs `commit` and then the app's callback,
+so an ENTER handler never reads an uncommitted buffer. Two consequences a
+subclass must not undo:
+
+- **ENTER is committed and then left to keep bubbling.** `handle_key` returns
+  `super` (false), because `TextField` consumes ENTER only when *its* `on_enter`
+  is set — so a field with no callback declines the key, it arrives here by
+  bubbling, and a scope's default button still sees it. Consuming it instead
+  would silently break every form whose Save is bound to ENTER, and the first
+  cut of `DateField` did exactly that by claiming the editor's slot
+  unconditionally. Exactly one commit runs on either path, since the two are
+  mutually exclusive.
+- **A third claimed slot needs a hook, not a claim.** The base already owns the
+  editor's `on_change` (the change guard) and now its `on_enter`; a subclass
+  reacting to *edits* gets the protected `on_editor_change` no-op instead, which
+  is what `DateField`'s settling latch hangs on (`D_date_field`). One callback
+  slot cannot be shared (`D_no_key_interceptor`), so every one the base claims
+  owes the subclasses a hook in its place.
+
+**The admission test, which is what keeps this from becoming a junk drawer.** A
+member belongs here **iff it is true of every wrapping field *because* it wraps**
+— if you can state it without mentioning the inner editor, it belongs on
+`Component`, a `Has*` mixin, or the subclass. That admits the delegations and
+rejects `min`/`max`, `required`, rounding, a `converter=` and a caption, each of
+which is separately refused elsewhere. Its sharpest consequence is the
+**forwarding test**: forward a knob only if it means something in the face's own
+domain. `max_text_length` and `mask_char` fail it — a character count is an
+editor idea, meaningless on an `IntegerField` (which would want a value
+`min`/`max`, a different feature) — so they are **not** forwarded and a subclass
+sets them on its editor internally. Both of the first two candidates coming out
+*no* is the evidence the surface stays short.
+
+**Alternatives rejected.**
+- *Keep `HasContent` and make `content=` protected.* The mixin's whole point for
+  `Slot` / `Window` / `Overlay` is that the caller sets the child; the split is
+  by *audience*, not by visibility of one method.
+- *Migrate `ComboBox` too.* It fails both premises this base rests on — its
+  buffer is a transient **query** rather than a rendering of its value, and only
+  a commit moves the value. Forcing it in would need three overrides that each
+  *undo* a base behaviour (`clear`, the `on_change` wiring, the `on_enter`
+  forwarder, which would let the inner field eat the ENTER that opens the
+  dropdown). A base whose members a subclass must disable is not a fit. Same line
+  `HasBadInput` already draws for the same component.
+- *Cover the two group widgets as well.* `CheckboxGroup` / `RadioGroup` wrap a
+  `List` and want four of the fourteen members; ten inapplicable is not a shared
+  base. They were fixed the other way, in the same release: they drop
+  `HasContent` and own their `List` privately, but expose it **read-only** as
+  `list`. That is the second legal shape, and the one the *populate* half of the
+  rule picks out — an app tunes that `List` (`scrollbar_visibility`,
+  `show_cursor_when_inactive`, the cursor) but never supplies it. Forwarding
+  those knobs instead would fail the forwarding test above: they are `List`
+  concepts, not group concepts. Addressable is not the same as yours.
+- *Names.* `AbstractWrappedField` — the passive names the *inner* thing, and both
+  objects are fields. `AbstractDelegatingField` — the real contender, lost to
+  stdlib `Delegator`'s `method_missing`-based *total* delegation, which promises
+  exactly the forwarding the test above refuses. `AbstractTypedField` —
+  mis-scopes: `Select`'s value is typed and it wraps nothing.
+  `AbstractComposedField` — one letter from the eventual `CompositeField`.
+
+**Consequences.**
+- **`content` / `content=` are gone from the three typed fields** — a breaking
+  change to documented API, 6 call sites in-tree. There is no app-facing
+  replacement *by design*: a need the delegation surface does not cover is
+  either a forwarder this class should grow or an editor-shaped knob that fails
+  the forwarding test. Specs are the exception and use `Testing.get`.
+- **`clear` now empties the *input*.** The trap `HasBadInput`'s rdoc names — a
+  field whose value already reads `empty_value` while glyphs remain — only failed
+  to bite because all three `value=` wrote the buffer unconditionally.
+- **`value` / `value=` raise `NotImplementedError` in the base**, since
+  `HasValue`'s defaults store into `@value` and never touch the editor.
+- **`empty_value` is called during construction** to seed the change guard, so it
+  must not depend on subclass state. In practice it is a constant per class.
+- **`D_placeholder` needs amending, not superseding.** Its argument for
+  forwarding `placeholder` was that "`content` is already the seam for every
+  other inner-field knob"; that premise is void, and the conclusion is now
+  stronger — `placeholder` earns a forwarder precisely because it is the only one
+  of the three that is a domain concept.
+- **No `extent` declaration.** Checked rather than assumed: a 6-row
+  `IntegerField` paints its well on row 0 only, so there is nothing to fix.
+- **`Testing.find(HasValue)` matches twice per wrapping field** — the face and
+  its inner editor — and **that is correct and must stay**. Note the asymmetry:
+  an *app* never reaches the editor (the surface above is the whole story), but
+  a *test* legitimately does — `Testing.get(Component::TextField, in:
+  field)` is how a spec puts a field into a state no public setter reaches (a
+  lone `"-"`, a half-typed date) or sends it characters, and it is the sanctioned
+  replacement for the `content` this entry removed. So the locator reports the
+  tree **verbatim** and filters nothing; teaching it to hide a component because
+  of who owns it would both break that technique and make the tree it dumps
+  disagree with the tree that exists, which is the whole debugging value
+  (`D_component_lookup`).
+
+## D_date_field — `DateField`: several formats in, one format out (2026-09-04)
+
+**Status:** Accepted; implemented 2026-09-04 (`Component::DateField`).
+Graduated from `ideas/date-field.md`, now retired. v1 is manual entry only — the calendar
+grid stays Tier 2 in `ideas/new-components.md`, blocked on the Popover
+extraction, and the field unblocks itself by dropping it. Its twin is
+`D_time_field` (2026-09-05), which inherits every ruling here it does not
+question and records one as *shared* — Up/Down from an unparseable buffer
+stepping to today/now — changeable only in both fields at once.
+
+**Context.** `DateField` is the component that forced `HasBadInput` into
+existence: a date is the first Tuile value whose input cannot be constrained
+keystroke-by-keystroke, so it is the first field that must *accept* input it
+cannot represent. It is also the first field whose *display* is a choice rather
+than a rendering — `42` has one spelling, 4 September 2026 has a dozen.
+
+**Decision — the value is stdlib `Date`, so the component is `DateField`.**
+`D_float_field`'s naming rule (named after the Ruby class of its value) applies
+unchanged. The `LocalDate` instinct is right about the semantics and does not
+transfer: `LocalDate` exists in Java only because `java.util.Date` was a
+misnamed instant, while Ruby's `Date` *is* the civil date and `DateTime` /
+`Time` are the ones carrying time and offset. A Tuile-owned value type would be
+one no app's models, ORM columns or serializers speak — Tuile's job is to edit
+the app's values, not to introduce its own. Not `DatePicker`: Vaadin's name
+names the widget *category*, and a later calendar popup is a feature of this
+field, not a rename.
+
+**Decision — a list of strftime formats: parse in order, first whole match
+wins, `formats.first` writes back.** Stolen from Vaadin's
+`i18n.setDateFormats` (v25.2), which is the good idea because it makes a field
+lenient about what it accepts and strict about what it shows, with no mode flag
+and no ambiguity about which format is *the* format. Two corollaries:
+
+- **The list belongs to the app, not to the component.** The same mechanism
+  that makes a field lenient makes leniency configurable without a second
+  concept — one format is strict ISO, three accept what a European or an
+  American types, and nothing changes but the array. This is *not* the
+  `converter=` strategy `D_integer_field` refused: a format list configures the
+  field's own parse/format pair, it does not replace it with an injected one.
+- **strftime, not Java patterns.** `strptime` and `strftime` share one
+  vocabulary, so lenient-parse/strict-write costs one array; translating
+  `dd.MM.yyyy` would be a second grammar to own and keep correct.
+
+**Decision — the default is one ISO format, and *not* a lenient list.** A
+lenient default cannot be shipped: `%m/%d/%Y` and `%d/%m/%Y` both match
+`04/09/2026` and disagree about what it means, and **no validator can detect
+that** — only the app knows which reading was intended. Shipping the ambiguous
+pair would silently produce April 9 for a European who typed 4 September: a
+*wrong value that saves cleanly*, strictly worse than bad input, which is at
+least visible. So the order of the list is the disambiguation and it is the
+app's call; Tuile ships the culture-neutral, sortable, screenshot-stable one and
+lets an app shoot itself in the foot deliberately. (Vaadin's three-format
+example is *app* code, not its default.)
+
+**Decision — `default_format` / `default_calendar_start` are app-global
+*seeds*.** Read at construction into the per-instance `formats` /
+`calendar_start`, exactly as `ThemeDef.default` seeds new screens rather than
+being read live: an app sets them before building its UI, and a later change
+does not reach fields already built. Both rdocs say **"may change in the
+future"**, because both are stopgaps for the locale seam of `ideas/locale.md`
+(which also eventually owns `FloatField`'s decimal comma and a calendar grid's
+month names). The global holds *one* format rather than a list to keep the later
+deletion small; the accepted cost is that an app-wide lenient list is
+per-instance only. The house warning that comes with a reassignable app-global
+applies in full: a spec that reassigns one must restore it.
+
+**Superseded 2026-09-04 (`D_locale`), as its rdoc promised.** Both globals are
+**deleted**; `formats` and `calendar_start` became nil-means-inherit readers
+over `Screen#locale`. The two predictions in the paragraph above both held —
+the deletion was small, and the "one format, not a list" hedge was what made it
+so, since a detected `Locale#date_formats` *is* a list and the seed had nothing
+to lose. What it got wrong was the *seed* shape: a `Locale.default` was designed
+and then dropped, because a locale is a detected fact whose app override is one
+line after `Screen.new`, where a `ThemeDef` is an app-authored artifact a whole
+spec suite needs. So this entry's `ThemeDef.default` parallel is the one part
+not to copy for the next such global — and the spec-restore warning went away
+with it. The `formats` rulings this entry makes (the ordering-is-the-app's-call
+disambiguation, the round-trip validator, the derived placeholder, `%y`'s
+rejection) all stand, with one loosening `D_locale` records: only the *primary*
+must round-trip.
+
+**Decision — parse with `Date._strptime` for the leftover, then build and
+rescue.** Three findings, verified rather than predicted:
+`Date.parse("4 sep")` cheerfully guesses (which would make the format list
+decorative), `Date.strptime("2026-09-04junk", "%Y-%m-%d")` *succeeds* while
+silently ignoring the tail, and `Date._strptime("2026-02-30", "%Y-%m-%d")` hands
+back `mday: 30` because it does not check the calendar. So a match is two gates:
+a non-empty `:leftover` is no match, and only constructing the `Date` catches
+February 30th. Free leniency falls out — `"2026-9-4"` parses without zero
+padding, which is itself an argument for canonicalizing on commit.
+
+**Decision — `formats=` validates by round-tripping each pattern against one
+pre-1969 reference date.** `Date.strptime(REF.strftime(f), f) == REF` with
+`REF = Date.new(1962, 9, 4)`, and it does five jobs at assignment instead of at
+the first keystroke: it rejects `%D` (a whole `mm/dd/yy`, the typo for `%d`), an
+incomplete `"%Y-%m"` (which silently fills `mday: 1`), a write-only
+`"%B %-d, %Y"` (strptime takes no `-` flag), `%G` (the ISO *week*-based year
+masquerading as `%Y`, which round-trips to the reference year whatever you feed
+it) and every `%y`. Every property of the reference date is load-bearing:
+*pre-1969* so `%y` fails, *post-1582-10-15* so the Gregorian reform fails no
+innocent format, and *month ≠ day* so a `%m`/`%d` swap is not masked. It is a
+canary rather than a proof — but a century-lossy directive is lossy in both
+directions, so one pre-window date catches the class that ships, and the formats
+an app plausibly writes (`"%d.%m.%Y"`, `"%m/%d/%Y"`, `"%Y%m%d"`,
+`"%B %d, %Y"`, `"%d-%b-%Y"`, `"%A, %d %B %Y"`, `"%Y-%j"`) all pass. What it
+deliberately does *not* catch is an order **ambiguity** — `"%m/%d/%Y"`
+round-trips itself perfectly — which is correct, since which reading was meant
+is the app's call. The one thing it forbids is a deliberately incomplete
+parse-only format like `"%d/%m"` meaning "this year", which is
+`Date.parse`-flavoured guessing; the rejection is a feature. `%x` / `%X` / `%c`
+are rejected *separately*, by name, with a message saying they are not
+locale-aware: Ruby's `%x` is a fixed `"09/04/26"` under every locale and
+round-trips fine, so it would pass validation while silently meaning "American".
+
+**Decision — `%y` is out of a format list entirely; the app writes `%Y`.**
+Ruby's window is fixed *and closed at both ends*: `%y` is exact on
+1969-01-01…2068-12-31 and silently wrong outside it in both directions (1962
+writes `62` and reads back 2062; 2069 and 2100 write `69` and `00` and read back
+1969 and 2000). Since the primary is the write-back format and
+canonicalize-on-commit makes the rendered text *be* the value, a `%y` primary
+turns `field.value = Date.new(2100, 9, 4)` into a field holding 2000 — the same
+wrong-value-that-saves-cleanly the ISO-default ruling refused. And there is **no
+compact replacement, by arithmetic rather than by stdlib wart**: two characters
+cannot carry a century. `"%C%y-%m-%d"` round-trips 1962/2026/2100 exactly but is
+four digits wide, i.e. `%Y` with extra keystrokes. So Vaadin's `referenceDate`
+(a 100-year window centred on today) is not declined but *moot* — with no
+two-digit years there is nothing to centre. The cost, accepted and reversible:
+an app cannot make `04.09.26` typeable.
+
+**Decision — the placeholder is derived from the primary format, exactly or not
+at all.** `HasBadInput` mandates one frozen constant with no interpolation, so
+the message is `"not a valid date"` and can *never* name the accepted formats:
+the placeholder is the only channel that tells the user what to type, which
+makes it load-bearing rather than decorative. `D_placeholder` had refused to
+derive it, on the grounds that a `"%d.%m.%Y"` → `"dd.mm.yyyy"` table is a second
+grammar that will drift. Lifted, by making the table **best-effort**: it serves
+the placeholder only, so it may abstain. Every directive of the primary in the
+table ⇒ a derived hint; any one missing ⇒ `nil`, and the field shows no hint
+unless the app set one. That kills the drift objection *structurally* — the
+table cannot disagree with a format it makes no claim about, and a
+half-translated hint with a raw `%j` in it is unreachable. So the table is
+deliberately **not** the validator's enumeration: `"%Y-%j"`, `"%F"` and even
+`"%s"` validate cleanly and simply cost their instance a derived hint. Three
+directives plus `%%`; no `%b`/`%B` (a month *name* would need an invented
+`mmm`), no `%e` (a hint of `" d"` is not worth an entry), and `%-d` / `%-m`
+cannot appear in a format list at all. `nil` restores the derived hint and `""`
+suppresses it, which is free since `""` is truthy in Ruby and an empty hint
+paints nothing — and `field.placeholder` on an untouched field therefore reads
+`"yyyy-mm-dd"` rather than `nil`, an asymmetry with `IntegerField` and the more
+useful reading ("what does this field show?").
+
+**Decision — no input filter at all.** `DateField` overrides no `insert_text`:
+every character is admitted, typed or pasted, and the residue is reported
+through `bad_input?`. The grammar is not prefix-closed (`"2020-13-45"` is
+well-formed at every character), which is the condition `D_input_filters` names
+for taking the accept-and-report road; the tempting middle — rejecting
+characters no configured format can contain — is refused by the same entry, a
+partial filter *reads as a guarantee and isn't*. `max_text_length` likewise caps
+at a flat 64 rather than at the longest configured format: it is a pasted-novel
+guard, not a grammar.
+
+**Decision — leaving the field canonicalizes it, and ENTER commits too.** On
+blur a buffer that parses is rewritten in the primary format: type `4.9.2026`
+into an ISO field, Tab away, see `2026-09-04`. The UX argument is decisive —
+*the user sees that the field understood what they typed* — and it is what makes
+a multi-format list legible rather than mysterious. This is a deliberate
+divergence from `IntegerField`, which leaves `"007"` alone: a format list is a
+statement that input and display are *separate vocabularies*, which
+`IntegerField` never claimed. The seam is `AbstractWrappingField#commit`
+(`D_wrapping_field`). **ENTER commits too**, because a form whose default button
+is reached by ENTER never moves focus, so blur alone would let it save an
+uncanonicalized buffer — and that generalized into the base, which commits on
+ENTER and then lets the key keep bubbling to whatever binds it. Two gestures,
+not a general "commit" notion: there is no third candidate.
+
+**Decision — the red well is latched to those two gestures.** This is the first
+consumer of the settling rule `D_bad_input` left owed, and it had to be: every
+prefix of a date is bad input, so the OR in `error_ink?` held the field red from
+the first keystroke to the last — `2`, `20`, `202` all reddening on the way to a
+correct `2026-09-04`, which reads as "you are wrong" where the truth is "you are
+not finished". The rule gates the **ink** and nothing else, exactly as
+`D_has_validation` predicted it would: `HasBadInput#bad_input_settled?`
+(default `true`, so the numeric fields are unchanged — their residue is two
+transient buffers, where the early warning beats the quiet) is overridden here by
+a latch that `commit` sets and the base's `on_editor_change` clears. So the well
+reddens when the user leaves the field or presses ENTER, goes quiet on the next
+edit, and `bad_input?` — the pull a save gate uses — never waits for any of it.
+Two details that are easy to get backwards: `commit` settles **after** rewriting
+the buffer, since the rewrite is itself an edit that clears the latch; and
+settling must `invalidate`, because an ENTER on an untouched buffer paints no
+cells of its own and would otherwise change the ink with nothing repainting it.
+
+**Decision — Up/Down step a day; an empty or unparseable field steps to
+today.** `IntegerField` treats an unparseable buffer as `0`, so the analogue is
+`Date.today` — and unlike the integer case the step *lands* on today rather than
+today ± 1, since today is what a picker would have opened on. They claim the
+editor's `on_key_up` / `on_key_down` slots, as the numeric fields do, leaving
+the general key seam free.
+
+**Decision — `Date::GREGORIAN` by default, not Ruby's `Date::ITALY`.**
+Investigated rather than assumed, and the evidence runs one way. Ruby core calls
+the split a mistake — in [bug #18946][d_date_field_bug] Matz wrote *"`to_date`
+has been use GREGORIAN calendar since 2011-05-31 and `to_datetime` preserved the
+old `DEFAULT_SG` (ITALY). I assume this is a mistake and both should use
+GREGORIAN"* — `Time` is proleptic Gregorian and always has been (so
+`Date.new(1500,1,1).to_time` and `Time.new(1500,1,1).to_date` are nine days
+apart), ISO 8601 mandates proleptic Gregorian and ISO is this field's default
+primary format, and under `GREGORIAN` the ten days the reform skipped stop being
+a `Date::Error` the user cannot type their way out of. The cost, stated rather
+than hidden: the round-trip is exact only while the field's calendar matches
+that of the `Date`s the app hands it, and `Date.new(1500, 1, 1)` in *app* code
+is `ITALY` — so an app that builds pre-1582 dates naively gets them back nine
+days off after a canonicalization. That is what the per-instance setting is for.
+
+[d_date_field_bug]: https://bugs.ruby-lang.org/issues/18946
+
+**Rejected alternatives.**
+- **`value=` remembering the incoming `Date`'s own `start` and parsing back with
+  it.** Makes the round-trip exact for free, and is wrong anyway: `value` would
+  stop being a pure function of the buffer — the shape every other typed field
+  has (`D_integer_field`: the buffer is the single source of truth) — and a
+  field typed into from empty would have no `start` to remember.
+- **A runtime guard on `value=`.** `DateTime < Date` is true and `Time#strftime`
+  exists, so `field.value = Time.now` "works", formats as the civil date and
+  reads back a `Date`. Keep the thinness (`IntegerField#value=` just calls
+  `to_s`) and rule the truncation in rdoc: it is the same lenient-in/strict-out
+  shape as the format list.
+- **Two reference dates in the validator** — a pre-1969 one for the primary and
+  an in-window one for the rest, so `%y` stays typeable as a fallback. Bought a
+  two-digit shortcut at the price of a per-position rule; dropped with `%y`
+  itself. Re-allowing it later is purely additive.
+- **A mask (`dd/mm/yyyy` with per-field ranges).** It *is* a format declaration
+  by another route, and it manufactures a third state: `"__/05/2026"` is neither
+  garbage nor a value but **incomplete**, which Vaadin models separately
+  (`setIncompleteInputErrorMessage`). If this field ever grows one, it owes a
+  ruling on whether incomplete is bad input or its own thing — and it would ride
+  the same `error_ink?` hook either way.
+- **Designs that make bad input impossible** rather than reportable: a
+  calendar-grid-only picker (no text input, so no parse at all — but ~30
+  keystrokes for a birth date) and text entry behind a modal commit (a
+  `ConfirmWindow`-shaped dialog that won't close on garbage — heavy in a form
+  with six dates). A multi-format parse weakens the case for both.
+
+**Consequences.**
+- **`require "date"` is hoisted into `lib/tuile.rb`.** `Date` is not preloaded,
+  but unlike `bigdecimal` it is a default gem — always present, never optional —
+  so it gets none of `D_bigdecimal_field`'s lazy-load treatment, and citing that
+  precedent for it would be a misreading. `rake sig:validate` gains `-r date`
+  for the same reason.
+- **`formats=` and `calendar_start=` can change `value` with no edit**, since
+  the value is a derived parse — so both fire `on_value_change` when the reparse
+  differs. Neither touches the buffer: it is text, it reparses on the next read,
+  and if it has gone bad the red well says so.
+- **The humanizer must recognize a directive it does not know.** A `gsub` of the
+  three known ones leaves `"%Y-%j"` as the literal hint `"yyyy-%j"` — exactly
+  the lying hint the derive-exactly rule forbids, produced by the honest-looking
+  code. It scans the *general* strftime directive shape (flags, width, the
+  `E`/`O` modifiers, `%%`, `%::z`) and returns `nil` on any match outside the
+  table.
+- **No `extent` declaration and no paint code**, like the other wrapping
+  fields: the editor paints, and the red well arrives through
+  `HasBadInput#error_ink?` (`D_has_validation`).
+- **PageUp/PageDown stepping a month is deferred**, recorded so it is a decision
+  rather than an omission.
+
+## D_kill_keys — Ctrl+U and Ctrl+W in the string fields; Shift+Backspace is not a key (2026-09-04)
+
+**Status:** Accepted; implemented 2026-09-04.
+
+**Context.** Emptying a `ComboBox` query meant holding Backspace down. The
+obvious binding — Shift+Backspace — does not exist on the wire: Backspace is a
+single byte (`\x7f`) with nowhere to carry a modifier, so a terminal delivers
+Shift+Backspace as plain Backspace. Only opt-in protocols express it (xterm's
+`modifyOtherKeys=2` sends `\e[27;2;127~`, kitty's keyboard protocol
+`\e[127;2u`), Tuile enables neither, and VTE and Konsole send `\x7f` regardless.
+Nothing binds it, so nothing needed to.
+
+What every terminal input *does* bind is readline's kill trio: **Ctrl+U** to the
+line start, **Ctrl+W** the previous word, Ctrl+K to the line end. bash, zsh, fzf
+(`clear-query`), Textual's `Input` (`delete_left_all` / `delete_left_word`),
+prompt_toolkit, the ratatui ecosystem's `tui-input` and vim's insert mode all
+agree, and have since the 1980s. The GUI toolkits have no keyboard equivalent at
+all — Vaadin's combo ships a clear `×` and browsers rely on the mouse; macOS's
+Cmd+Delete is the closest cousin.
+
+**Decision — Ctrl+W on `AbstractStringField`, Ctrl+U on each subclass, both
+targeting a deletion the *key* names.** They share one protected primitive,
+`delete_back_to(index)`, so the caret and cluster rules are written once:
+
+- **Ctrl+W** is in the base, because "delete back to `word_left`" means the
+  same thing in one line and in many — it deletes exactly what Ctrl+Left would
+  have skipped, newline crossing included.
+- **Ctrl+U** is per subclass, because the target is not shared: index 0 in a
+  `TextField`, the caret's **row** start in a `TextArea` — the wrapped row, so
+  it kills back to wherever Home goes. Pinning it to the *line* would have made
+  Ctrl+U and Home disagree in a wrapped paragraph, which is the more visible
+  surprise.
+
+Ctrl+K is deliberately not bound: killing *forward* is the rarer half of the
+trio and the one nobody reached for here. It stays free, and the shape above
+(one `when`, one `delete_forward_to`) is what to copy if it is ever wanted.
+
+**The cost, paid knowingly: a `ComboBox` loses Ctrl+U half-page scrolling.**
+`ListDropdown::MOVE_KEYS` includes Ctrl+U/D, and a combo only ever sees the keys
+its field declines — so five of the six still bubble, and Ctrl+U now clears the
+query instead of moving the highlight five rows. `Select`, which wraps no
+editor, keeps all six. Worth it in one direction only: half-page-up over a
+ten-row dropdown duplicates what two arrow presses do, while clearing a query
+had no key at all. (`D_no_key_interceptor`'s "the field claims none of the six"
+is amended by exactly this.)
+
+**Alternatives rejected.**
+- **Bind it on `ComboBox` alone, gated on the dropdown being closed.** The first
+  proposal, and it fails twice. The gate is a mode flag in dispatch — a key
+  meaning two things depending on invisible state — and the moment `TextField`
+  grows the same key for its own sake (which it should, being a text field),
+  Ctrl+U means one thing in a bare field and another inside a combo. A key
+  earns its meaning from the widget that has focus; here that is always the
+  field.
+- **Ctrl+W only, leaving Ctrl+U to the dropdown.** No collision, and repeated
+  Ctrl+W clears a one-word query in one press. Declined because it makes Tuile
+  the only terminal input where Ctrl+U does not clear the line, to protect a
+  scroll gesture the arrows already cover.
+- **Drop Ctrl+U/D from `MOVE_KEYS` so the constant tells the truth.** It reads
+  tidier and is strictly worse: it would take the half-page jump away from
+  `Select` too, which has no editor and no conflict. The constant lists what the
+  dropdown *accepts*; what reaches it is dispatch's business, and the rdoc says
+  so.
+- **A `clear` gesture on the widget instead of a key** (a `×` affordance in the
+  face, or ESC clearing rather than reverting). The face is one row with one
+  spare column, already spent on the `▾`; and ESC's revert-to-the-committed-
+  label is the behavior that makes the query transient (`D_has_value`), so
+  spending it on clearing would cost more than it buys.
+
+**Consequences.**
+- **`delete_before_caret` is now `delete_back_to(cluster_boundary_before(caret))`**
+  — one deletion path, so the "write `@caret` before `text=`" rule (a caret left
+  past the shortened text lands at its end) is stated once.
+- **Every `TextField` subclass and composed field inherits both keys** —
+  `PasswordField`, the three numeric fields, `DateField`, `ComboBox`. Deletion
+  passes through no `insert_text`, so an input filter has nothing to say about
+  it (`D_input_filters`).
+- **A container under a text field can no longer bubble-bind Ctrl+U or Ctrl+W.**
+  The same rule that already covers printables and the editing keys, now two
+  keys wider.
+
+---
+
+## D_locale — `Locale`: the formatting conventions, and never the prose (2026-09-04)
+
+**Decision.** `Tuile::Locale` is a frozen `Data` value type of formatting
+conventions — `date_formats`, `calendar_start`, `first_weekday`, the four
+month/day name tables, `decimal_separator`. `Screen#locale` holds one, seeded in
+`Screen#initialize` from `Locale.system` (which shells out to `locale -k`), and
+`Screen#locale=` replaces it, firing `Component#on_locale_changed` across the
+tree and invalidating all of it. `Locale::ISO` is the only shipped constant and
+the universal fallback. `DateField#formats` / `#calendar_start` became
+nil-means-inherit readers over it, and `DateField.default_format` /
+`.default_calendar_start` are deleted (`D_date_field`, superseded).
+Graduated from `ideas/locale.md`, which is retired.
+
+**Why it became necessary.** Three components needed locale-shaped *data* and
+were about to grow three separate class-globals for it: `FloatField`'s decimal
+comma (`D_float_field` deferred it verbatim), a phase-2 calendar grid (which
+*cannot* be built without month names, since `Date::MONTHNAMES` is frozen
+English), and `DateField#formats` — whose two stopgap globals shipped the same
+day this was filed, marked "may change in the future" precisely because of this.
+
+**The boundary rule, which is the whole design.**
+
+> `Locale` holds formatting conventions — how a value is rendered and parsed.
+> It never holds prose.
+
+That sentence is what keeps this eight members instead of a subsystem, and it is
+the gate a ninth has to pass. A message catalogue — per-string lookup,
+interpolation, pluralization — is a different beast, and `D_bad_input` already
+ruled that wording arrives as *the wording fork* (a settable message, or a
+catalogue lookup inside `bad_input_message`), never as a redesign of the
+channel. The rule is not Tuile's invention: **POSIX draws the same line**,
+putting prose in `LC_MESSAGES` and formatting in `LC_TIME` / `LC_NUMERIC`.
+Reading only the formatting categories is what lets a session coherently want an
+English UI, ISO dates and a decimal comma at once — which is not a contrived
+example but the author's own machine, and the strongest single argument in the
+whole design.
+
+**Why a subprocess, which is a first for Tuile.** Ruby exposes no locale data at
+all, verified rather than remembered (3.3.8 / glibc): no `nl_langinfo` binding,
+no `D_FMT`, nothing on `Date` or in `Etc`; `Encoding.locale_charmap` is a
+charset and `RbConfig` has a path, not data. `Date::MONTHNAMES` is frozen
+English under any `LC_ALL`. And `strftime("%x")` is a **trap**, not a channel:
+it returned a fixed `"09/04/26"` under every locale tried *and*
+`Date.strptime("09/04/26", "%x")` parses, so `%x` in a format list is a silently
+American `%m/%d/%y` that would sail through a round-trip validator — hence the
+explicit rejection of `%x` / `%X` / `%c` with a message saying so, since that
+misconception is why this whole entry exists.
+
+`locale(1)` is POSIX and hands back **strftime patterns — Tuile's exact
+vocabulary**, so there is no second grammar to translate or keep correct, and
+one ~1 ms call spans both categories (libc resolves each keyword in its own).
+The honest cost, and the thing this decision actually has to argue: **a
+subprocess at `Screen` construction is new.** `ColorDepth.detect` is env-only;
+`TerminalBackground` is an OSC query on a stream Tuile already owns. The
+mitigations are that it is gated (below), that nothing in it can fail loudly,
+and that it is one call rather than one per keyword.
+
+**`-k`, not the bare keyword form.** Verified: `locale d_fmt bogus_key
+decimal_point` prints **two** lines for three keys, so positional parsing
+silently misaligns every later value — and that is exactly the shape of a
+keyword a non-glibc `locale` lacks (`first_weekday` is a glibc extension POSIX
+never defined). `-k` prints `key=value`, so a missing key is simply absent.
+
+**The exit status is useless in both directions**, also verified: a bad locale
+name prints to stderr, **exits 0** and silently returns the C locale
+(`LC_ALL=xx_YY.UTF-8 locale d_fmt` → `%m/%d/%y`), while an unknown *keyword*
+**exits 1** yet still prints every good key. So the status is ignored, stderr
+discarded, and each value validated on its own — falling back to its `ISO`
+member individually rather than all-or-nothing. That per-member fallback reuses
+the real constructor (`locale.with(member => value)` in a `rescue`) instead of
+restating the shape rules, so there is exactly one validator.
+
+**Detect only when the user said something — and gate it *per category*. This is
+the one judgement call the design rests on.** The C/POSIX default is American,
+so "said nothing" and "wants `%m/%d/%y`" are indistinguishable from the answer,
+and a container with no `LANG` would confidently show American dates to
+everyone. A *single* gate on "any locale variable is set" is wrong on a real
+machine: a session exporting only `LC_NUMERIC=de_DE.UTF-8` opens it, and then
+`d_fmt` resolves through an unset `LC_TIME` and an unset `LANG` to C's American
+pattern. So the date half is kept only if `LC_ALL` / `LC_TIME` / `LANG` speaks
+and the numeric half only if `LC_ALL` / `LC_NUMERIC` / `LANG` does, with unset,
+`C` and `POSIX` all counting as silence. One subprocess, two gates.
+
+**`en_GB`'s `d_fmt` is `%d/%m/%y`, and it gets fixed rather than fudged.** It is
+the case that survives doing detection *correctly*, and the fix is principled: a
+two-digit year cannot round-trip, because `Date.new(1962, 9, 4)` renders
+`"04/09/62"` and reparses as **2062** under Ruby's fixed POSIX window
+(`69`→1969, `26`→2026). So the detected primary is widened `%y`→`%Y` while the
+raw pattern stays in the *parse* list, and a Brit typing `04/09/26` is still
+understood — lenient in, strict out, `DateField`'s own design doing the work.
+**Widen at the probe, raise at assignment**, and that asymmetry is deliberate:
+the probe has no author to tell, an assignment does. It is not an inconsistency
+to iron out.
+
+That forced one **loosening of `D_date_field`'s validator**: only
+`formats.first` must survive a round-trip, since it is the only one ever
+*written*; a later entry only ever parses, so it needs merely to be a usable
+strptime pattern. Without it the detected list above is unrepresentable. It is
+backwards compatible (strictly more input accepted), and it improves the error
+message, which now says a `%y` pattern may still appear later in the list.
+
+**Why `Screen` is the home, objection and all.** The objection is real: a locale
+is a property of the *human*, and `Screen` is "the service" (`D_tree_first`).
+Three things answer it. (1) `Screen` is already the **environment** boundary,
+not just the terminal: it owns both existing environment probes and the
+dark/light *scheme* derived from one of them — and a colour scheme is every bit
+as much a property of the human as a date format is. The locale arrives from the
+same place: the process environment the session was launched in. One session,
+one locale, one `Screen`. (2) It is machinery by `D_tree_first`'s own split;
+nothing about the *tree* changes. (3) The alternatives are worse — a
+`Tuile.locale` module global reintroduces the spec-leak hazard that AGENTS.md
+warns about for `ThemeDef.default`, and a `bg_color`-style resolve-up-the-tree
+chain has no consumer asking for two locales in one process.
+
+**No `Locale.default`, and that is the interesting divergence from `ThemeDef`.**
+One was designed and dropped. `ThemeDef.default` exists because a theme *pair*
+is an app-authored artifact a whole spec suite needs every screen to carry; a
+locale is a **detected fact** whose app override is one line after `Screen.new`.
+So this follows the `ColorDepth` precedent instead: detect in `initialize`, pin
+in the fake, nothing global to leak or restore. The payoff is concrete — the
+spec-restore obligation `ThemeDef.default` and `VerticalScrollBar.handle_char`
+both carry simply does not exist here, because the next `Screen.fake` resets the
+only place the value lives. `Locale.system` is also **not memoized**: once per
+`Screen.new`, 1 ms, and a memo is one more thing a spec would have to reset.
+
+**Name tables are keyed by the `Date` accessor that reads them.**
+`month_names[d.month]`, `day_names[d.wday]` — so months are a `Hash` keyed
+`1..12` and days stay Ruby's 0-based `Array` verbatim. The differing shapes are a
+*consequence* of the rule, not an inconsistency, and the rule makes the
+off-by-one **unrepresentable rather than documented against**: a 0-based month
+array answers `month_names[9] # => "October"`, a plausible wrong answer,
+silently — the same failure class as `%y` reparsing as 2062 and an `%m`/`%d`
+swap no validator can see. Out-of-range answers `nil`. The cost is one `.values`
+where a month picker wants all twelve.
+
+**`calendar_start` belongs here, and the first answer that said otherwise was
+wrong for an instructive reason:** it conflated *probeable* with *belonging*.
+`locale(1)` has no keyword for the calendar reform date, but `Locale` was never
+defined as "whatever `locale -k` returns" — it is defined as *how a value is
+rendered and parsed*, and `calendar_start` is literally an argument to
+`Date.strptime`. It is also the most **regional** fact in the object (Italy 1582,
+England 1752, Russia 1918), one libc declines to expose only because nobody has
+needed it since. A member `Locale.system` never sets is fine; the *override*
+channel is the point, and an app in the pre-reform world now writes
+`ISO.with(calendar_start: Date::ITALY)` once instead of per field.
+
+**All eight members ship ahead of their consumers — an explicit, bounded
+exception.** By this entry's own no-consumer rule (which keeps `t_fmt` /
+`d_t_fmt` / `am_pm` out), v1 would have been
+`Data.define(:date_formats, :calendar_start)`: the grid does not exist and
+`decimal_separator`'s field-side work is deferred above. The author overruled
+that, and the reasoning is worth recording because it is an exception. The probe
+is one subprocess either way, so five more keys buy a rounding error; the
+expensive part is the *rulings* (the keying, the `first_weekday` conversion, the
+per-category gate), which were settled while fresh and are cheaper to encode in
+code than to re-derive later; and the rule's real target is *inventing*
+conventions nobody asked for, which these are not — two consumers are already
+filed. The boundary that keeps it from becoming licence: the time formats stay
+out, because their consumer is a `TimeField` nobody has filed. That is the
+difference between deferred and unimagined. (Filed since — `D_time_field`,
+2026-09-05, adds `time_formats` as the ninth member, and rules that the *seconds
+strip* is the field's policy rather than the probe's normalization, so the
+member carries `t_fmt`'s full precision; the expansion table stays at the
+boundary as this entry's rule requires.)
+
+**`locale=` invalidates the whole tree, plus one hook.** A locale change is a
+once-a-session event, so invalidate-all costs nothing worth optimizing, and a
+field losing a half-typed buffer to the new grammar is **accepted**: the text
+stays, the value goes nil, the field reads as bad input, and the user can see
+and fix it. Invalidation alone is not sufficient, though, and the reason
+generalizes: anything *pulled* at paint or parse time comes out right on the
+next frame, but anything **pushed** does not. `DateField`'s typing hint lives in
+its editor's `placeholder`, written when the formats were last set, so a repaint
+would faithfully repaint the stale `dd.mm.yyyy`. Hence `on_locale_changed`,
+shaped exactly like `on_theme_changed` (protected, `__send__` fan-out per
+`D_hook_visibility`, `super` from an override, plus an assignable listener for
+apps that compose rather than subclass). It stays a one-consumer mechanism by
+design: the calendar grid will read names at paint time and need nothing.
+
+**Roads not taken:**
+
+- *The `i18n` gem, or CLDR (`ruby-cldr`, `twitter_cldr`).* They have the data and
+  they are correct; they are also dependencies, and Tuile's *one* optional
+  dependency has a whole entry justifying it (`D_bigdecimal_field`, which says
+  explicitly that a second needs its own argument rather than that precedent).
+  Asking the system ships **zero** locale data, which keeps the no-catalogue rule
+  better than any bundled table could.
+- *`ENV["LC_ALL"] || ENV["LC_TIME"] || ENV["LANG"]` plus a locale-name → format
+  table.* This is the cheap version, and it is the catalogue **plus** a
+  reimplementation of libc's precedence chain. It gets the author's machine wrong
+  twice over (reading `LANG=en_US` for both categories, where the compiled data
+  says otherwise for each), and it gets `en_DK` wrong unless the table happens to
+  carry it. The subprocess's value is not that it reads env vars — it is that it
+  reads the **compiled locale data**, per category.
+- *A `TUILE_LOCALE` env override*, for symmetry with `TUILE_COLOR_DEPTH`. A whole
+  locale does not fit in an env var without inventing a serialization, and the pin
+  a PTY spec needs already exists: pass `{"LC_ALL" => "C"}` in the env hash it has
+  to pass anyway for the colour-depth reason, or a real locale name to exercise
+  the real path. Unit specs need nothing — `FakeScreen` pins `ISO`.
+- *Preset constants (`Locale::EN_US`, `::DE`, …).* Two presets are a catalogue, a
+  catalogue implies completeness, and `en_GB`'s own `%d/%m/%y` shows how
+  opinionated even a "correct" entry is. Apps build theirs with `ISO.with(...)`;
+  Tuile hands over the gun and ships no ammunition. The name helps — `ISO` names
+  a *standard*, not a country, and three of its members cite it.
+- *Mirroring `Date::MONTHNAMES`' 13-entry array with `nil` at index 0.*
+  `[d.month]` would work, at the price of a `nil` hole in a frozen value type —
+  worse than the `Hash`, and it makes "12 names" unexpressible as a shape check.
+- *Making the day tables `Hash`es too.* Deferred, with a trigger rather than a
+  shrug: the only real argument is a future "widest name in this table" helper for
+  the grid's column arithmetic, which reads `.values` on a `Hash` and the table
+  itself on an `Array`. Until the grid exists, re-keying `Date::DAYNAMES` is
+  transformation noise in a constant whose virtue is being Ruby's data verbatim.
+- *Validating the probe's answer as a whole.* Rejected in favour of per-member
+  fallback: one odd keyword on one distro would otherwise discard a `d_fmt` that
+  was perfectly good.
+- *Trusting `locale`'s exit status*, or reading `t_fmt` / `am_pm` "while we are
+  in there". The first is measured to be meaningless; the second is the
+  no-consumer rule, which the eight-member overrule above explicitly does not
+  extend to.
+
+**Known-unverified, and deliberately so.** macOS / BSD `locale -k` keyword
+support is believed fine but unchecked (CI is `ubuntu-latest` only), and
+`first_weekday` is a glibc extension likely absent there. This is safe to leave
+open precisely because of the `-k` shape and the per-member fallback: an absent
+or odd key degrades to its `ISO` value with nothing raised. A missing binary
+(Windows, some musl containers) yields `ISO` whole, and Windows' gate never opens
+anyway.
+
+## D_empty_ancestor — An empty rect propagates down, and the drain filter enforces it (2026-09-04)
+
+**Status:** Accepted; implemented 2026-09-04 in `Layout::Box#relayout`,
+`Screen#repaint`'s drain filter and `Screen#initialize`, with `Box#add`'s `at:`
+and `Box#constrain` alongside. Reported downstream by pikuri-tui as issue #17.
+Leans on `D_repaint_cascade` (the same bug shape one layer up — a notice that
+must keep travelling down), `D_tabs` (hiding is detachment; the `visible?`
+re-grow rule), `D_box_layouts` (the sugar this amends) and `D_extent` (why an
+empty rect is a *paint* convention and gates nothing else).
+
+**Context — the symptom.** pikuri-tui's coding shell hides its sidebar column by
+handing it a zero-width rect. The two panes inside it are `Layout::Vertical`s,
+which kept the rects they had while visible. Nothing painted them — until the
+user closed the `Ctrl+K` leader menu, a popup, and `Screen#remove_popup`'s
+`needs_full_repaint` invalidated **every** component directly. The sidebar came
+straight back, and, being later in tree order, over the conversation pane's
+scrollbar column. Every subsequent popup open/close flickered it away and back.
+
+**The mechanism.** `Box#relayout` opened with `return if rect.empty?`, so a box
+whose own rect went empty never assigned its children. The branch immediately
+below it does exactly the right thing — `children.each { _1.rect = … 0, 0 }` for
+an empty `inner_rect` — and the guard made it unreachable. Three paths refuse to
+paint the resulting stale subtree (`Component#repaint`'s own empty-rect return,
+the default container `repaint` cascading only from a non-empty parent, and
+`Screen#repaint`'s detached filter), which is why it stayed hidden;
+`needs_full_repaint` bypasses all three.
+
+A sweep says the fault is `Box`'s alone: `Window#layout_footer`, `Slot#layout`
+and `TabSheet#rect=` all let an empty rect fall through to the arithmetic and
+zero their children correctly. `Box` was also inconsistent with *itself* — an
+over-subscribed child is already starved to an empty rect and placed anyway.
+
+**Decision — a container propagates its own empty rect to every child.** The
+guard conflated *"no rect yet"* with *"rect deliberately emptied"*, and only the
+first ever needed protecting; it survives the deletion, because during
+construction the children are already empty (so the assignments are no-ops) and
+the trailing `invalidate` returns early while detached. This is the load-bearing
+half: it is what makes `cursor_position` answer `nil` for a collapsed field, and
+so what stops the hardware cursor parking inside the *visible* pane.
+
+**Decision — `Screen#repaint`'s drain filter is ancestor-aware.** The filter
+already dropped detached components; it now also drops a component with an empty
+rect anywhere on its ancestor chain. This is not new policy — `Component#repaint`
+gates each component on its *own* empty rect, and this is that same gate made to
+see one hop further — so it removes an inconsistency rather than adding a rule.
+The point is that it holds for a container that has **not** been fixed, including
+an app's own `Absolute` subclass: a forgetful container now leaves an inert
+subtree instead of a subtree that paints at stale coordinates. It is also a
+strictly narrower repaint set, so marginally cheaper.
+
+**Consequence — the pane is sized in `Screen#initialize`.** `@pane.rect` used to
+be assigned only by `#layout`, which runs from the event loop; under the new
+filter an unsized pane is an empty *ancestor* rect for the entire tree, and every
+`FakeScreen`-driven repaint painted nothing. Seeding it at construction, exactly
+as `#size` is already seeded from `TTYSizeEvent.create`, is the honest fix: it
+makes the fake match production, where `#layout` runs before anything paints.
+`FakeScreen` re-seeds it after resizing itself to 160×50.
+
+**Decision — a collapse is not hiding, and `Box` lets you re-place a child.**
+The issue proposed a `visible` property with Android's `INVISIBLE` / `GONE`
+split. What this entry settled is the measurement that any such flag has to
+honour: geometry cannot express hiding, because `tab_stop?` does not consult
+geometry and must not. A zero-rect sidebar keeps its tab stops and still takes
+keys **after** this fix — the fix only stops it painting and moves its cursor
+off-screen. So `Fixed[0]` is *collapse*, not hide, and its rdoc says so. The
+flag itself was deferred here under `D_tabs`' re-grow rule and has since been
+accepted as `D_visibility`, as the full focus-and-paint gate this measurement
+demands; that entry owns hiding now.
+
+What pushed pikuri-tui into the zero-rect idiom is that detachment — the answer
+at the time — was not expressible in a `Box`: `Box#add` had no `at:`, so a
+removed child came back at the end of a multi-child box, and a child's
+constraints could not be changed after `add` at all. Both are closed —
+`add(child, main, at: i)` and `constrain(child, main = nil, cross: nil, align:
+nil)`, the latter `nil`-means-keep so one axis moves alone — and both stay
+useful beside the flag: `remove` / `add(…, at:)` is the move when the lifecycle
+hooks *should* fire.
+
+**Roads not taken.**
+
+- **A `Component#paintable?` predicate** for the filter to call. Rejected: it
+  reads as a component-level concept ("am I paintable?") when it is one screen's
+  drain-time question, and it would be a new public predicate every component
+  answers. The AND is spelled at the one call site instead.
+- **Fixing `needs_full_repaint` alone**, as the issue proposed. It is the path
+  that surfaced the bug, but not the only one that can reach a stale subtree, and
+  the invariant belongs at the single choke point every invalidation drains
+  through.
+- **Blanking the cells a collapsed subtree vacated.** Deliberately not attempted.
+  `clear_outside_extent` reaches an L, never an interior hole, and the general
+  version is the rect-subtraction geometry `D_repaint_cascade` already declined
+  in the hottest path. In a tiled layout a sibling grows into the space and
+  repaints, which is what happens in pikuri-tui and in `#constrain`'s
+  `Fixed[0]`-gives-its-space-to-siblings spec. The minimal repro — a root box
+  emptied by nobody, so no sibling exists — keeps its stale glyphs, and that is
+  the artificial case.
+- **Making a collapsed child cost no `Box#spacing`.** A `Fixed[0]` child still
+  leaves the gap around it. Changing that would also change over-subscription
+  starvation, which shifts existing layouts, and `D_box_layouts` holds that a gap
+  belongs to the *sequence*. Documented on `Fixed` instead. `D_visibility`
+  draws the line: a collapsed child is still a member of the sequence and keeps
+  its gap; a *hidden* one is not, and costs nothing.
+
+## D_component_contract — A contract suite over a catalog of every component (2026-09-04)
+
+**Status:** Accepted; `spec/tuile/component_contract_spec.rb` added 2026-09-04
+with three invariants and a completeness guard. Prompted by `D_empty_ancestor`,
+whose bug the suite would have caught. Leans on `D_repaint_cascade` and
+`D_progress_bar` (two of the three invariants are their rules), and on
+`D_component_lookup` (the other additive-to-the-assertion-channel testing tool).
+
+**Context.** Tuile's per-widget specs are thorough and all of them share a blind
+spot: they assert what *their* widget paints, in *its* rect, after *one*
+repaint. Three framework-wide obligations are invisible from there. A widget
+that overruns its rect paints on a *neighbour*. A widget that blanks a cell it
+is about to repaint marks it dirty, so `flush` re-emits it — identical on screen.
+A container that fails to zero its children's rects strands them, and nothing
+paints until an unrelated full repaint does. All three fail with no exception
+and no red example; `D_empty_ancestor` shipped for exactly that reason, and
+`D_repaint_cascade`'s bug was found by a hand-rolled sweep, which is the same
+observation made once and then thrown away.
+
+**Decision — one suite, run over a catalog, with a guard that makes enrolment
+mandatory.** The catalog maps each concrete `Component` subclass to a factory
+returning one populated enough to paint; the guard eager-loads `lib/` and fails
+on any subclass in neither the catalog nor an `excluded` map that carries a
+reason per entry. The eager load is the load-bearing half: Zeitwerk resolves on
+first reference, so without it the guard would see only the classes the catalog
+itself named — it could never spot the new component it exists to spot. The
+value is entirely in the components that *do not exist yet*; a suite you have to
+remember to extend is a suite that documents the day it was written.
+
+**Decision — a violator is `pending`, never `skip`.** RSpec fails a `pending`
+example that starts passing, so a fix prompts deleting its entry; a `skip` would
+let the deviation outlive its reason. The distinction matters because the first
+run found one (below), and the temptation was to widen the check's precondition
+until it went quiet — which is how a suite becomes decoration.
+
+**What the first run found.** `Component::Window` and its four subclasses
+re-emit their whole border on every unchanged repaint: `Window#repaint` calls
+`super`, whose default clears the rect because the content slot does not tile it
+(it is inset by the border), and then `repaint_border` redraws the border over
+the cells just blanked. Measured at **925 bytes per unchanged 80×24 repaint**,
+paid on every focus change, since that invalidates the whole focus chain and
+every enclosing `Window` is on it. Note AGENTS.md asserted the opposite —
+"components that paint their entire rect themselves (currently `Window` … and
+`List`) opt out" — which is true of `List` and was never true of `Window`. Left
+**fixed the same day**, and the fix was smaller than the guess: not an override
+of `children_tile_rect?` but `Window#repaint` dropping `super` for
+`invalidate_children` plus `clear_background(content_rect)` on the one path
+nothing else covers — a window with no content in it. Nothing had to change
+about a shrinking content rect, because the content rect is derived from the
+window's own (`Window#content_rect`, extracted for this) and so cannot shrink
+independently of it. The check found a second instance while measuring the
+first: with `scrollbar = true` the window drops its right border so the
+content's bar can own that column, but `repaint_border` painted `│` down it
+anyway before the bar covered it, dirtying the column into every frame —
+270 bytes an unchanged frame, now 0. Both are pinned in `window_spec`; the
+`pending` entry is gone, which is the mechanism working as designed.
+
+**Alternatives rejected.**
+
+- **Runtime enforcement in the framework**, the way `Tuile::Final` guards the
+  tree methods. Right for a rule with a cheap check at a single call site;
+  wrong for these, which need a *painted buffer* to compare against. Verifying
+  "painted nothing outside its rect" at runtime means bounds-checking every
+  `Buffer` write against the painting component's rect — a check in the hottest
+  path, for a bug that a test catches once per CI run.
+- **Auto-discovering instances instead of a catalog** (walk `lib/`, call
+  `klass.new`). It fails on every component with a required argument and, worse,
+  yields *empty* components — an unpopulated `List` paints nothing, so every
+  invariant passes vacuously. The factories are the point: the catalog is a set
+  of canonical, painted specimens, and writing one is the work.
+- **Folding these into `component_spec.rb`.** That file already has the pattern
+  — "keeps children, `@children` and the parent pointers in agreement" walks a
+  tree of every container kind — but it is the spec *for* `Component`, mirroring
+  `lib/tuile/component.rb` per the one-spec-per-source-file rule. A suite whose
+  subject is "every component" mirrors no file, so it is a sibling of
+  `nomenclature_spec.rb`: a guard, named for what it guards.
+- **Starting with more invariants.** Screen-free construction, `extent` honesty
+  ("a component paints every cell it declares"), and `bg_color` inheritance were
+  all drafted and cut. Three that hold and are understood beat eight where two
+  are half-true — a suite with a hedged invariant teaches contributors to widen
+  preconditions rather than fix code.
+
+## D_visibility — `Component#visible=`: a *gone* flag, kept in the tree (2026-09-05)
+
+**Status:** Accepted and implemented 2026-09-05 — `Component#visible=` /
+`#visible?` / `#on_shown_tree` / `#on_child_visibility_changed`, the gates in
+`Screen`, `ScreenPane`, `Layout`, `HasContent`, `Box`, `Overlay` and `Testing`,
+a `component_contract_spec` invariant over the whole catalog, book ch5 + ch7 and
+a sampler pane (Shell ▸ Visibility). Brainstormed in `ideas/visibility.md`, with
+a 24-toolkit precedent survey beside it; both retired. Satisfies the re-grow
+rule `D_tabs` recorded and supersedes `D_empty_ancestor`'s "hiding is still
+detachment".
+Leans on `D_slots` (an empty slot keeps its space — the *other* state),
+`D_box_layouts` (a gap belongs to the sequence), `D_overlay` (an overlay is
+dismissed, not hidden), `D_attach_hooks` (what a hidden component keeps
+running), `D_component_lookup` (the locator's contract) and
+`D_component_contract` (where the new invariant is enforced).
+
+**Context.** A form hides fields on choices above them — "Company name" only
+when "Business customer" is ticked. After `D_empty_ancestor` the sanctioned
+way to hide was `box.remove(field)` and `box.add(field, Fixed[1], at: i)`, and
+three things make that the wrong tool for exactly this consumer: the app has to
+know `i`, which shifts under it (an insert above, or two fields re-shown in the
+other order, and they land in each other's places — a shadow copy of the child
+order, the very thing `D_tree_api` forbids the framework from keeping, pushed
+onto every app); `remove` drops the child's placement, so the show path re-states
+`Fixed[1], cross: Fixed[30]` from somewhere; and detachment fires the lifecycle
+hooks, which is wrong for a pane that must stay live while hidden (a running
+job, a subscription). The two geometric idioms fail too, measured in
+`D_empty_ancestor`: `Fixed[0]` keeps its `spacing` gap and its tab stop, and a
+`Slot` with no content keeps its row. `D_tabs`' re-grow rule asked for a second
+consumer and a ruling on layout arithmetic; this is both. Note that `D_tabs`
+argued against *zero-rect* hiding and for detachment as `TabSheet`'s
+implementation — it never argued against a flag.
+
+**Decision — one boolean, meaning *gone*.** `Component#visible?` /
+`#visible=`, default `true`. `false` means: **as if detached — but it stays in
+the tree.** Paints nothing, takes no space in a `Box`, and is invisible to
+focus, keys, the cursor and the mouse, exactly as a detached component is; and
+unlike one it keeps its parent, its rect, its placement, its state and its
+running resources, so no lifecycle hook fires. Say it that way and not "hiding
+is detaching" — the analogy is about what the *user* can reach, and the one
+place it breaks is the one an implementor would otherwise assume: `on_detached`
+is never called. This is Android's `GONE`, and only `GONE`. The keep-the-space state
+(`INVISIBLE`) is not a second value: a `Slot` whose content is `nil` already
+*is* that (`D_slots`), so Tuile has both Android states with no enum. The
+survey says this is the industry shape, not a Tuile shortcut: where a single
+boolean exists (Qt, GTK4, Vaadin, Lanterna, WinForms, AppKit stack views,
+Flutter's `Visibility`, Textual's `display`, FTXUI's `Maybe`, Tk's `grid
+remove`) it means gone, and keep-the-space is everywhere the opt-in
+(`retainSizeWhenHidden`, `maintainSize`, `setHonorsVisibility(false)`,
+`detachesHiddenViews = false`). Named `visible`, positive: a caller wanting a
+thing shown writes `visible = true`, never `hidden = !x`; it is also the name
+the re-grow rule used and the sibling of `scrollbar_visibility`.
+
+**Decision — the gates live on the component tree, not in the containers.**
+The flag is ancestor-inclusive: a component is *shown* iff it and every
+ancestor are `visible?`, and every walk prunes the hidden subtree at its root
+rather than testing leaves, so a `TextField` three levels under a hidden panel
+is skipped without knowing it. The gates, and where each sits:
+
+- **Paint:** `Screen#repaint`'s drain filter — the one choke point every
+  invalidation passes — drops a hidden component or one under a hidden
+  ancestor. Same AND as `D_empty_ancestor`'s empty-rect term, one more term.
+  `invalidate` keeps recording; showing again re-invalidates the subtree
+  (`on_tree`), as `bg_color=` does.
+- **The parent's gap clear:** `children_tile_rect?` excludes hidden children, so
+  a hidden child's cells count as a gap and the parent blanks them. This is what
+  actually erases the field in a container that never re-assigns its rect.
+- **Focus walks:** `Screen#cycle_focus`, `ScreenPane#first_tab_stop_or_root`,
+  `Layout#on_focus` and `HasContent#on_focus` prune hidden subtrees, through one
+  shared walk helper rather than four copies of the rule.
+- **Focus assignment:** `Screen#focused=` raises on a hidden target, as it does
+  on a detached one. Focusing what the user cannot see is the cursor-in-the-
+  visible-pane bug of `D_tabs`, and it should fail at the call site.
+- **Mouse:** `Component#handle_mouse` skips hidden children — belt to the
+  empty-rect braces, since an `Absolute` child keeps its rect.
+- **Cursor and keys** follow: the focused component is always shown, and a
+  hidden one is never on the focus chain.
+- **Lifecycle: nothing fires.** `on_attached` / `on_detached` stay bound to
+  `parent=`. That is the feature — the hidden-but-live pane.
+
+Why component-side: a hidden child that keeps a stale rect is then *harmless*
+in every container — it paints nothing, its cells are blanked, it takes no
+focus and no clicks — so a container that never heard of the flag degrades to
+a hole rather than to a leak. That inverts `D_empty_ancestor`'s failure mode,
+where every container between the app and the leaves was a separate chance to
+forget.
+
+**Decision — the layout arithmetic.** `Box` skips a hidden child entirely: out
+of the `count` that prices `spacing * (count - 1)`, no share of `available`, and
+assigned the empty rect at the box's origin (the rect its `inner.empty?` branch
+assigns). Its placement entry is **kept**, so `visible = true` puts it back with
+its constraints intact. This is the one place gone reclaims space, and it makes
+a `spacing: 1` form close up cleanly. It settles the point `D_empty_ancestor`
+left open: a collapsed (`Fixed[0]`) child is still a member of the sequence and
+keeps costing its gap; a hidden child is not, and costs nothing. Every box
+layout in the survey prices spacing over shown children only (Qt's
+`previousNonEmptyIndex`, GTK's `(n_visible_children - 1) * spacing`, Lanterna,
+AWT `FlowLayout`, Android `LinearLayout` and its dividers, AppKit); the one
+double-gap trap is Swing `BoxLayout`, and only because its gaps are strut
+*components* — Tuile's `spacing` is a number, so it cannot fall into it. `Box`
+learns of a flip through one protected upward hook,
+`on_child_visibility_changed(child)`, default no-op, the shape of
+`on_child_removed`; a future `FormLayout` overrides it too. `Absolute` does
+nothing — its `rect=` is app arithmetic, and an app that wants the space
+reclaimed reads `child.visible?` in its own pass. `Window` / `Popup` / `Slot` /
+`HasContent` have one child and nothing to reclaim; hidden content leaves the
+inner area blank, as an empty `Slot` does, and a `Window` keeps its border.
+
+**Decision — hiding the focused subtree repairs focus through the parent, never
+to `nil`, and never restores on re-show.** When the flag lands on the focused
+component or an ancestor of it, focus goes to the hidden component's parent and
+the parent's ordinary `on_focus` cascade takes it from there (a `Layout` to the
+first *shown* tab stop in its subtree, a `Window` into its content, the
+`ScreenPane` through its own repair). This is the focus-repair half of
+`Component#on_child_removed`, reused as-is, so the two ways a subtree can
+leave the user's reach land focus in the same place and are specced once —
+only the repair is shared, not the detach; the hidden component keeps its
+parent and hears no hook. `nil`
+was the other candidate and it is not neutral in Tuile: `ScreenPane#focus_chain`
+returns nil, `bubble_key` delivers to nobody — not even the scope root, so a
+form's Enter-to-submit goes dead — and the next unhandled `q` or ESC falls
+through to the loop and **quits the app**. The DOM's focus-to-viewport works
+because a browser has no quit key. Nothing is restored when the component
+reappears — no toolkit surveyed does, and a stored "focus to restore" is one
+more pointer into a tree that may have changed. Prior art, verified against
+source: DOM moves focus to the viewport, and Chromium resumes Tab from the
+removed node's *parent* (the shape chosen here); Swing (`hide` →
+`transferFocus(true)`) and Qt (`hide_helper` → `focusNextPrevChild(true)`, also
+when an ancestor is hidden) go to the **next** component; Android `GONE` clears
+and lands on the **first** focusable from the top; Textual's `display = False`
+does *not* reset focus, so its `focused` goes stale — the leak `D_tabs` listed,
+shipped.
+
+**Decision — `Testing.find` never finds a hidden component.** Karibu-Testing's
+standing policy, held for years: a test is a user, and a user cannot click what
+is not on the screen; a locator that reached a hidden `Button` would pass a form
+the user cannot operate. So `find` / `get` prune hidden subtrees with the same
+walk the focus gates use. The failure message then **counts the hidden matches
+it excluded** — `found 0 (1 hidden match excluded)` — because "I *know* it's
+there" is the commonest confusion and one clause diagnoses it; and `dump` shows
+the whole tree, `inspect_details` adding `hidden` and the excluded matches
+getting their own marker beside the `→` of found ones. **No `visible:` filter.**
+A test asserting a field *is* hidden holds the reference and asserts
+`refute field.visible?`; one asserting the user cannot reach it asserts
+`count: 0`, which is what the user experiences. A filter reaching hidden
+components is the same hole as `_setValue` on a disabled field, and comes back
+only argued from a test that cannot be written otherwise.
+
+**Decision — overlays refuse the flag; `TabSheet` stays on detachment.**
+`visible=` raises on an `Overlay`: it is dismissed, not hidden (`D_overlay`),
+the "live while hidden" motivation does not apply, and the pane consults
+`@popups` for hit-testing and `modal_popup` for key scope — a hidden popup that
+was still modal and still caught clicks is the `focusable?`-and-`modal?` trap
+again. `TabSheet` keeps detaching: the lifecycle hooks on switch are a feature
+the book teaches, and switchers split evenly in the survey (Textual, Swing,
+Android, Qt, GTK on the flag; urwid, Flutter, SwiftUI, AppKit on detachment). A
+keep-alive pane, if wanted, would use GTK's split — a container-only
+`child-visible` beside the public `visible` — and is deliberately not this
+entry.
+
+**Consequences.** The contract suite gains a fourth invariant — *a hidden
+component paints nothing, is not in the Tab cycle, and reappears where it was
+with its constraints* — over the catalog. AGENTS.md's "Hiding a component means
+detaching it" becomes "hiding is `visible = false`; `TabSheet` detaches for the
+lifecycle hooks", and book ch7's section of that name is rewritten; `Fixed`'s
+collapse note gains "a hidden child costs no gap". `visible?` is a second reason,
+beside the empty rect, for a component not to paint, and the two are different
+axes: geometry says *where* and *how much*, the flag says *whether*.
+
+**Roads not taken.**
+
+- **A `Hidden` / `Gone` `Box` constraint** (`constrain(field, Gone)`). Parent-side
+  only, so it reclaims space and leaves every focus leak `D_tabs` listed — it is
+  `Fixed[0]` with better branding, the exact thing `D_empty_ancestor` refused.
+- **An enum** (`:visible` / `:invisible` / `:gone`). The middle state is a `Slot`
+  with no content, a hidden-but-space-keeping field has no form use, and an enum
+  invites `:disabled` next.
+- **`visible=` as sugar over `remove` / `add(at:)`.** Fires lifecycle, loses the
+  live-while-hidden case, and only `Box` could implement it — an `Absolute` has
+  no `at:`.
+- **A public `shown?` reader** for the effective state. The walks prune at the
+  hidden root and need none; a reader that walks ancestors is one more thing to
+  keep un-cached. Add only when an app needs it.
+- **"Next tab stop" focus repair**, the Swing/Qt answer. Implementable (collect
+  stops, pick the successor, before hiding) but then hiding and removing a
+  focused subtree would land focus in different places; if it is ever wanted,
+  change `on_child_removed`'s repair and this in one move so they stay one rule.
+- **A `hidden` / `hidden=` name** (HTML's attribute, AppKit's `isHidden`).
+  Negative names make callers negate what they want.
+
+## D_time_field — `TimeField`: a `Time` on a fixed epoch; `step` owns the precision (2026-09-05)
+
+**Status:** Accepted and implemented 2026-09-05 — `Component::TimeField`,
+`Locale#time_formats`, `Locale::TimeFormats`, the `Locale::Formats` lexer hoist,
+a spec mirror, a `component_contract_spec` catalog entry, book ch7 + ch10 and a
+sampler pane (Input ▸ Typed ▸ TimeField). Graduated from `ideas/time-field.md`,
+now retired. Both verifications the design was pending held: Rails casts
+`"13:45"` to `2000-01-01 13:45:00 UTC`, so the epoch is *alignment* rather than
+invention; and Ruby's `strptime` accepts `1:45pm`, `1:45 PM`, `1:45PM` and
+`1:45 pm` alike under `%I:%M %p`, so the feared spaceless-secondary workaround
+was never needed.
+`D_date_field`'s twin — every ruling not questioned here is inherited from that
+entry verbatim: the format list consumed in order with `formats.first` writing
+back, no input filter, the red well latched to the commit gestures,
+canonicalize on blur and ENTER, the placeholder derived exactly or not at all,
+`MAX_TEXT_LENGTH = 64`, a frozen `bad_input_message`. Gives `D_locale` its ninth
+member. Two findings in this entry are marked **surveyed** — read off another
+toolkit's docs or source — as distinct from **verified**, which means run in this
+repo's Ruby.
+
+**Context.** A one-row field whose value is a *local time of day* — a wall-clock
+reading with no date and no zone; `09:30` means half past nine wherever you are.
+It is the twin `D_date_field` predicted and `D_locale` explicitly left out
+("the time formats stay out, because their consumer is a `TimeField` nobody has
+filed"). Two things make it more than a copy: Ruby has no civil-time class, so
+the value type has to be *decided* where `DateField` could point at `Date`; and
+a time has a **precision** — seconds or not — which a date does not, and which
+turns out to be the one genuinely new ruling.
+
+**Decision — the value is a `Time` pinned to `2000-01-01` UTC, so the component
+is `TimeField`.** Four candidates, priced by `D_float_field`'s naming rule (a
+typed field is named after the Ruby class of its value):
+
+| Value | Component | Cost |
+|---|---|---|
+| `Time` on a fixed epoch date, in UTC | `TimeField` | the value is a real *instant*, so it can be passed where an instant is wanted |
+| `Tuile::LocalTime` (`Data.define`) | `LocalTimeField` | Tuile ships a domain value type; every app converts at its own boundary |
+| `Integer` seconds since midnight | — (`IntegerField` by the rule) | indistinguishable from a duration; the name is not derivable |
+| `String` | — | that is a `TextField`; no typed field at all |
+
+`Time` wins on a sharpening of `D_date_field`'s "Tuile's job is to edit the
+app's values, not to introduce its own", which needed sharpening precisely
+because there is no stdlib type to defer to: **Tuile owns UI value types —
+`Point`, `Size`, `Rect`, `Fraction`, `Color`, `StyledString`, `Theme`,
+`Locale` — and no domain value types.** A time of day is domain data: it lands
+in a model, a column, a serializer. And the ecosystem's near-consensus is
+exactly this shape — a `Time` on a dummy date is what Rails' `time` column hands
+you. The epoch is `2000-01-01` **pending one verification** (Rails' date, from
+recollection; `gem install activerecord` and cast `"13:45"`); if it holds, an
+ActiveRecord round-trip is exact and the choice is *alignment with an existing
+convention*, the strongest version of the argument. `Sequel::SQLTime` is
+recalled to default to *today*, class-configurable, so no fixed epoch could match
+it and Rails is the one convention available. **UTC, not local:** a local epoch
+puts every value on a date whose offset the zone can change, so a transition on
+the epoch date makes some wall times unrepresentable or silently shifted — the
+whole DST class, removed. Cells still read correctly (**verified**:
+`Time.utc(2000,1,1,13,45,0).strftime("%H:%M") == "13:45"`).
+
+The accepted cost, stated loudly in rdoc: the value is an instant, so it is
+*wrong* somewhere else while being a perfectly good `Time` —
+`field.value = Time.now; field.value == Time.now` is `false` (**verified**;
+different date, different zone). An app that forgets to combine it with a date
+gets the year 2000 in its output, which is *visible*, and by this project's
+standard beats silently wrong. `value=` is thin and lenient the way
+`DateField#value=` is: anything responding to `hour` / `min` / `sec` is taken by
+those readers and rebuilt on the epoch (`Time`, `DateTime`, `Sequel::SQLTime`);
+`nil` clears; a `Date` raises `TypeError` (no hour to take — accepting it means
+inventing midnight) and so does a `String` (that is what the buffer is for; a
+`value=` that parsed would be a second parse path with its own leniency);
+sub-seconds truncate silently. Three ergonomics, so no caller ever assembles a
+`Time` on the epoch by hand: `#set_to(hour, minute, second = 0)` and
+`#set_to_now` to *write* one, and `.time_of_day(hour, minute, second = 0)` to
+build a value to *compare* against, plus the epoch public as `MIDNIGHT`.
+
+**The class method is deliberately not named for the class.** It shipped as
+`TimeField.at` and was renamed on review: every other class method on a
+component here (`ConfirmWindow.alert`, `Notification.show`) returns an
+*instance*, so `TimeField.at(13, 45)` reads as a constructor while returning a
+`Time` — the one thing a reader should not have to check. `time_of_day` says
+what comes back, and the wordiness is free because the rename also moved the
+common case off it: setting a field is now `field.set_to(13, 45)`, and the
+factory is left with the rare read-side job of building something to compare a
+value against. Deleting it outright was the other candidate and is worse: it
+pushes `Time.utc(2000, 1, 1, …)` — the hand-written epoch this exists to
+prevent — into every spec and every app that checks a value it got back.
+`#set_to_now` is sugar rather than a fix (an app writing `value = Time.now` is
+already corrected by the buffer round-trip), but it names a concept the field
+already had: it is where Up/Down land an empty field.
+
+**Decision — the parse has a third gate, because `Time` normalizes where `Date`
+raised.** `D_date_field`'s parse is two gates — a non-empty `:leftover` is no
+match, and constructing the `Date` catches February 30th. The second does not
+transfer (**verified**): `Date._strptime("24:00", "%H:%M")` yields
+`{hour: 24, min: 0}` and `Time.utc(2000,1,1,24,0,0)` is *the next day*;
+`"13:45:60"` parses and `Time.utc(…,13,45,60)` is `13:46:00`. Both are
+wrong-values-that-save-cleanly, and the rollover is worse than it looks — a value
+past midnight lands on a *different date* from every other value the field
+produces, so comparison and sorting quietly break. So `TimeField` range-checks
+`hour` 0..23, `min` 0..59, `sec` 0..59 itself, `Time.utc` becomes construction
+rather than validation, and **`.time_of_day` and `#set_to` share the one gate** —
+building normalizes just as silently as parsing, and a spec comparing against
+`time_of_day(24, 0)` would pass against the wrong date. `Date._strptime` already
+range-checks the *field width* (`"25:00"` and `"13:99"` yield `nil`,
+**verified**) and gives padding leniency for free (`"1:45"` under `%H:%M`). `24:00`
+being rejected costs one documented sentence: it is legal ISO 8601 end-of-day
+and `Time` cannot hold it. No new `require`: the parse is `Date._strptime`
+(`date` is hoisted per `D_date_field`), `Time` is core, and `Time.strptime` — the
+one thing needing `require "time"` — is not used.
+
+**Decision — minute precision by default; `step` is the precision knob; there is
+no per-field `formats=`.** The ruling that is new to this field:
+
+> **Precision is not a spelling.** A format list is ordered leniency, and for
+> time the order also decides *how much of the value survives a commit*. Only the
+> widening direction is lossless: with `%H:%M:%S` primary, typing `13:45`
+> canonicalizes to `13:45:00` and adds nothing false. With `%H:%M` primary,
+> typing `13:45:30` canonicalizes to `13:45` and **loses the seconds** — the
+> buffer is the single source of truth, so truncating the buffer truncates the
+> value.
+
+So the default shows minutes and `13:45:30` is bad input — visible, reportable,
+fixable — and an app that wants seconds sets `step` below a minute. The field
+has **one** precision-bearing knob and it is the stride: **`step < 60` shows
+seconds, `step >= 60` does not**, Vaadin's rule and HTML's, and the whole of it.
+`formats` is a **read-only report**, derived on every read from `Screen#locale`
+and `step`: it exists so the placeholder, the rdoc, the specs and a curious app
+can name the list in force, and for the reason `Component#size` exists — to
+squat the name, so a writer can only return through the re-grow rule below.
+The escape hatch is `screen.locale=`, exactly as Vaadin's is `setLocale()`: an
+app wanting a spelling the probe did not find assigns a `Locale` and every
+`TimeField` follows, which is what a *convention* is. No `precision` reader
+either — `formats` squats the name that matters, a `precision` reader invites
+"where is the writer?", and the API is one rdoc sentence.
+
+The survey that settled the default (**surveyed** 2026-09-05):
+
+| Toolkit | Default precision | Seconds | Knob |
+|---|---|---|---|
+| Vaadin `TimePicker` | `hh:mm` | yes | `step` (`Duration`), default 1 hour |
+| HTML `<input type="time">` | `hh:mm` | yes | `step`, default `60` |
+| MUI X `TimePicker` | hours + minutes (+ meridiem) | yes | `views:` array |
+| Qt `QTimeEdit` | locale **ShortFormat** (en_US `h:mm AP`) | yes | `displayFormat` string |
+| Flutter `showTimePicker` | hour + minute | **none** — `TimeOfDay` has no field for them | — |
+| Taiga UI `InputTime` | `mode` enum, `HH:MM` … `HH:MM:SS.MSS` | yes | `mode` |
+| WinForms `DateTimePicker` | OS **long time**, `h:mm:ss tt` | shipped | `CustomFormat`, to *remove* them |
+| Ant Design `TimePicker` | `HH:mm:ss` | shipped | `format` string |
+
+Six of eight default to minutes. The useful half is *which two dissent, and
+why*: WinForms inherits the OS *long time* pattern and Ant Design simply picked
+a format — both a clock-display format used as a form-field format, putting
+`:00` in front of every user who never asked for it, which is the `t_fmt`
+failure below observed in the wild. And the split between the two knob shapes
+has a **cause**, not a style: precision is either a property of the format
+string (Qt, Ant Design, WinForms) or a selector orthogonal to spelling
+(Vaadin/HTML `step`, MUI `views`, Taiga `mode`), and **every toolkit that fuses
+precision into `step` is one where the app cannot write a format at all** —
+Vaadin's Java API has `setLocale()` and `setStep()` and no format setter
+(**surveyed**), HTML has no `format` attribute. Every toolkit exposing a format
+string leaves `step` alone; zero exceptions either way. So the fusion is not a
+school anyone joined; it falls out of *not having* a format writer — which is
+exactly why Tuile adopts it cleanly, by removing the writer so the precondition
+is *made true* rather than importing a workaround into an API that contradicts
+it.
+
+**The costs, named so this is chosen and not inherited.** (1) **Seconds precision
+with a minute stride is unsayable** — a field holding `13:45:30` whose Up key
+walks to `13:46:30`; asking for the third segment hands you a one-second stride.
+Narrow, Vaadin lives without it, and additive to fix (a `precision:` whose nil
+means derived-from-step). (2) **No per-field spelling override**, so the twin is
+asymmetric: `DateField#formats=` is a writer. Defensible on the merits — a date
+has a genuine *per-field* axis (one form mixing `dd.mm.` and ISO for a technical
+value), a time has none; 12- versus 24-hour is a session convention, which is
+what `Locale` is for. (3) **Deliberate lossy leniency** (`["%H:%M", "%H:%M:%S"]`
+as an app's own list) is gone; it was a sanctioned edge, never a need. Two
+things are Tuile's and not Vaadin's: the **default is 60, not 3600** — Vaadin's
+hour is a dropdown-density number that leaks into the arrow keys, so Up from
+`13:45` lands on `14:45`, and there is no overlay at all (the dropdown decision
+below) — and there is **no divisor rule** (Vaadin requires a step to divide an hour or day); Tuile adds and
+wraps, and a constraint that exists for a picker's row grid is the picker's to
+add.
+
+**Decision — the two derived lists are asymmetric, by the ruling above.** At
+`step < 60`, `formats` is the *full-precision forms, then the stripped forms*, so
+typing `13:45` parses through the lenient secondary and canonicalizes to
+`13:45:00` — the lossless direction, free. At `step >= 60` it is the stripped
+forms *only*: admitting `%H:%M:%S` there is the lossy direction, so `13:45:30`
+stays bad input. One rule, read from the primary. (The first draft's table
+showed only what each mode *writes*, which is how it hid that the seconds mode
+would have demanded `:00` from the user — the reverse of the annoyance the
+default exists to avoid.)
+
+**Decision — the seconds strip is the field's, not the locale's.** glibc's
+`t_fmt` is a *clock display* format and carries seconds nearly everywhere, so
+honoring it puts `:00` in every form field in the world. The field therefore
+**keeps the locale's spelling and drops its precision** — separator, digit
+order and the 12/24-hour choice are conventions; the seconds are not. Qt arrives
+at the same place independently (`QDateTimeEdit` seeds itself with
+`loc.timeFormat(QLocale::ShortFormat)`, en_US `h:mm AP` where the long form is
+`h:mm:ss AP t`), and gets it *free* because CLDR ships short/medium/long time
+patterns as separate data; glibc ships one `t_fmt` with no short variant to ask
+for. So the strip is Tuile computing by hand the datum CLDR would have handed
+it. But it runs in **`TimeField`, not at the `Locale` boundary**, for two
+reasons — and the second stands on its own: the strip is *policy*, not
+normalization (`D_locale`'s boundary rule covers the `%T` → `%H:%M:%S` expansion
+and `first_weekday`'s renumbering, both representation changes; "default to
+minutes" is a form field's ruling, and `Locale` holds conventions, not UI
+defaults — its own stated gate); and it is **lossy** where those are not — a
+status-bar clock, a log timestamp, any consumer rendering a time *display*
+legitimately wants `t_fmt` with its seconds, and a boundary strip makes that
+unrecoverable, so they would hardcode a separator and take the same regression
+one layer down with no knob to fix it. So `Locale#time_formats` carries the
+locale's spelling at **full detected precision** (fi_FI
+`["%H.%M.%S", "%H:%M:%S"]`), `Locale::ISO` is `["%H:%M:%S"]` (ISO 8601 permits
+both; the member holds the fuller one and the field's default reduces it), the
+expansion table (`%T` → `%H:%M:%S`, `%R` → `%H:%M`, `%r` → `%I:%M:%S %p`) stays
+at the boundary, and the field strips. `t_fmt_ampm` is **not** read: en_GB's is
+`%l:%M:%S %P %Z`, a zone name and a blank-padded hour, two directives this
+field rejects. The strip rule — *drop `%S` and the literal run immediately
+preceding it*; a format with no `%S` passes through as already-minute; `step <
+60` over a locale with no seconds falls back to ISO `%H:%M:%S` rather than
+splicing a separator it would have to invent — is deliberately the smallest
+grammar surgery that works, and `Locale` places **no `%S` requirement** on an
+entry, since the fallback already covers the case a raise would cover.
+
+**Decision — stepping adds and wraps; `step=` at runtime is the locale-change
+path.** Up/Down add `step` seconds modulo 24 h (`23:59` + 1 → `00:00`; a clock
+has no day to carry into, so wrapping is arithmetic, not policy). An empty or
+unparseable field steps to **now**, truncated to the field's precision — the
+`Date.today` analogue, landing *on* now rather than now ± 1; that this clobbers a
+half-typed `13:4` is `D_date_field`'s ruling inherited knowingly (an arrow
+mid-typo is asking for help; a no-op is a dead key) and recorded here as a
+**shared** ruling — change it in both fields in one commit or the divergence
+reads as a bug. **Add, never snap:** `step = 900` from `13:07` goes to `13:22`,
+not the `13:15` grid line — snapping silently moves a value the user did not
+ask to change; Vaadin adds too ("accepts values that don't align with the
+specified step"), and HTML's snap is to a `min` base this field lacks. `step=`
+takes a positive `Integer` in `1...86400` and raises `ArgumentError` otherwise:
+no `nil` (nil-means-inherit is for locale-derived knobs; the default is set in
+`initialize`), no `Float`/`Rational` (a sub-second stride implies `%L`, rejected
+by name), nothing that wraps onto itself. And **`step=` with a value present is
+"re-derive, then run the locale-change path"**, not a second code path — the
+rule `on_locale_changed` already has, *re-canonicalize a buffer that still
+parses, leave one that does not*: widening `60 → 1` rewrites `13:45` to
+`13:45:00`; narrowing `1 → 60` leaves `13:45:30`, which becomes bad input
+(`value` reads `nil`, `on_value_change` fires, `bad_input?` says why). Nothing is
+silent on any channel, and the field never truncates a value it did not type —
+the *app* narrowed it and hears about it through the seam it already listens on.
+PageUp/PageDown step an hour whatever the stride — the dropdown decision below
+says why that is a key and not an overlay; `D_date_field` still defers the month.
+
+**Refined during implementation: a narrowing step *carries* a value the new
+primary can still write exactly.** `13:45:00` narrowed to minutes shows `13:45`
+rather than reddening, because dropping a *zero* second discards nothing — the
+no-truncation rule is about not losing what the user meant, and there is nothing
+there to lose. The test is the round-trip the validator already uses
+(`parse(value.strftime(new_primary), new_primary) == value`), so it needs no new
+concept; `13:45:30` fails it and is left as typed, exactly as ruled above. Only
+`step=` can do this, since it can read the outgoing value before switching;
+`on_locale_changed` fires *after* the conventions have changed and has no such
+handle, which is the same asymmetry `D_date_field` lives with. Without it, an
+app toggling precision for display reasons would redden a field whose value was
+never in doubt — an error state with nothing wrong, which is the failure mode
+this project treats as worse than a visible one.
+
+**Decision — the round-trip reference is `Time.utc(2000, 1, 1, 13, 45, 0)`, it
+validates on `Locale` only, and zone and sub-second directives are rejected by
+name.** Every property of the canary is load-bearing (all **verified**): *hour ≥
+13*, so a 12-hour directive with no `%p` fails — `%I:%M` writes `"01:45"` and
+reads back 1 o'clock, the exact analogue of `%y` not carrying a century, while
+`%I:%M %p`, `%I.%M %p` and `%I:%M%P` pass; *minute ≠ hour*, so an `%H`/`%M`
+swap is not masked; *second = 0*, so a minute-precision primary is legal, which
+the default is. What it deliberately does not catch is a **precision
+truncation** — `%H:%M` round-trips itself perfectly, and precision is `step`'s
+business. Pass: `%H:%M`, `%H:%M:%S`, `%T`, `%R`, `%r`, `%H.%M`, `%Hh%M`, `%H%M`,
+`%k:%M`, `%I:%M %p`. Rejected: `%I:%M`, `%I:%M:%S`, `%l:%M`, `%p`, `%H`, `%M:%S`,
+`%s`, any `%-H`. Two new by-name rejections, because both **round-trip cleanly
+and lose information anyway** (**verified**): **zone directives** `%z` `%Z` `%:z`
+`%::z` `%s` — `"%H:%M:%S%z"` writes `+0000` and reads it back, and
+`Date._strptime("13:45:00+0200", …)` hands back `zone: "+0200", offset: 7200`
+which this field would drop on the floor, so a user typing an offset would see it
+silently reinterpreted as a wall time; and **sub-second directives** `%L` `%N` —
+`sec_fraction: (1/2)` parsed and dropped. `%x` / `%X` / `%c` stay rejected as
+locale lookalikes. With no per-field writer the validator has exactly two call
+sites, both on `Locale`: the `time_formats:` assignment (an author to tell — it
+raises) and the `t_fmt` probe (nobody to tell — a failing format is dropped and
+the list falls back to ISO), the same asymmetry as `date_formats`. One known
+limitation written down rather than fixed: **Ruby's `%p` is fixed English**;
+under a 12-hour locale whose `am_pm` is not `AM;PM` the field writes English,
+because implementing `%p` from `Locale#am_pm` would mean owning a second
+formatting grammar, which `D_date_field`'s "strftime, not Java patterns" refuses.
+Whether strptime accepts `1:45pm` / `1:45PM` under `%I:%M %p` (the literal space
+and the case of `%p`) is **to verify before building**, and ruled either way: if
+strict, accept the cost rather than derive a spaceless secondary — that is
+grammar surgery on the locale's pattern, and the ISO `%H:%M` secondary means
+`13:45` always works.
+
+**Decision — `TimeFormats::HINTS` is its own table.** `%H`/`%I`/`%k`/`%l` →
+`hh`, `%M` → `mm`, `%S` → `ss`, `%p` → `AM`, `%P` → `am`, `%%` → `%`. Kept apart
+from `DateFormats::HINTS` because `%m` → `mm` (month) and `%M` → `mm` (minute) are
+both right in their own table, and a combined one is a question only a
+`DateTimeField` has to ask. `%p` is admissible where `%b` was not: `mmm` would be
+an invented token, while `AM` is literally what the field prints and a
+placeholder is a typing *sample* — so en_US's derived hint is `hh:mm AM` and
+fi_FI's `hh.mm`. `%k` and `%l` are in because both pass the round-trip and a
+directive that passes but has no hint makes the placeholder "not at all" for no
+reason.
+
+**Decision — no dropdown; PageUp/PageDown is the hour jump; segment stepping is
+phase 2.** Vaadin's `TimePicker` drops open a list of times spaced by `step`, and
+`ideas/new-components.md` carried that as this field's cheap phase 2. It is
+rejected, on `D_mouse`'s rule and two facts of its own. **A list of times computes
+nothing:** the calendar grid `DateField` will grow answers questions the user
+cannot (which weekday is the 17th, does this month have a 31st), while every row
+of a time list is derivable from its neighbour — it is a list of the thing the
+user was about to type, and typing `1345` beats scrolling to it. And **Vaadin's
+dropdown is an implementation inheritance, not a UX finding** —
+`vaadin-time-picker` wraps `vaadin-combo-box-light`, and it hides the list below
+a 15-minute step (**surveyed**, from recollection of `__generateDropdownList`;
+re-check before citing it further), so at this field's default stride a faithful
+port shows nothing. Building it would also re-import the coupling the default of
+60 was chosen to escape: a useful list needs an hour-ish `step`, which coarsens
+the arrows, and decoupling them is a second density knob beside the one knob this
+entry is built on. Last, there is no open gesture: the editor eats printables
+(Space is legal in `1:45 PM`), the arrows already mean step, and open-on-focus
+makes a Tab pass through a form flash overlays.
+
+What the keyboard actually lacked was the *hour jump* — 60 Ups from `13:45` to
+`14:45` — and that is a key, not an overlay: **PageUp/PageDown step an hour,
+whatever `step` is**, wrapping like the arrows and landing on now from an empty
+field like the arrows. The editor declines both, so the field claims them in its
+own `handle_key` (rung 3, one hop up the bubble) — no new `TextField` slot, and
+no printable, so a form's letter bindings keep working. The keyboard lineage of
+every toolkit built for hands-on-keys is **segmented stepping** — Qt's
+`QTimeEdit`, WinForms' `DateTimePicker`, HTML's `<input type=time>`, and the one
+TUI ancestor with a time widget, `dialog --timebox`: Up in the hour segment steps
+an hour, in the minute segment a minute, on `%p` toggles meridiem. That is the
+honest phase 2 — buildable, since the `Locale::Formats` lexer already yields a
+caret → directive map, and shared with `DateField` — deferred until PageUp/
+PageDown proves insufficient, because it changes what `step` means where the
+caret sits. **Re-grow rule for the dropdown:** only as a mouse affordance, only
+if a mouse-driven use actually appears, in `Select`'s shape with Vaadin's density
+gate (`SECONDS_PER_DAY / step <= 96`, so it exists only where the app has already
+coarsened `step` for its own reasons) — never with a density knob of its own.
+
+**Rejected alternatives.**
+
+- **A Vaadin-style dropdown of times by `step`** — computes nothing, empty at
+  the default stride by Vaadin's own gate, and re-couples list density to the
+  arrow stride; the decision above.
+
+- **`Tuile::LocalTime` as the value** (a `LocalTimeField`). It makes the wrong
+  state unrepresentable — a `NoMethodError` beats the year 2000 — and loses on
+  the UI-not-domain rule plus a cost the table understates: owning a value type
+  means owning `Comparable`, arithmetic, `to_s`, `inspect`, RBS and a spec file,
+  in a toolkit whose job is editing. It buys nothing for the composite either
+  (`DateTimeField` combining a `Date` with either representation is one line).
+  **Re-argue if** an app is observed passing a `TimeField#value` somewhere it
+  means an instant — that is the failure this trades away. As a later
+  *supplement* it stays open and cheap, because the naming rule lets the two
+  coexist with no mode flag: `TimeField#value` is a `Time`,
+  `LocalTimeField#value` a `Tuile::LocalTime`, and an app picks by its model's
+  type. It would be the third copy of this shell — `D_float_field`'s re-argue
+  point — and the honest answer will probably still be "duplicate". It must
+  **not** arrive as a `value_type:` knob on `TimeField`: that is the injected
+  converter `D_integer_field` refused, and it makes `value`'s class un-derivable
+  from the component's name.
+- **`Integer` seconds since midnight.** Indistinguishable from a duration, and
+  `IntegerField` by the naming rule.
+- **A per-field `formats=` writer beside `step`** — the two-knob shape this
+  entry held for one day, and MUI's shipped design (`views` plus `format`, with
+  `format` documented as *"Defaults to localized format based on the used
+  `views`"*, **surveyed**). It is the right shape **if** a writer has to exist,
+  and the interaction rule is settled should one return (**re-grow**):
+  `precision` becomes a stored selector (`:minutes` / `:seconds`, nil meaning
+  derived from `step`) and `formats=` the override; precision is a *property of*
+  `formats.first`, so there is one authority and which one depends on whether
+  the derivation ran — `formats` nil → `precision` selects the detected form,
+  `formats` set → `precision` reads back *derived* from `formats.first`;
+  disagreeing explicit values **raise at assignment**, either order, naming both
+  (letting `precision` win silently rewrites a pattern the author wrote, the
+  zone directives' class; letting `formats` win makes `precision` a silent
+  no-op; there is an author to tell — `D_locale`'s asymmetry, and `bg_color=`'s
+  eager `KeyError` is the shape); the check keys on `formats.first` alone, so a
+  lossy-leniency list stays legal beside `precision = :minutes`; and
+  `precision` is stored, never eagerly resolved into a list, or it snapshots the
+  session locale. Not v1 because v1 has no writer to reconcile against and
+  reaches MUI's outcome — the spelling survives the precision switch — with one
+  knob. Qt is the other reading of the same table and the one declined: a
+  format writer *and* a locale default, with the spelling gap that implies, and
+  no fix.
+- **A fused `step` *with* `formats=`** — importing Vaadin's workaround into an
+  API that has the thing it works around. Two writers for one fact; needed the
+  raise above to hold together.
+- **Stripping seconds at the `Locale` boundary** — lossy for every non-field
+  consumer; see the strip decision.
+- **Honoring `t_fmt`'s precision** — `:00` in every form field in the world;
+  WinForms and Ant Design are what that looks like shipped.
+- **Reading `t_fmt_ampm`** — carries `%Z` and `%l`, two rejected directives.
+- **Snapping a step to the grid** — silently moves the user's value.
+- **A `precision` reader** — squats a second name for one fact and invites the
+  writer question; the API is one sentence.
+- **Splicing a separator to add `%S` to a seconds-less locale format** — grammar
+  surgery the strip rule is kept deliberately minimal about; ISO is the fallback.
+
+**Consequences.**
+
+- **`Locale` grows `time_formats`**, its ninth member, passing its own gate
+  (how a value is rendered and parsed; no prose). `KEYWORDS` gains `t_fmt`;
+  `Locale.system`'s `LC_TIME` gate already covers it. Detected list is
+  `[t_fmt expanded, "%H:%M:%S"].uniq` — the `[widened, raw, ISO]` shape of
+  `date_formats_from` with no widening step. Specs drive it through
+  `Locale.from_keywords`; `FakeScreen` keeps pinning `Locale::ISO`.
+- **The strftime lexer is hoisted** out of `Locale::DateFormats` into a
+  `Locale::Formats` module — `DIRECTIVE`, `each_directive`, `LOCALE_LOOKALIKES` —
+  with `DateFormats` and `TimeFormats` as two validators over it. Two copies of
+  `DIRECTIVE` drifting apart is a silent bug in both, and "duplicate rather than
+  DRY a shallow shell" (`D_float_field`) is about component shells, not a lexer.
+  Moving three constants is one **Breaking** CHANGELOG line in a pre-1.0 gem;
+  taking it now is cheaper than a third format kind later, and it is its own
+  commit — a refactor bundled into the feature is the one split the git rules
+  ask for.
+- **The field is the second copy of the date-field shell** exactly as
+  `FloatField` is the second of the numeric one; duplicate, re-argue at the
+  fourth.
+- **The picker phase 2 is segment-aware Up/Down, not a dropdown** (decision
+  above); it is `DateField`'s phase 2 as well, and the calendar grid stays that
+  field's own, because a calendar carries information a list of times does not.
+- **`DateTimeField` over a `DateField` plus a `TimeField`** is what
+  `ideas/composite-field.md` was filed for, still blocked on which component
+  wears a *combination* error.
+- **The sampler pane supplies its own locale** — a canned fi_FI-shaped `Locale`
+  via `Locale.from_keywords`, `step: 60` and `step: 1` side by side — because the
+  point is that a non-colon spelling survives the switch, and on an en_US box
+  the host locale demonstrates nothing.
+- `D_date_field` owes a pointer here; `D_locale`'s "the time formats stay out"
+  sentence resolves to this entry.
+
+## D_mouse — Keyboard first: the mouse is additive, ranked by activity (2026-09-05)
+
+**Status:** Accepted 2026-09-05. Decided while ruling out the `TimeField`
+dropdown (`D_time_field`), which is its worked rejection; nothing implemented,
+because the entry mostly names what already holds. `virtui` — visualization-heavy,
+the one downstream app — is what keeps the mouse in scope at all.
+
+**Context.** Tuile parses the mouse (`MouseEvent`: buttons and the wheel), routes
+a click down the tree (`Component#handle_mouse`), hit-tests it (`extent_rect`),
+focuses on click and dismisses overlays on an outside click. Every one of those
+arrived because a keyboard-motivated component needed it, and none was argued for
+on its own. The question kept coming back per feature — should a `TimeField` have
+a dropdown so a mouse user can pick? should hover paint an accent? — with no
+ruling to point at, so each was re-argued from scratch. This entry is the ruling.
+
+**Decision — the ranking, by activity.** Mouse is **better** than keyboard for
+window-moving and dragging; **at least equal** for scrolling; **equal** for focus;
+a **distant second** for value entry. Rungs, not a blanket: "the mouse is a
+distant second" is true of *value entry* and false of the wheel, and a rule
+stated per activity is what stops either reading from being generalized. Focus is
+"equal" as complementary rather than interchangeable — Tab is sequential (next
+stop, hands stay put), a click is random access (any widget, one gesture, cost
+growing with distance rather than stop count); neither dominates, so neither
+drives design.
+
+**Decision — the operative rule: every capability is reachable from the keyboard;
+the mouse is additive.** No capability exists *only* through the mouse, and no
+component, overlay or knob is built on a mouse argument alone. Applied per rung:
+
+- **Where the mouse is better or at least equal (dragging, scrolling)** it may get
+  features of its own — the wheel on the scrollers, someday window-moving —
+  provided the keyboard already does the job (PageDown; a move-window key). The
+  mouse gets to be *nicer*, never *necessary*.
+- **Where it is equal (focus)** both exist and neither shapes design;
+  click-to-focus ungated by geometry is already that.
+- **Where it is a distant second (value entry)** it gets exactly what
+  `Component#handle_mouse`'s routing hands over for free: a `super`-then-act
+  hit-test on a widget that exists for keyboard reasons. A `Checkbox` toggles on
+  click, a `List` row selects, a `Select` row chooses, a `Button` fires — all
+  shipped, all one line, all staying. What is refused is a feature whose only
+  argument is "so a mouse user can…": the `TimeField` dropdown is the worked case.
+
+**Rejected alternatives.**
+
+- **The mouse as an equal peer** — every field gets a picker, every enumeration a
+  clickable face. That is a GUI toolkit's rule, and it produces Vaadin's
+  `TimePicker`: a dropdown that exists because the widget is a `ComboBox` skin,
+  hidden below a 15-minute step because it stops being useful. A TUI user's hands
+  are on the keys; typing `1345` beats scrolling to it.
+- **A blanket "no mouse value entry"** — the first phrasing, and literally false
+  of shipped code (the four click handlers above). Deleting them would be
+  gratuitous; the rule is about what *motivates* a feature, not what the mouse may
+  touch.
+- **A `mouse:` knob per component, or a `Screen#mouse = false`** — a setting for
+  something nobody has asked to turn off; the ranking is a design priority, not a
+  runtime mode.
+- **Mouse-only features "for virtui"** — the app is the reason the mouse is in
+  scope, not a licence to build widgets for it. The framework owes virtui the
+  plumbing (events, routing, extents, the wheel); a mouse-heavy visualization is
+  the app's own component, built on that plumbing.
+
+**Consequences.**
+
+- **`D_select` is untouched, and says so where the question will be asked.**
+  Select's dropdown is *enumeration* — options the user cannot type without
+  seeing, the same information test the calendar grid passes and a list of times
+  fails — and its no-printable claim is a keyboard argument. Nothing here demotes
+  Select relative to `ComboBox`; the enum-vs-data criterion stands.
+- **`ideas/hover.md` is compatible by construction**, not by exemption: its own
+  framing is "opt-in and never load-bearing" — hover adds ink, not a capability,
+  so a keyboard user loses nothing. It stays paused on its own merits.
+- **The wheel on the scrollers is sanctioned and unscheduled.** `MouseEvent`
+  already parses `:scroll_up` / `:scroll_down`; no `List`, `TextView`, `TextArea`
+  or `ListDropdown` consumes them. It is the one gap the ranking exposes, and it
+  arrives as a small feature whenever someone wants it — PageUp/PageDown already
+  do the job.
+- **Window-moving needs its own `D_` when it comes:** motion and release events
+  (modes 1002/1006 — Tuile runs X10 mode 1000, press only; the Split Layout
+  blocker in `ideas/new-components.md`, and what `ideas/hover.md` step 1
+  designs), plus the keyboard equivalent the rule above requires *first*.
+- **Segment-aware Up/Down** (`D_time_field`'s phase 2) is the keyboard's picker,
+  and the shape any future "picker" for a typed field takes before an overlay is
+  considered.
+- AGENTS.md carries the one-line invariant — no capability reachable only
+  through the mouse — beside the `handle_mouse` routing rule, since a new
+  component can break it from its own file.