tuile 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18944d23fd95ada3802f613eb6ff6847e845a082e1b155f2ed9d72e324181179
-  data.tar.gz: 33c476d0d194ae365a95e0ec65f9652fb8da44ba566e34e4a0c99a043747080a
+  metadata.gz: 442d863affeb579ca0fdc7d99531c0d255a9c6129c82c09e0a91ebbb1404e651
+  data.tar.gz: a502cb86f7c2c9fc0c871699838c223b6076ec98e9099ef1771f8e0f3ef973f1
 SHA512:
-  metadata.gz: 5e7a9b67f3530b86123933ccfaab6116b0aa0c4031f03e81c6b60094f6196aaa8f8adbc86634f4cc052048a1b15078ed5230983a3fff0ba7186d7d8b3d1e2d71
-  data.tar.gz: ae43fd49b5217606f88d3b7d631c89c8f3c86b82882c0850b6c6980ce100cdbaefd9237da9ea148680775d1c3a980b708934fad0ab71616de3560ea35804602f
+  metadata.gz: cc042252f3248883da046ad9328417fe7bc609314b1633a56751bbf62608c0c5e1142dd943bd33027b2d1da0661dadea4306442db8d8ea800bd96a5e882765f5
+  data.tar.gz: '09e3aecaedcf12cfdb0da848fc92baec87c393c990a927f58f7c2796c19734032fc7fe8ab2f3678b9433c98579dbc6c1953e08040b7316c75c353e49a9434f15'

data/CHANGELOG.md

@@ -1,5 +1,115 @@
 ## [Unreleased]
 
+## [0.16.0] - 2026-09-18
+
+0.16.0 settles two vocabularies. Every override point is now `handle_foo` and
+every listener slot `on_foo=`, with a trailing `?` marking exactly the handlers a
+dispatcher routes, so a name says what it is and what it owes. The mouse is
+rebuilt on that footing: `Tuile::Mouse` gives each wire event its own class, and
+`Mouse::Router` owns every walk — resolving the path under the pointer, focusing,
+bubbling a press to one claimant and holding the grab until the release — so no
+widget hit-tests or `super`s a walk of its own again.
+
+- Add `Tuile::Mouse` — one class per mouse event, `DownEvent` / `UpEvent` / `ScrollEvent` / `MoveEvent` off the wire plus the router-made `DragEvent` (which `Screen#handle_mouse` refuses, naming the `MoveEvent` to post instead), each including the `Mouse::Event` marker and its `point`; `Mouse.parse` replaces `MouseEvent.parse`. See `design/decisions.md` `D_mouse_dispatch`.
+- Add `Tuile::Mouse::Router` — the dispatcher that owns every mouse walk: it resolves the path under the pointer, focuses, bubbles a press to one claimant, holds the grab and diffs the hovered chain. `Screen#handle_mouse` is its public door. See `design/decisions.md` `D_mouse_dispatch`.
+- Add `Screen#grabbed` and `Screen#hovered` — the component holding the mouse grab, and the innermost one under the pointer.
+- Add `capture_mouse: :drag` / `:hover` to `Screen#run_event_loop` — the rungs unlocking `handle_mouse_drag` (mode 1002) and `handle_mouse_move?` with the enter/exit hooks (1003). `true` still means `:clicks`, and an unknown level now raises. See `design/research.md` `R_mouse_reporting`.
+- Add `FakeScreen#click` / `#press` / `#release` / `#scroll` / `#move` / `#drag` — a spec posts the gesture the terminal would, at screen coordinates, instead of calling a handler; `#drag` plays press-moves-release over the points handed it and interpolates none.
+- Add a *Mouse* pane to `examples/sampler.rb` — a canvas that strokes `X` on a drag, trails on a hover and lifts on a right-drag, beside a log of the discrete events and a live pointer row; it takes the sampler to `capture_mouse: :hover`.
+- Add `Component::DateTimeField` — a `DateField` and a `TimeField` side by side on one row behind a single `DateTime` value, with the two halves exposed read-only as `date_field` / `time_field` for tuning. See `design/decisions.md` `D_date_time_field`.
+- Add `Component#clear_inside_extent` — the protected hook a container overrides to decline the default's blank of its extent, so ink it paints into a face cell no child covers stays off the wire. See `design/decisions.md` `D_extent`.
+- Add `Component::AbstractWrappingField#notify_on_edit?` — the protected hook a field whose grammar is not prefix-closed answers `false`, settling `on_value_change` onto the commit gestures instead of firing it per edit. See `design/decisions.md` `D_date_field`.
+- Add `Component#on_theme_changed` and `#on_locale_changed` readers — every listener slot is now a full `attr_accessor`, the two dual names that forced `attr_writer` having been renamed away. See `design/decisions.md` `D_handler_naming`.
+- Add `Component::Notification::View` — the toast's own `TextView`, which refuses the wheel so queued messages wait for the ticker rather than becoming mouse-only scrollable text. See `design/decisions.md` `D_notification`.
+- Fix `Component#repaint` leaving the cells of a declared `extent` that no child covers — a `Layout::Box`'s `spacing` column, its trailing slack, a hidden child's abandoned span — unblanked, so they kept stale glyphs across a resize. See `design/decisions.md` `D_extent`.
+- **Breaking:** `Component#handle_mouse` is gone, and with it the walk every override had to `super` into: a component overrides one handler per event, three routed (`handle_mouse_down?`, `handle_mouse_scroll?`, `handle_mouse_move?`) and four not (`handle_mouse_up`, `handle_mouse_drag`, `handle_mouse_enter`, `handle_mouse_exit`). Move an old body into `handle_mouse_down?`, drop the `super` and the hit test the router now does, and return `true` when you acted. See `design/decisions.md` `D_mouse_dispatch`.
+- **Breaking:** `Tuile::MouseEvent` is gone, replaced by one class per wire event under `Tuile::Mouse`. Build a press as `Mouse::DownEvent.new(:left, x, y)`, a release as `Mouse::UpEvent.new(x, y)` — it carries no button — and read `direction` on a `Mouse::ScrollEvent` where you read `button: :scroll_up`.
+- **Breaking:** Click-to-focus moved into `Mouse::Router`, which focuses the innermost `focusable?` under the pointer before any handler runs. Delete a widget's own `extent_rect` hit test: a press only reaches it where the extent contains the point.
+- **Breaking:** A press is claimed by exactly one component and stops there, where it used to reach every level containing the point, and the claimant holds the mouse grab until the release, any key or the next press. A container acting on presses aimed at its children must claim them itself.
+- **Breaking:** `ScreenPane#handle_mouse` is gone; the pane answers the router's two tree questions instead, `#mouse_root_at` and `#dismissing_popups_outside`. Outside-click dismissal is unchanged.
+- **Breaking:** `List::Cursor#handle_mouse` is now `#handle_mouse_down?`, so a custom cursor strategy renames its override. `List` and `TextView` now decline a wheel notch they cannot act on, which bubbles it to an ancestor scroller instead of swallowing it.
+- **Breaking:** Every override hook is now `handle_*`, so `on_` names a listener slot and nothing else: `on_attached`, `on_detached`, `on_focus`, `on_blur`, `on_child_removed`, `on_child_visibility_changed`, `on_width_changed`, `on_text_mutated`, `on_caret_mutated`, `on_editor_change`, `on_half_change`, `on_theme_changed`, `on_locale_changed`, and `Screen`'s `on_color_scheme` / `on_background_color`. Rename each override and call `super` from it; every `on_foo=` slot keeps its name, so `label.on_theme_changed = …` is untouched. See `design/decisions.md` `D_handler_naming`.
+- **Breaking:** The routed handlers that return a verdict now say so with a `?` — `Component#handle_key?`, `Screen#handle_key?`, `ScreenPane#handle_key?`, `AbstractStringField#handle_text_input_key?` and `MenuBar#handle_mnemonic?`. Rename each override and each direct call, `Testing.get(…).handle_key?(Keys::ENTER)` included; the return values are unchanged. See `design/decisions.md` `D_handler_naming`.
+- **Breaking:** `Component#handle_paste` returns `void` rather than a Boolean. Drop the trailing `true` from an override; nothing read the answer. See `design/decisions.md` `D_bracketed_paste`.
+- **Breaking:** `Component#on_tree` and `#on_shown_tree` are now `#walk_tree` and `#walk_shown_tree` — the `on_` prefix is reserved for listener slots, and these are traversals, not events. Rename the call; nothing else about either walk changed.
+- **Breaking:** `EventQueue#on_loop_thread?` is now `#in_loop_thread?`, for the same reserved prefix. Same answer, same semantics — only the spelling moved.
+- **Breaking:** `Component::DateField` and `Component::TimeField` fire `on_value_change` at the commit gestures — leaving the field, or ENTER — rather than per keystroke. A listener wanting the live reading polls `value`; a `value=`, an arrow-key step and a `clear` still announce themselves as they happen. See `design/decisions.md` `D_date_field`.
+- **Breaking:** The contributor docs moved under `design/` and no longer ship in the packaged gem — `DECISIONS.md`, `TERMINOLOGY.md`, `RELEASING.md` and `ideas/` are now `design/decisions.md`, `terminology.md`, `releasing.md` and `design/ideas/`. Update any link you kept and read them on GitHub; nothing under `lib/`, `book/`, `examples/` or `sig/` changed.
+- **Breaking:** `COMPARISON.md` and `design/requirements.md` are retired — the toolkit survey is now `design/research.md`'s `R_ruby_tui_toolkits` / `R_ratatui` / `R_charm_ruby` / `R_curses_bindings` entries, and the one requirement is the **Promises** section of `AGENTS.md`.
+- **Breaking:** Remove `Theme#hint_color` and `Theme#hint` — a "de-emphasized text" shade is the global fg token Tuile declines to carry. Carry it as a `custom` token instead and render it with `Theme#fg(:hint, text)`, pairing it in a `ThemeDef` so it survives an appearance flip. See `design/decisions.md` `D_no_hint_color`.
+- **Breaking:** `lib/tuile/AGENTS.md` and `lib/tuile/component/layout/AGENTS.md` are retired, and the two that remain trade their per-file lists for a sub-directory map. Their rules already lived in each symbol's rdoc and `design/decisions.md` `D_box_layouts`; `ls` is the file index.
+- **Breaking:** `Component::ComboBox` no longer includes `Component::HasContent` — its inner `TextField` holds a transient query it owns, not content you populate — so `combo.content` and `combo.content=` are gone. A spec reaches the field with `Testing.get(Component::TextField, in: combo)`. See `design/decisions.md` `D_has_content`.
+- **Breaking:** `Component::PickerWindow` no longer colors option captions; they paint in the terminal's own foreground. `Option#caption` is now a `StyledString`, coerced through `StyledString.parse`, so hand in a `StyledString` (or the ANSI String `Theme#fg` returns) to color one — per option.
+
+## [0.15.0] - 2026-09-05
+
+0.15.0 is about the form. A field can now report input its type cannot
+represent (`HasBadInput`), hold an outside validator's verdict
+(`HasValidation`), paint either as a red well, hint at what it wants
+(`HasPlaceholder`), and spell dates and times the way the session's new
+`Tuile::Locale` says — `DateField` and `TimeField` are the two new ones, over a
+shared `AbstractWrappingField`. Under them, two seams the widgets had been
+improvising become framework: a background that resolves down the tree through
+`default_bg_color` and `BG_INHERIT`, and `Component#visible=`, which hides a
+component as if it were detached while it stays in the tree. And `Tuile::Testing`
+lets a spec drive that UI by looking components up instead of reading the
+painted buffer.
+
+- Add `Component#visible=` / `#visible?` — hides a component as if it were detached while it stays in the tree: it paints nothing, takes no space in a `Layout::Box`, and is unreachable by focus, Tab, keys, the mouse and `Testing.find`, while keeping its parent, rect, state and any running resource. See `design/decisions.md` `D_visibility` and book ch7.
+- Add `Component#on_shown_tree` — `on_tree` with hidden subtrees pruned; the walk every "can the user reach it" question takes, and the one a new focus traversal must use.
+- Add `Component#on_child_visibility_changed` — the protected notice a container with layout arithmetic overrides to re-divide space when a direct child is hidden or shown; `Layout::Box` relayouts from it.
+- Add a visibility rule to `Testing.find` / `.get`: they simulate a user, so a hidden component is never returned, and a failed lookup counts the hidden matches it excluded. `Screen#focused=` likewise raises on a hidden target, as it already did on a detached one.
+- Add `Tuile::Testing` — `Testing.get` / `.find`, which locate a component in the tree by class, mixin, `id`, caption or a block, so a spec can drive the UI instead of only reading the painted buffer. A failed lookup dumps the tree it searched. See `design/decisions.md` `D_component_lookup`.
+- Add `Component#id` — a `Symbol` tag for finding a component again; nothing paints it and nothing enforces uniqueness, since `Testing.get` raising on two matches is the enforcement.
+- Add `Component#inspect` — one line naming the class, `id`, rect and each mixin's contribution via the protected `inspect_details` hook, replacing an `Object#inspect` that walked `parent`, `children` and the `Screen`.
+- Add `Tuile::Final` — the `final` keyword Ruby lacks: a class `extend`s it, marks the methods a subclass may not redefine, and calls `verify_final!` from its own `initialize`. See `design/decisions.md` `D_final_tree`.
+- Add `Component#default_bg_color` — a protected hook where a widget declares the background it paints itself; the level the resolution chain was missing, sitting under `bg_color` and over the parent's. See `design/decisions.md` `D_bg_surface`.
+- Add `Component::BG_INHERIT` — assign it to `bg_color` to contribute no background of your own and take what surrounds you, skipping this component's `default_bg_color`; it is how a widget owned by a bigger one drops its well. See `design/decisions.md` `D_bg_surface`.
+- Add a state-keyed form of `Component#bg_color`: `{ normal: …, active: … }` over `Component::BG_STATES`, so an app can keep a focus shade of its own rather than flattening one. An absent key falls through to the next level of the chain.
+- Add `Component::HasBadInput` — `bad_input?` / `bad_input_message`, the report a field owes when its input is something its value cannot represent (a lone `-` in an `IntegerField` reads `nil`, exactly like an empty one). Included by the three numeric fields; ask it before `empty?`. See `design/decisions.md` `D_bad_input` and book ch7.
+- Add `Component::HasValidation` — `error_message` plus `on_error_message_change`, the verdict slot a validator writes and the field shows as a red well; included by `HasValue`, so every field has it, and `bad_input?` reddens the well too. See `design/decisions.md` `D_has_validation` and book ch7.
+- Add `Component#error_bg_color` — a protected hook for the background a component paints while signalling an error, resolving *above* `bg_color` so tinting a panel cannot switch the signal off on the fields inside it.
+- Add `VerticalScrollBar.handle_char=` / `.track_char=` — the two bar glyphs as an app-global look-and-feel knob (`▐` over `│` for a lazygit-style bar); a glyph that is not exactly one cluster one column wide is rejected at assignment.
+- Add `Component::HasPlaceholder` — `placeholder=` paints a hint into a field's empty well (`dd.mm.yyyy`) in the new barely-visible `Theme#placeholder_color`, never touching the value; carried by `TextField`, forwarded by the four composed fields. See `design/decisions.md` `D_placeholder` and book ch7.
+- Add `Component::AbstractWrappingField` — the base for a field that carries a typed value but paints nothing itself, owning and hiding one inner editor, committing on both commit gestures and offering subclasses an `on_editor_change` hook; `IntegerField`, `FloatField` and `BigDecimalField` are built on it. See `design/decisions.md` `D_wrapping_field`.
+- Add `Component::DateField` — a typed `Date`/`nil` field over a list of strftime `formats` taken from `Screen#locale`: parsing tries them in order, leaving the field rewrites the buffer in the first, Up/Down step a day, and unparseable input is reported through `bad_input?` rather than filtered. See `design/decisions.md` `D_date_field` and book ch7.
+- Add `Component::TimeField` — a typed `Time`/`nil` time of day on a fixed epoch date, spelled the way `Screen#locale` says: `step` is both the Up/Down stride and the precision, PageUp/PageDown step an hour, and unparseable input is reported through `bad_input?`. See `design/decisions.md` `D_time_field` and book ch7.
+- Add `Locale#time_formats` — the strftime patterns a time field accepts, detected from glibc's `t_fmt` and carrying its full precision, since dropping the seconds is a form field's policy and a clock display wants them. See `design/decisions.md` `D_time_field` and book ch10.
+- Add `Component::HasBadInput#bad_input_settled?` — the protected gate deciding whether bad input may paint the invalid well *yet*; `true` by default (the numeric fields redden as you type), latched to the commit gestures by `DateField`, whose every prefix is bad input. The `bad_input?` pull is unaffected. See `design/decisions.md` `D_has_validation`.
+- Add `Tuile::Locale` — a frozen value type of formatting conventions (date formats, calendar, month/weekday names, decimal separator), detected from `locale -k` by `Locale.system` and never holding prose. `Locale::ISO` is the only preset and the fallback. See `design/decisions.md` `D_locale` and book ch10.
+- Add `Screen#locale` / `#locale=` — the session's conventions, seeded at construction; assigning fires `Component#on_locale_changed` across the tree and repaints it, so a `DateField` respells the dates it holds. See `design/decisions.md` `D_locale`.
+- Add `Component#on_locale_changed` — the protected hook (plus an assignable listener) for state derived from the old conventions and *pushed* somewhere; anything read at paint or parse time needs nothing, since the locale change repaints everything.
+- Add `Screen.instance?` — whether `Screen.instance` would answer rather than raise, for code that must work with no screen in the process, as a detached component tree legitimately is.
+- Add `Component::DateField#calendar_start` / `#calendar_start=` — the calendar the field parses and formats against, inheriting `Screen#locale` until you set one and again when set back to `nil`; proleptic Gregorian by default, not Ruby's `Date::ITALY`. See `design/decisions.md` `D_date_field`.
+- Add a `DateField` pane to `examples/sampler.rb` under Input → Typed, where typing `4.9.2026` and Tabbing away shows the buffer rewrite.
+- Add readline's kill keys to both text inputs (`AbstractStringField`): `Ctrl+W` deletes the word behind the caret, `Ctrl+U` everything before it — back to index 0 in a `TextField`, to the caret's row start in a `TextArea`. See `design/decisions.md` `D_kill_keys` and book ch7.
+- Add `Component#invalidate_children` — the protected repaint cascade as a named call, so a container that paints its own rect can skip the default's blanket clear without silently dropping the one line it may not.
+- Add an `at:` keyword to `Component::Layout::Box#add`, placing the child at an index instead of appending, so a pane hidden with `#remove` goes back where it was. See `design/decisions.md` `D_empty_ancestor`.
+- Add `Component::Layout::Box#constrain` — re-constrains a child already added, a `nil` axis keeping whatever it had, so a pane can be collapsed with `Fixed[0]` without removing and re-adding it.
+- Add `Component#on_blur` — the protected mirror of `on_focus`, fired on the component that just lost focus, so a field can commit or canonicalize what the user typed even when they Tab away. See `design/decisions.md` `D_on_blur` and book ch5.
+- Fix `Component::Window` and its subclasses re-emitting their whole border on every unchanged repaint — 925 bytes for an 80x25 window, paid on each focus change — by no longer blanking the rect it is about to repaint. See `design/decisions.md` `D_component_contract`.
+- Fix a `Component::Window` with `scrollbar = true` painting its right border under the content's scrollbar, dirtying that column into every frame; the border now leaves the column it gave away alone.
+- Fix `Component::Layout::Box` stranding its children at their old rects when its own rect went empty, so the next full repaint — which any popup close runs — painted the hidden subtree back at stale coordinates. See `design/decisions.md` `D_empty_ancestor`.
+- Fix `Screen#repaint` painting a component that sits under an empty-rect ancestor: the drain filter now drops it, as it already drops a detached one, so a container that forgets to zero its children is inert rather than wrong.
+- Fix `Screen`'s pane carrying no rect until the first `#layout`, which runs from the event loop; it is sized at construction from `#size`, so the tree is not filtered out of the repaint as sitting under an empty ancestor.
+- Fix `Component::IntegerField`, `FloatField` and `BigDecimalField` accepting *pasted* text their own filter forbids — `"abc"` pasted into an integer field left it showing `abc42` while `value` silently read `nil`. Each now filters in its inner field's `insert_text`, which typing and pasting both pass through. See `design/decisions.md` `D_input_filters`.
+- Fix the numeric fields occupying their inner field's `on_key` slot for Up/Down stepping, so an app that set `field.content.on_key` silently killed the spinner. They use `on_key_up` / `on_key_down` now, and `on_key` is free.
+- Fix `Component#bg_color` being inert on `Component::TextField`, `TextArea`, `Select` and `ComboBox`, which reached past it to the theme — contradicting what `bg_color=` and `effective_bg_color` documented. Setting one on a field now wins over its well.
+- Fix `Component::TextView` wrapping text right up against a visible scrollbar (`…to show the█`): the bar now reserves a blank column beside it, as `List` rows always have. See `design/decisions.md` `D_scrollbar_reserve`.
+- Fix the scrollbar painting a solid full-height `█` when the content fits: with nothing to scroll the bar now shows only its track, keeping its column and its content width. See `design/decisions.md` `D_scrollbar_ink`.
+- **Breaking:** `Locale::DateFormats::DIRECTIVE`, `::LOCALE_LOOKALIKES` and `.each_directive` moved to the new `Locale::Formats`, the strftime lexer `DateFormats` and `TimeFormats` now share. Reference them under `Locale::Formats`; `REF`, `HINTS`, `.validate`, `.humanize` and `.widen` are unmoved.
+- **Breaking:** `Component::AbstractStringField#on_key` is gone — the pre-dispatch interceptor that could claim any key. Subclass and override `handle_text_input_key` instead, calling `super` for keys you don't claim; a key you decline still bubbles to an ancestor. See `design/decisions.md` `D_no_key_interceptor` and book ch7.
+- **Breaking:** A paste is delivered to `Screen#focused` alone and no longer bubbles up the focus chain; `ScreenPane#handle_paste` returns false when the focused component declines. A container that relied on catching a paste its child refused must move that `handle_paste` onto the focusable component. See `design/decisions.md` `D_bracketed_paste`.
+- **Breaking:** `Component::TextField#preprocess_paste` keeps the paste's first line instead of flattening every newline to a space, so a copied whole line no longer arrives with an invisible trailing space. Override it to restore the old behavior. See `design/decisions.md` `D_paste_newlines`.
+- **Breaking:** `Theme` carries a further token, `placeholder_color`, the ink `Component::HasPlaceholder` paints an empty field's hint in. A hand-rolled `Theme.new(...)` must now pass it; `Theme::DARK.with(...)` is unaffected. See `design/decisions.md` `D_placeholder`.
+- **Breaking:** `Theme` carries four further tokens — `scrollbar_color`, plus `error_color` / `error_bg_color` / `error_active_bg_color` — so a scrollbar is themed rather than painted in the terminal's default foreground, and an invalid field shows a well that still reads as focused. A hand-rolled `Theme.new(...)` must now pass all four; `Theme::DARK.with(...)` is unaffected. See `design/decisions.md` `D_scrollbar_ink` and `D_has_validation`.
+- **Breaking:** `Component::Label#bg` / `#bg=` are gone. Use `bg_color`, which now covers the text, the trailing padding and the blank rows alike; to override a span's own background as `#bg` did, restyle the text with `label.text = text.with_bg(c)`.
+- **Breaking:** `Component#effective_bg_color` is protected and final. A widget declares its own background by overriding `default_bg_color`; nothing else needs to read the resolved value, since `draw_text` / `draw_char` / `clear_background` apply it.
+- **Breaking:** `Component::AbstractStringField#background` is gone. A subclass painting its own row calls `draw_text`, which applies the well; to change the well, override `default_bg_color`.
+- **Breaking:** `Component::FINAL_METHODS` is gone, replaced by the `Tuile::Final` declaration it became. Read `Component.final_methods` instead; `Component.verify_final!` is unchanged.
+- **Breaking:** `content` / `content=` are gone from `Component::IntegerField`, `FloatField` and `BigDecimalField`, whose inner editor is private machinery. Use the field's own `placeholder` / `on_enter` / `cursor_position` / `clear`, write a forwarder for anything else, and reach the editor from a *spec* with `Testing.get(Component::TextField, in: field)`. See `design/decisions.md` `D_wrapping_field`.
+- **Breaking:** `content` is now `list` on `Component::CheckboxGroup` and `RadioGroup`, and read-only — an app tunes the composed `List` but must not swap it, since the group's renderer and selection are wired into that one. Rename `group.content` to `group.list`; there is no `content=` replacement. See `design/decisions.md` `D_has_content`.
+
 ## [0.14.0] - 2026-08-31
 
 Tuile names the foundations it had been improvising: the floating layer becomes
@@ -12,22 +122,22 @@ terminal untouched by the app — and the terminal's own background becomes
 readable as a `Color`. On top of that sit the dialogs: `ConfirmWindow`, an
 `InfoWindow` prose body, and `LogTextView` for a frameless log.
 
-- Add `Component::Overlay` — the bare floating layer every overlay is built on: a mount/dismiss lifecycle, `owner`, `on_close` and outside-click dismissal, at a rect the caller assigns. See `DECISIONS.md` `D_overlay` and book ch7.
-- Add `Component::Slot` — a one-child region for content that may be absent, arrive late, or be swapped; a container gives each of its regions one, wired at construction, so a swap never has to compute an insert index. See `DECISIONS.md` `D_slots`.
-- Add `Component#extent`, `#extent_rect` and `#clear_outside_extent` — the size a widget actually paints inside the rect it was assigned (`nil` by default, meaning undeclared), and what it hit-tests, anchors and blanks against. See `DECISIONS.md` `D_extent`.
+- Add `Component::Overlay` — the bare floating layer every overlay is built on: a mount/dismiss lifecycle, `owner`, `on_close` and outside-click dismissal, at a rect the caller assigns. See `design/decisions.md` `D_overlay` and book ch7.
+- Add `Component::Slot` — a one-child region for content that may be absent, arrive late, or be swapped; a container gives each of its regions one, wired at construction, so a swap never has to compute an insert index. See `design/decisions.md` `D_slots`.
+- Add `Component#extent`, `#extent_rect` and `#clear_outside_extent` — the size a widget actually paints inside the rect it was assigned (`nil` by default, meaning undeclared), and what it hit-tests, anchors and blanks against. See `design/decisions.md` `D_extent`.
 - Add `Component::Select#extent` and `Component::ComboBox#extent` — the one row the widget paints, which is what its dropdown anchors to; a single-slot container assigns these widgets far more height than they use.
-- Add `Component#size`, `#width` and `#height` — read-only shorthands for the matching `rect` field. Reports of the geometry a parent assigned, never requests: there is no writer and no container consults them. See `DECISIONS.md` `D_declared_size`.
+- Add `Component#size`, `#width` and `#height` — read-only shorthands for the matching `rect` field. Reports of the geometry a parent assigned, never requests: there is no writer and no container consults them. See `design/decisions.md` `D_declared_size`.
 - Add `Component#handle_mouse` routing to every child whose `rect` contains the point, so a container gets click delivery without writing one; a widget that resolves clicks itself still overrides without `super`.
-- Add `Component::ConfirmWindow` — the confirm/alert dialog: a caption, a wrapping message and a row of buttons, opened by the `alert` / `confirm` / `yes_no` factories or built button-by-button via `#button`; every route out of it fires `on_dismiss` exactly once. See `DECISIONS.md` `D_confirm_window` and book ch7.
-- Add `Component::InfoWindow#message=` — the prose body, wrapped by a scrollable `TextView` (`ConfirmWindow`'s seam); `#lines=` stays as the rows presentation, and the constructor and `.open` pick the presentation by the body's type. See `DECISIONS.md` `D_info_window_body`.
+- Add `Component::ConfirmWindow` — the confirm/alert dialog: a caption, a wrapping message and a row of buttons, opened by the `alert` / `confirm` / `yes_no` factories or built button-by-button via `#button`; every route out of it fires `on_dismiss` exactly once. See `design/decisions.md` `D_confirm_window` and book ch7.
+- Add `Component::InfoWindow#message=` — the prose body, wrapped by a scrollable `TextView` (`ConfirmWindow`'s seam); `#lines=` stays as the rows presentation, and the constructor and `.open` pick the presentation by the body's type. See `design/decisions.md` `D_info_window_body`.
 - Add `Component::LogTextView` — `LogWindow`'s innards as a standalone `TextView`, so a frameless pane composes the log view directly: the any-thread `#log` and the `IO` adapter live on the view, and `LogWindow` reduces to a `Window` framing one (`LogWindow::IO` stays as an alias).
-- Add `Screen#color_depth` and `ColorDepth.detect` — how many colors the terminal can show (`:truecolor` / `:palette256` / `:ansi16`), detected from `COLORTERM` and `TERM` at construction and overridable with `TUILE_COLOR_DEPTH`. See `DECISIONS.md` `D_color_depth` and book ch6.
+- Add `Screen#color_depth` and `ColorDepth.detect` — how many colors the terminal can show (`:truecolor` / `:palette256` / `:ansi16`), detected from `COLORTERM` and `TERM` at construction and overridable with `TUILE_COLOR_DEPTH`. See `design/decisions.md` `D_color_depth` and book ch6.
 - Add `Color#quantize` — this color as the nearest one a depth can show, returning the receiver when nothing needs degrading. `Buffer#flush` applies it to every color it emits, so a computed RGB tint renders on a 256-color terminal without the app quantizing anything.
 - Add a `color_depth:` keyword to `Buffer.new`, which degrades colors as it flushes them; cells keep whatever color a component painted, so `region_ansi` and friends still report it unchanged.
 - Add a pinned `:truecolor` depth to `FakeScreen`, so a spec asserting frame bytes is unaffected by the runner's `COLORTERM`; a PTY spec asserting bytes passes `TUILE_COLOR_DEPTH` to the child instead.
-- Add `Screen#background_color` — the terminal's own background as a `Color`, nil when it reported none; re-probed on every OS appearance flip, and a changed color fires `Component#on_theme_changed`. See `DECISIONS.md` `D_background_rgb` and book ch6.
+- Add `Screen#background_color` — the terminal's own background as a `Color`, nil when it reported none; re-probed on every OS appearance flip, and a changed color fires `Component#on_theme_changed`. See `design/decisions.md` `D_background_rgb` and book ch6.
 - Add `FakeScreen#background_color=` — plays the terminal answering the re-probe, so a spec can drive app code that derives colors from it.
-- Add `StyledString::Style#inverse` — SGR 7 reverse video, swapping whatever fg/bg are in effect at the cell: parsed and emitted like the other attributes, applied whole-string via `StyledString#with_inverse`, and skipped by `#under_bg` the way an explicit bg is. See `DECISIONS.md` `D_inverse`.
+- Add `StyledString::Style#inverse` — SGR 7 reverse video, swapping whatever fg/bg are in effect at the cell: parsed and emitted like the other attributes, applied whole-string via `StyledString#with_inverse`, and skipped by `#under_bg` the way an explicit bg is. See `design/decisions.md` `D_inverse`.
 - Add a *ConfirmWindow* pane to `examples/sampler.rb` — the three factories, the layer-1 three-way builder and a scrolling Terms-of-Service dialog, with a status row naming which callback each route out of a dialog landed in.
 - Add a terminal-derived tint to the *Background* pane of `examples/sampler.rb` — the borderless-pane step of +10 per channel off `Screen#background_color`, re-derived in `on_theme_changed` and degrading to a "none reported" entry.
 - Fix a click on `Component::Window` chrome not landing focus on the window, which its `focusable?` has claimed all along.
@@ -35,11 +145,11 @@ readable as a `Color`. On top of that sit the dialogs: `ConfirmWindow`, an
 - Fix `Component::Select` opening its dropdown from a click anywhere in its rect, including the tail its own `repaint` clears — it now hit-tests its `extent`, the one row it paints, as `Checkbox` already did on the width axis.
 - Fix a click on a `Component::ListDropdown` margin being able to land focus outside the key scope, killing every keystroke until Tab; the dropdown is now non-focusable by inheritance rather than by geometry.
 - Fix a lower popup's content bleeding through a popup stacked over it: `Screen#repaint`'s drain loop now re-asserts every popup above any layer that repainted, so a repaint cascade spilling into a later iteration can no longer paint over the popups on top.
-- Fix `Screen#theme=` dying with `NoMethodError` when a component overrode `on_theme_changed` under `protected`, aborting the restyle mid-walk. The hook is now protected plumbing fanned out with `__send__`, so an override may declare any visibility. See `DECISIONS.md` `D_hook_visibility`.
-- **Breaking:** `Component#children`, `#parent`, `#parent=`, `#add_child`, `#remove_child` and `#detach_child` are final — overriding any of them raises `Tuile::Error` at construction. Derive nothing: reparent through `add_child` / `remove_child` / `detach_child`, and hold a `Component::Slot` for a swappable region. See `DECISIONS.md` `D_final_tree`.
+- Fix `Screen#theme=` dying with `NoMethodError` when a component overrode `on_theme_changed` under `protected`, aborting the restyle mid-walk. The hook is now protected plumbing fanned out with `__send__`, so an override may declare any visibility. See `design/decisions.md` `D_hook_visibility`.
+- **Breaking:** `Component#children`, `#parent`, `#parent=`, `#add_child`, `#remove_child` and `#detach_child` are final — overriding any of them raises `Tuile::Error` at construction. Derive nothing: reparent through `add_child` / `remove_child` / `detach_child`, and hold a `Component::Slot` for a swappable region. See `design/decisions.md` `D_final_tree`.
 - **Breaking:** a `Component::Window` footer now lives in a `Component::Slot`, so `window.children` always holds that slot and `footer.parent` is the slot rather than the window. Reach the footer through `window.footer`, which is unchanged.
 - **Breaking:** `Component#extent` is a `Size` (or `nil`) rather than a `Rect`, and `Button`, `Checkbox`, `Tabs` and `MenuBar` narrowed with it — an extent always sits at the rect's top-left. Read `#extent_rect` where you need the positioned rectangle.
-- **Breaking:** `Component::Popup#size` is renamed `#declared_size`, and the `Popup.new` / `Component::InfoWindow.open` keyword with it, freeing `size` to mean `rect.size` on any component. Rename the accessor and the keyword at your call sites. See `DECISIONS.md` `D_declared_size`.
+- **Breaking:** `Component::Popup#size` is renamed `#declared_size`, and the `Popup.new` / `Component::InfoWindow.open` keyword with it, freeing `size` to mean `rect.size` on any component. Rename the accessor and the keyword at your call sites. See `design/decisions.md` `D_declared_size`.
 - **Breaking:** `Component::Popup` is always modal — `Popup.new(modal: false)` now raises `ArgumentError`. Build a non-modal overlay with `Component::Overlay.new`, which carries the same lifecycle, `owner`, `on_close` and `close_on_outside_click` members, and place it with `rect=`.
 - **Breaking:** `Component::Notification` and `Component::ListDropdown` subclass `Component::Overlay` rather than `Component::Popup`, neither ever having been modal. An `is_a?(Popup)` test over the popup stack becomes `is_a?(Overlay)`.
 - **Breaking:** `TerminalBackground.detect` returns a `TerminalBackground::Result` (`scheme` plus the reported `color`, nil under the `COLORFGBG` fallback) instead of a bare `Symbol`; nil still means undetectable. Call `.scheme` on the result where you read the symbol.
@@ -53,38 +163,38 @@ fills the terminal and an app builds its own status line. A paste also stops
 being a burst of keystrokes, arriving as one `Component#handle_paste` instead
 of one keystroke per character.
 
-- Add `Screen#on_focus_changed=` — a no-arg callback fired after the focused component *changes*, including to and from `nil` and on the focus repair a closing popup runs. Edge-triggered, so re-focusing what already has focus fires nothing. See `DECISIONS.md` `D_status_bar` and book ch5.
-- Add `mnemonic:` to `Component::MenuBar#add_item` and `MenuBar::Item#add_item` — a letter that activates the item, underlined in its caption, matched level-scoped with no fallback, so only siblings can clash (which raises). See `DECISIONS.md` `D_menu_bar` and book ch7.
+- Add `Screen#on_focus_changed=` — a no-arg callback fired after the focused component *changes*, including to and from `nil` and on the focus repair a closing popup runs. Edge-triggered, so re-focusing what already has focus fires nothing. See `design/decisions.md` `D_status_bar` and book ch5.
+- Add `mnemonic:` to `Component::MenuBar#add_item` and `MenuBar::Item#add_item` — a letter that activates the item, underlined in its caption, matched level-scoped with no fallback, so only siblings can clash (which raises). See `design/decisions.md` `D_menu_bar` and book ch7.
 - Add `Component::List#select` and `Component::ListDropdown#select` — moves the cursor to an item by index, scrolling it into view and firing `on_cursor_changed`; the positional member of the `select_next` / `select_prev` family.
-- Add `Component::MenuBar` — a one-row strip of menu captions, each dropping a cascade of submenus that nests without limit, built from `MenuBar::Item` handles minted and nested by `#add_item`, each carrying an optional no-arg `on_click`. See `DECISIONS.md` `D_menu_bar` and book ch7.
+- Add `Component::MenuBar` — a one-row strip of menu captions, each dropping a cascade of submenus that nests without limit, built from `MenuBar::Item` handles minted and nested by `#add_item`, each carrying an optional no-arg `on_click`. See `design/decisions.md` `D_menu_bar` and book ch7.
 - Add a `MenuBar` shell to `examples/sampler.rb` — the side nav list becomes a menu bar grouped like the README's Components table, plus a `ComboBox` jump box at its right end, and the demo window fills everything below.
 - Add a *MenuBar* pane to `examples/sampler.rb` — a three-deep File menu, an Edit menu, a top-level leaf that acts as a button, and a status line naming the last activated item.
 - Add `Component::ListDropdown#anchor_beside` — places a panel against a row's right edge, flipping left when there is no room and sliding vertically, which is the cascading-submenu counterpart of `#anchor_to`.
 - Add `Component::ListDropdown#cursor_row_rect` and `#on_cursor_changed=` — the highlighted row's rect, and the highlight-moved pass-through a cascading driver needs to drop the panels below the row it left.
-- Add `Component::Tabs` — a one-row strip of captions with one selected: Left/Right switch immediately, a click selects, `#on_tab_selected` reports every change (`nil, nil` once the last tab goes), and tabs are `Tabs::Tab` handles minted by `#add_tab`. See `DECISIONS.md` `D_tabs` and book ch7.
+- Add `Component::Tabs` — a one-row strip of captions with one selected: Left/Right switch immediately, a click selects, `#on_tab_selected` reports every change (`nil, nil` once the last tab goes), and tabs are `Tabs::Tab` handles minted by `#add_tab`. See `design/decisions.md` `D_tabs` and book ch7.
 - Add horizontal scrolling to `Component::Tabs` and `Component::MenuBar` — a strip narrower than its captions now scrolls to keep the selected or highlighted caption whole in view, instead of clipping it.
 - Add a *TabSheet* pane to `examples/sampler.rb` — three tabs over a form, a `List` and a `TextView`, with a status line reporting every pane's state on each switch, so a hidden pane keeping its scroll position is visible rather than asserted.
-- Add `Component::TabSheet` — a `Tabs` strip on its top row plus the selected tab's pane below it, added with `#add_tab(caption, pane)`; unselected panes are *detached* rather than hidden by a flag, so they keep their state and stay out of the Tab cycle. See `DECISIONS.md` `D_tabs`.
+- Add `Component::TabSheet` — a `Tabs` strip on its top row plus the selected tab's pane below it, added with `#add_tab(caption, pane)`; unselected panes are *detached* rather than hidden by a flag, so they keep their state and stay out of the Tab cycle. See `design/decisions.md` `D_tabs`.
 - Add `Screen#beep` and `Ansi::BEL` — rings the terminal bell for a keystroke that went nowhere. It writes immediately rather than riding the next frame, since the keys worth beeping at are precisely the ones that invalidate nothing.
 - Add `StyledString#with_underline` — applies underline to every span, preserving each span's colors and other attributes; the underline counterpart of `#with_bold`. Slice and rejoin to underline part of a string, as a one-character mnemonic cue does.
 - Add `StyledString#with_bold` — applies bold to every span, preserving each span's colors and other attributes; the bold-attribute counterpart of `#with_fg` / `#with_bg`. There is no `under_bold`, since bold has no inherited-unset state.
-- Add `Component#handle_paste` — pasted text, whole and `\n`-normalized, delivered down the focus chain like a key but off the key ladder; the default returns false and `AbstractStringField` inserts at the caret in one mutation. See `DECISIONS.md` `D_bracketed_paste` and book ch5.
+- Add `Component#handle_paste` — pasted text, whole and `\n`-normalized, delivered down the focus chain like a key but off the key ladder; the default returns false and `AbstractStringField` inserts at the caret in one mutation. See `design/decisions.md` `D_bracketed_paste` and book ch5.
 - Add `Screen#run_event_loop(bracketed_paste:)` — on by default, mirroring `capture_mouse:`; pass false for a terminal that mishandles mode 2004.
 - Add `Keys::BRACKETED_PASTE_ON` / `_OFF`, `Keys::PASTE_START` / `PASTE_END`, `Keys.read_paste` and `Keys.normalize_paste` — the terminal-layer half: markers, a raw drain to the terminator, and CR/CRLF-to-`\n` plus a UTF-8 scrub.
 - Add `EventQueue::PasteEvent` — the whole clipboard as one frozen event, posted by the key thread.
 - Add `FakeScreen#paste` — normalizes and dispatches like the real key thread, so a spec can hand it the CR line endings terminals actually send.
 - Add `Component::AbstractStringField#preprocess_paste` — the paste-side input filter; the base drops the C0 controls a text buffer cannot hold and `TextField` also flattens newlines to spaces and trims to `max_text_length`.
 - Add a *Paste* pane to `examples/sampler.rb` — a submit-on-Enter prompt with submit/paste counters, so the distinction is visible (and PTY-testable).
-- Add `Component::Popup#close_on_outside_click?` — a left click outside an open popup now closes it, modal or not (default true; `Component::Notification` opts out). Fixes dropdowns and menu cascades stranded by a click on inert decoration. See `DECISIONS.md` `D_outside_click`.
+- Add `Component::Popup#close_on_outside_click?` — a left click outside an open popup now closes it, modal or not (default true; `Component::Notification` opts out). Fixes dropdowns and menu cascades stranded by a click on inert decoration. See `design/decisions.md` `D_outside_click`.
 - Add `Component::Popup#owner` — names the component an overlay is part of, so a click inside it doesn't dismiss the popup hosting it. `ComboBox`, `Select` and each `MenuBar` cascade panel set it; an overlay without one is independent.
 - Add `Component::Popup#on_close` — a no-arg callback fired once the popup has left the screen, however it left; for a driver keeping its own record of what is open.
 - **Fix:** `Component::TabSheet` no longer holds a removed tab's pane against re-use — `Tabs::Tab#remove` bypasses `TabSheet#remove_tab`, and the stale mapping made `add_tab` reject that pane as still in use.
-- **Fix:** a container whose children exactly tile its rect no longer swallows the repaint cascade — content under it survives an ancestor's `clear_background` instead of vanishing until the next unrelated repaint (visible in the sampler as rows blanking when focus moved). See `DECISIONS.md` `D_repaint_cascade`.
+- **Fix:** a container whose children exactly tile its rect no longer swallows the repaint cascade — content under it survives an ancestor's `clear_background` instead of vanishing until the next unrelated repaint (visible in the sampler as rows blanking when focus moved). See `design/decisions.md` `D_repaint_cascade`.
 - **Fix:** a multi-line paste into a `Component::TextArea` subclass that rebinds ENTER no longer fires that binding once per pasted line ([#4](https://github.com/mvysny/tuile/issues/4)).
 - **Fix:** `Component::TextArea`'s rdoc had the two line-break bytes backwards — a pasted break arrived as `\r`, not `\n`.
-- **Fix:** `Component::TextView#handle_key` no longer refuses every key while the view is unfocused — a vestigial `active?` guard that 0.8.0's dispatch overhaul dropped from every other widget — so hand-feeding it a scroll key scrolls, as with any other component. See `DECISIONS.md` `D_text_view_scroll_verbs`.
+- **Fix:** `Component::TextView#handle_key` no longer refuses every key while the view is unfocused — a vestigial `active?` guard that 0.8.0's dispatch overhaul dropped from every other widget — so hand-feeding it a scroll key scrolls, as with any other component. See `design/decisions.md` `D_text_view_scroll_verbs`.
 - **Breaking:** `Component::TextField#left_column` is now private — the horizontal scroll offset was internal state with no caller outside the field. A spec asserting the scrolling reads it through `send(:left_column)`.
-- **Breaking:** the framework status bar is removed — `ScreenPane#status_bar` is gone and the pane no longer reserves the bottom row, so `content` now fills the whole terminal. Build a status line into your own layout and fill it from `Screen#on_focus_changed=`; `examples/hello_world.rb` and `examples/file_commander.rb` show the shape. See `DECISIONS.md` `D_status_bar`.
+- **Breaking:** the framework status bar is removed — `ScreenPane#status_bar` is gone and the pane no longer reserves the bottom row, so `content` now fills the whole terminal. Build a status line into your own layout and fill it from `Screen#on_focus_changed=`; `examples/hello_world.rb` and `examples/file_commander.rb` show the shape. See `design/decisions.md` `D_status_bar`.
 - **Breaking:** `Component#keyboard_hint` is removed, along with its overrides on `Popup`, `PickerWindow`, `MenuBar`, `Tabs`, `Select`, `ComboBox` and `Notification` — four of them were unreachable in every configuration. Keep the method on your own window classes and call it from your status line; nothing in Tuile consults it now.
 - **Breaking:** `Screen#register_global_shortcut` no longer takes `hint:` — the registry runs actions, it does not describe them. Drop the argument and write the hint into your own status line, next to the registration.
 - **Breaking:** `Screen#active_window` is removed — it existed only to pick the component the status bar asked for a hint. Walk up from `Screen#focused` instead, which is the direction a key actually bubbles.
@@ -98,14 +208,14 @@ folded onto it. The framework also settles its scrolling vocabulary in one
 pass: `row` is the terminal grid unit everywhere, `line` means exactly what
 `String#lines` returns, and `items` are the domain objects a widget renders.
 
-- Add `Component::List#items` / `#items=` and `#renderer` — the list holds typed items, one row each, and a renderer turns an item into its row. See `DECISIONS.md` `D_list_items` and book ch7.
+- Add `Component::List#items` / `#items=` and `#renderer` — the list holds typed items, one row each, and a renderer turns an item into its row. See `design/decisions.md` `D_list_items` and book ch7.
 - Add `Component::List#refresh_rows` — re-renders every row when the renderer's *inputs* changed (a group's selection) while the items and the renderer did not.
 - Add `Component::List#build_lines` — the verb-named builder that `#lines`'s block form used to be: it yields a growing `Array` and assigns it through `#lines=`.
 - Add `Component::ListDropdown#items` / `#items=` / `#renderer=`, forwarding to its list.
-- Add `Component::Notification` — the corner toast: `Notification.show("Saved")` floats a non-modal box in the top-right for three seconds, stacking a burst into one box that drains one message every tick. See `DECISIONS.md` `D_notification` and book ch7.
-- Add `Component::TextArea#caret_row` and `#row_count` — the two readers that answer "has Up/Down anywhere left to go?", so a subclass can claim the key at the text's edge and delegate elsewhere. See `DECISIONS.md` `D_text_area_rows`.
-- Add `Component::TextView#scroll_half_page_up` / `#scroll_half_page_down` — the programmatic form of `Ctrl+U` / `Ctrl+D`, for a host paging a view it does not focus. See `DECISIONS.md` `D_text_view_scroll_verbs`.
-- Add `TERMINOLOGY.md` — a glossary of Tuile's house words, looked up by term; the rules live in `AGENTS.md`'s *Nomenclature* section and the reasoning in `DECISIONS.md` `D_scroll_nomenclature`.
+- Add `Component::Notification` — the corner toast: `Notification.show("Saved")` floats a non-modal box in the top-right for three seconds, stacking a burst into one box that drains one message every tick. See `design/decisions.md` `D_notification` and book ch7.
+- Add `Component::TextArea#caret_row` and `#row_count` — the two readers that answer "has Up/Down anywhere left to go?", so a subclass can claim the key at the text's edge and delegate elsewhere. See `design/decisions.md` `D_text_area_rows`.
+- Add `Component::TextView#scroll_half_page_up` / `#scroll_half_page_down` — the programmatic form of `Ctrl+U` / `Ctrl+D`, for a host paging a view it does not focus. See `design/decisions.md` `D_text_view_scroll_verbs`.
+- Add `design/terminology.md` — a glossary of Tuile's house words, looked up by term; the rules live in `AGENTS.md`'s *Nomenclature* section and the reasoning in `design/decisions.md` `D_scroll_nomenclature`.
 - `Component::List` now renders lazily: only the rows in the viewport, memoized until `items=`, `renderer=` or a width change. A renderer therefore runs at paint time and must stay pure and cheap.
 - `Component::List#lines=` is unchanged and stays supported: it splits on `\n` and stores the resulting `StyledString`s *as* the items, so a line-populated list behaves exactly as before.
 - `Component::List::Cursor`'s count parameters are renamed `item_count` and `viewport_rows` (a cursor indexes items; only the paging half counts rows). They are positional, so no caller changes — a `Cursor` subclass overrides against the new names.
@@ -114,38 +224,38 @@ pass: `row` is the terminal grid unit everywhere, `line` means exactly what
 - **Fix:** `examples/file_commander.rb` navigates again — Enter on a directory called `Rainbow.uncolor` on a `StyledString` and raised.
 - **Breaking:** `Component::List#on_item_chosen` and `#on_cursor_changed` now receive `(index, item)` rather than `(index, line)`. A list populated by `lines=` is unaffected (its items *are* the `StyledString` rows); one populated by `items=` must expect its own objects.
 - **Breaking:** `Component::List#lines` (the reader) is removed — it returned the items, and the name lies once a `renderer` is set. Read `#items`; for the block form call `#build_lines`; to assert what a list *shows*, assert the painted buffer.
-- **Breaking:** `Component::ListDropdown#lines=` / `#lines` are removed — use `#items=` with a `#renderer=`. See `DECISIONS.md` `D_list_items`.
-- **Breaking:** `Component::List#add_line` and `#add_lines` are removed — an append is a statement about a collection the list owns, which a lazily-sourced provider has nothing to mutate. Keep your own array and assign it whole (`list.items = mine`); for incremental append use `Component::TextView`. See `DECISIONS.md` `D_list_items`.
-- **Breaking:** `Component::Popup.open` (the class method) is removed — it hardcoded `Popup.new`, so every subclass inherited a factory that silently built a bare `Popup`. Write `Popup.new(...).open`, which now returns the popup. See `DECISIONS.md` `D_popup_open`.
+- **Breaking:** `Component::ListDropdown#lines=` / `#lines` are removed — use `#items=` with a `#renderer=`. See `design/decisions.md` `D_list_items`.
+- **Breaking:** `Component::List#add_line` and `#add_lines` are removed — an append is a statement about a collection the list owns, which a lazily-sourced provider has nothing to mutate. Keep your own array and assign it whole (`list.items = mine`); for incremental append use `Component::TextView`. See `design/decisions.md` `D_list_items`.
+- **Breaking:** `Component::Popup.open` (the class method) is removed — it hardcoded `Popup.new`, so every subclass inherited a factory that silently built a bare `Popup`. Write `Popup.new(...).open`, which now returns the popup. See `design/decisions.md` `D_popup_open`.
 - **Breaking:** `Buffer#set_line` is now `#set_text` and `Component#draw_line` is now `#draw_text` — both write a `StyledString` starting at `(x, y)` and never filled a row. Rename the calls; behavior is unchanged.
 - **Breaking:** `Component::List#top_line`/`=` and `Component::TextView#top_line`/`=` are now `#scroll_top_row`/`=`, and `Component::TextArea#top_display_row` is now `#scroll_top_row`. Rename the accessors.
 - **Breaking:** `VerticalScrollBar.new(line_count:, top_line:)` is now `.new(row_count:, scroll_top_row:)`. Rename the keywords.
 
 ## [0.11.0] - 2026-08-12
 
-- Add `Component::Select` — a one-row enum field that drops open a `ListDropdown` of its typed `items`; `value` is the selected item, and Enter, Space or Down opens it. It claims no printable key but Space, so a form's own letter bindings keep working while it has focus. See `DECISIONS.md` `D_select` and book ch7.
-- Add `Component::Layout::Vertical` and `Component::Layout::Horizontal` (on the abstract `Component::Layout::Box`) — declarative 1-D layouts where a caller *declares* each child's extent (`Fixed` / `Percent` / `Expand`, plus box-global `spacing`, `padding` and a per-child `align:`) instead of computing it. See `DECISIONS.md` `D_box_layouts` and book ch3.
-- Add `Component::BigDecimalField` — the money field: the shape of `IntegerField`/`FloatField` with an exact `BigDecimal` (or `nil`) value, where assigning a `Float` raises rather than converting. See `DECISIONS.md` `D_bigdecimal_field`.
-- Add `Component::FloatField` — the `IntegerField` twin whose `value` is a `Float` (or `nil`), accepting a single `.` and stepping by `1.0` on Up/Down; `value=` raises on a NaN or infinity. See `DECISIONS.md` `D_float_field`.
+- Add `Component::Select` — a one-row enum field that drops open a `ListDropdown` of its typed `items`; `value` is the selected item, and Enter, Space or Down opens it. It claims no printable key but Space, so a form's own letter bindings keep working while it has focus. See `design/decisions.md` `D_select` and book ch7.
+- Add `Component::Layout::Vertical` and `Component::Layout::Horizontal` (on the abstract `Component::Layout::Box`) — declarative 1-D layouts where a caller *declares* each child's extent (`Fixed` / `Percent` / `Expand`, plus box-global `spacing`, `padding` and a per-child `align:`) instead of computing it. See `design/decisions.md` `D_box_layouts` and book ch3.
+- Add `Component::BigDecimalField` — the money field: the shape of `IntegerField`/`FloatField` with an exact `BigDecimal` (or `nil`) value, where assigning a `Float` raises rather than converting. See `design/decisions.md` `D_bigdecimal_field`.
+- Add `Component::FloatField` — the `IntegerField` twin whose `value` is a `Float` (or `nil`), accepting a single `.` and stepping by `1.0` on Up/Down; `value=` raises on a NaN or infinity. See `design/decisions.md` `D_float_field`.
 - Add `Component::ListDropdown#anchor_to(anchor, rows:, width:, max_rows:)` — placement now lives on the dropdown: below the driver, flipped above when the rows won't fit beneath, and slid left to stay on screen. Width stays a caller decision.
 - `bigdecimal` is Tuile's first optional dependency and is deliberately not in the gemspec: only an app naming `Component::BigDecimalField` loads it, and doing so without the gem raises `LoadError` with the fix in the message. A Bundler app on Ruby 3.4+ must name `bigdecimal` in its own `Gemfile`.
 - `examples/sampler.rb` gains `Select`, `FloatField` and `BigDecimalField` panes, and its demo panes are ported to the box layouts.
-- **Fix (behavior):** `StyledString#wrap` no longer eats a **first-line** indent, so indented text is displayable at all (every `Component::TextView` line goes through `wrap`). `plain("   ").wrap(5)` is now `["   "]` rather than `[""]`; continuations still start at column 0. See `DECISIONS.md` `D_wrap_leading_space`.
+- **Fix (behavior):** `StyledString#wrap` no longer eats a **first-line** indent, so indented text is displayable at all (every `Component::TextView` line goes through `wrap`). `plain("   ").wrap(5)` is now `["   "]` rather than `[""]`; continuations still start at column 0. See `design/decisions.md` `D_wrap_leading_space`.
 - **Fix (behavior):** a `Component::ListDropdown` that scrolls now shows a scrollbar — `List`'s `scrollbar_visibility` defaults to `:gone` and the dropdown never changed it, so an 11-match `ComboBox` looked identical to a 10-match one.
 - **Fix:** `Component::ComboBox` no longer hands its inner `TextField` a one-row rect when its own rect is zero-height — a child painting outside its parent, which a box layout can provoke by starving an over-subscribed child.
 - **Breaking:** `Component::ComboBox::MAX_VISIBLE_ROWS` moved to `Component::ListDropdown::MAX_VISIBLE_ROWS`. Update the constant reference.
-- **Breaking (behavior):** `Component::Checkbox` now toggles on **Enter** as well as Space, matching a checkable row inside a `List`. A focused checkbox therefore consumes Enter, so an ancestor's Enter-to-submit must move to a key no focused field claims. See `DECISIONS.md` `D_boolean_fields`.
+- **Breaking (behavior):** `Component::Checkbox` now toggles on **Enter** as well as Space, matching a checkable row inside a `List`. A focused checkbox therefore consumes Enter, so an ancestor's Enter-to-submit must move to a key no focused field claims. See `design/decisions.md` `D_boolean_fields`.
 
 ## [0.10.0] - 2026-08-02
 
-- Add `Component::Checkbox` — a one-row boolean input (`[x] Enable syslog forwarding`) toggled by Space or a left-click, whose `value` is always `true`/`false`, with `checked?`/`checked=`/`toggle` as the domain-word face over it. See `DECISIONS.md` `D_boolean_fields`.
-- Add `Component::CheckboxGroup` — multi-select over typed `items` whose `value` is a **frozen** `Set` of the selected items, iterating in toggle order (use `items & value.to_a` when order matters). See `DECISIONS.md` `D_checkbox_group`.
-- Add `Component::RadioGroup` — single-select over typed `items` whose `value` is the selected item; it composes a `List`, so the cursor roams without selecting and Space, Enter or a click commits the row under it. See `DECISIONS.md` `D_radio_group`.
+- Add `Component::Checkbox` — a one-row boolean input (`[x] Enable syslog forwarding`) toggled by Space or a left-click, whose `value` is always `true`/`false`, with `checked?`/`checked=`/`toggle` as the domain-word face over it. See `design/decisions.md` `D_boolean_fields`.
+- Add `Component::CheckboxGroup` — multi-select over typed `items` whose `value` is a **frozen** `Set` of the selected items, iterating in toggle order (use `items & value.to_a` when order matters). See `design/decisions.md` `D_checkbox_group`.
+- Add `Component::RadioGroup` — single-select over typed `items` whose `value` is the selected item; it composes a `List`, so the cursor roams without selecting and Space, Enter or a click commits the row under it. See `design/decisions.md` `D_radio_group`.
 - Add `Component::IntegerField` — a single-line input whose `value` is an `Integer` (or `nil`), accepting only digits and a single leading `-`, with Up/Down stepping by one; it composes a `TextField` rather than subclassing one.
 - Add `Component::PasswordField` — a `TextField` painting one mask glyph per character (`mask_char=`, default `*`) with a `revealed=`/`revealed?` toggle; while masked, word-jumps collapse to the ends of the buffer so the mask can't leak word boundaries.
 - Add `Component::TextField#display_text` — the protected seam a subclass overrides when it paints something other than `text`, since the caret, the scroll window and click-to-position all measure it. The contract is one display character per `text` character, in order.
-- Add `Component::ProgressBar` — a display-only fill over a `Range` with `fraction`/`percent` readers and an `indeterminate` mode owning a 5 fps ticker; it stays deliberately outside `Component::HasValue`. See `DECISIONS.md` `D_progress_bar` and `D_color_slots`.
-- Add `Component#on_attached` / `on_detached` — lifecycle hooks fired once per component per transition, letting a component own a mounted-lifetime resource. They are hooks, not destructors: a process exiting without `Screen#close` fires nothing. See `DECISIONS.md` `D_attach_hooks`.
+- Add `Component::ProgressBar` — a display-only fill over a `Range` with `fraction`/`percent` readers and an `indeterminate` mode owning a 5 fps ticker; it stays deliberately outside `Component::HasValue`. See `design/decisions.md` `D_progress_bar` and `D_color_slots`.
+- Add `Component#on_attached` / `on_detached` — lifecycle hooks fired once per component per transition, letting a component own a mounted-lifetime resource. They are hooks, not destructors: a process exiting without `Screen#close` fires nothing. See `design/decisions.md` `D_attach_hooks`.
 - Add `Component::HasCaption` — the caption seam included by `Button` and `Window`, coining the naming split (**caption** is app-authored chrome, **text** is the user-editable value) and making `is_a?`-plus-caption tree lookups possible.
 - `Component::HasValue` now carries `focusable? = true` (overridable). `tab_stop?` is deliberately not folded in: it stays `true` on the leaf `AbstractStringField` and `false` on the composing wrappers, whose inner field carries the stop.
 - `Component::ComboBox` and `Component::IntegerField` compose their inner field via `Component::HasContent` instead of hand-rolling `children`/`rect=`/`on_focus`, so their `content`/`content=` are consequently public.
@@ -153,17 +263,17 @@ pass: `row` is the terminal grid unit everywhere, `line` means exactly what
 - `Screen#close` now unmounts the component tree (via `ScreenPane#detach_all`), so teardown fires `on_detached` across it.
 - `items=` is chrome on `ComboBox` and on both group components: it never touches `value`, so an absent value renders as nothing selected and survives intact, with no reconcile step, clamp or silent drop.
 - `examples/sampler.rb` gains panes for `ProgressBar`, `RadioGroup` and `CheckboxGroup`.
-- Fix the caret stepping by *character* rather than by grapheme cluster: LEFT/RIGHT, BACKSPACE and DELETE now move over and delete exactly one cluster, and the caret is boundary-locked so a mid-cluster position is unrepresentable. See `DECISIONS.md` `D_cluster_caret`.
-- Fix `Component::TextArea` hanging the UI thread on text containing `\r`, `\v` or `\f` — the word-scan measured zero and the wrap loop never advanced, so `area.text = File.read(crlf_file)` was enough to lock up an app. See `DECISIONS.md` `D_text_area_columns`.
-- **Breaking:** `Component#children` is final, and reparenting goes through the protected `add_child(child, at:)` / `remove_child(child)` / `detach_child(child)`. A custom container must stop overriding `children` or hand-wiring `child.parent = …`; named slots become readers over the array. See `DECISIONS.md` `D_tree_api`.
-- **Breaking:** `Component#attached?` is now the one-axis type test `root.is_a?(ScreenPane)` — it consults no `Screen`, so it never raises and a tree can be assembled with no screen in the process. See `DECISIONS.md` `D_tree_first`.
-- **Breaking:** the UI-thread guard is rewritten — `EventQueue#locked?` becomes `#running?` plus `#on_loop_thread?`, the internal `@pretend_ui_lock` and `FakeScreen#check_locked`'s bypass are gone, and `Screen#state` is added. A spec mutating UI from a *spawned* thread now raises exactly as an app would. See `DECISIONS.md` `D_screen_lifecycle`.
-- **Breaking:** `Component#key_shortcut` and `#find_shortcut_component` are removed, along with `ScreenPane#handle_key`'s capture phase and `Window`'s `[k]-Caption` border prefix. Migration: `w.key_shortcut = "1"` becomes a `case` in the containing layout's own `handle_key`. See `DECISIONS.md` `D_key_dispatch`.
+- Fix the caret stepping by *character* rather than by grapheme cluster: LEFT/RIGHT, BACKSPACE and DELETE now move over and delete exactly one cluster, and the caret is boundary-locked so a mid-cluster position is unrepresentable. See `design/decisions.md` `D_cluster_caret`.
+- Fix `Component::TextArea` hanging the UI thread on text containing `\r`, `\v` or `\f` — the word-scan measured zero and the wrap loop never advanced, so `area.text = File.read(crlf_file)` was enough to lock up an app. See `design/decisions.md` `D_text_area_columns`.
+- **Breaking:** `Component#children` is final, and reparenting goes through the protected `add_child(child, at:)` / `remove_child(child)` / `detach_child(child)`. A custom container must stop overriding `children` or hand-wiring `child.parent = …`; named slots become readers over the array. See `design/decisions.md` `D_tree_api`.
+- **Breaking:** `Component#attached?` is now the one-axis type test `root.is_a?(ScreenPane)` — it consults no `Screen`, so it never raises and a tree can be assembled with no screen in the process. See `design/decisions.md` `D_tree_first`.
+- **Breaking:** the UI-thread guard is rewritten — `EventQueue#locked?` becomes `#running?` plus `#on_loop_thread?`, the internal `@pretend_ui_lock` and `FakeScreen#check_locked`'s bypass are gone, and `Screen#state` is added. A spec mutating UI from a *spawned* thread now raises exactly as an app would. See `design/decisions.md` `D_screen_lifecycle`.
+- **Breaking:** `Component#key_shortcut` and `#find_shortcut_component` are removed, along with `ScreenPane#handle_key`'s capture phase and `Window`'s `[k]-Caption` border prefix. Migration: `w.key_shortcut = "1"` becomes a `case` in the containing layout's own `handle_key`. See `design/decisions.md` `D_key_dispatch`.
 - **Breaking:** `Screen#register_global_shortcut` now also rejects `Screen::EDITING_KEYS` — `ENTER`, `BACKSPACE`, `DELETE` and the arrows — which silently broke `TextArea` newlines app-wide. Bind those on an ancestor's `handle_key` instead; `HOME`/`END`/`PAGE_UP`/`PAGE_DOWN` stay legal.
 - **Breaking:** `Component::TextInput` is renamed `Component::AbstractStringField` (file `text_input.rb` → `abstract_string_field.rb`). Only code referencing the constant directly must update.
 - **Breaking:** `Component::Button#caption` and `Component::Window#caption` return a `StyledString`, not a `String`. Measure with `caption.display_width` and recover the plain text with `caption.to_s`.
-- **Breaking (behavior):** all glyph measurement is now per grapheme cluster under one emoji policy (`:rgi`), so `"👍🏽"` measures 2 columns rather than 4 and no longer overruns its cell. Custom components measuring with `String#length` or iterating `each_char` must move to `StyledString#display_width` / `slice` / `ellipsize`. See `DECISIONS.md` `D_cluster_width`.
-- **Breaking (behavior):** `Component::TextField` separates the caret's character index from its terminal column and **scrolls horizontally** instead of being capped by its own width. `max_text_length` is now an explicit, settable cap defaulting to `nil` (unbounded) rather than the derived `rect.width - 1`. See `DECISIONS.md` `D_text_field_axes`.
+- **Breaking (behavior):** all glyph measurement is now per grapheme cluster under one emoji policy (`:rgi`), so `"👍🏽"` measures 2 columns rather than 4 and no longer overruns its cell. Custom components measuring with `String#length` or iterating `each_char` must move to `StyledString#display_width` / `slice` / `ellipsize`. See `design/decisions.md` `D_cluster_width`.
+- **Breaking (behavior):** `Component::TextField` separates the caret's character index from its terminal column and **scrolls horizontally** instead of being capped by its own width. `max_text_length` is now an explicit, settable cap defaulting to `nil` (unbounded) rather than the derived `rect.width - 1`. See `design/decisions.md` `D_text_field_axes`.
 - **Breaking (behavior):** `Component::Button#handle_mouse` fires `on_click` only within the button's painted **extent**, not anywhere in its `rect`, and `Component::Checkbox` follows the identical rule. A click on the blank tail still focuses the button but no longer activates it.
 
 ## [0.9.0] - 2026-07-05

data/README.md

@@ -12,10 +12,12 @@ providers — is described in
 Tuile is that approach applied to a terminal.
 
 Tuile is the only actively maintained component-oriented TUI framework for
-Ruby that we are aware of. If you have looked at the alternatives —
-tty-toolkit, vedeu, ratatui, or the curses bindings your distro packages —
-[COMPARISON.md](COMPARISON.md) sizes each one up and says which of them you
-can actually reach from Ruby.
+Ruby that we are aware of. Ruby does now reach two of the big non-Ruby
+toolkits — Rust's ratatui through `ratatui_ruby`, Go's Charm stack through
+CharmRuby — but both hand you a draw loop or an Elm-style model/update/view,
+not a tree of components. [The research notes](design/research.md) size up each
+neighbour, those two included, alongside tty-toolkit, vedeu and the curses
+bindings your distro packages.
 
 ## Installation
 
@@ -55,8 +57,8 @@ else in Tuile loads it.
 - **API reference:** every public class and method carries YARD headers —
   browse them at <https://rubydoc.info/gems/tuile>, or run
   `bundle exec rake yard` for a local site.
-- **[COMPARISON.md](COMPARISON.md)** places Tuile among the neighbouring
-  toolkits, and answers what a Ruby program can reach without writing
+- **[The research notes](design/research.md)** size up the neighbouring
+  toolkits, and answer what a Ruby program can reach without writing
   bindings first.
 
 ## Hello world
@@ -137,9 +139,20 @@ between panes. A paste is deliberately *not* a burst of keys: with bracketed
 paste it arrives whole, as one `handle_paste`.
 → [chapter 5](book/05-focus.md)
 
+**The mouse is routed by position, and claimed by one component.** A press
+focuses the innermost focusable under the pointer before any handler runs,
+then bubbles outward through `handle_mouse_down?` until someone answers
+`true` — and that claimant is *grabbed*, so the drags and the release reach
+it wherever the pointer goes. The wheel bubbles the same way, so a list
+already at its top hands the notch up to whatever scrolls around it. `capture_mouse:` picks how
+much the terminal reports: `:clicks`, `:drag`, or `:hover` with enter/exit
+hooks.
+→ [chapter 5](book/05-focus.md)
+
 **Theming is accents-only, and follows the OS.** A `Theme` carries semantic
-accent tokens — the list cursor, an input well, an active window border,
-status-bar hints — plus whatever `custom` tokens your app adds. Everything
+accent tokens for the chrome Tuile itself paints — the list cursor, an input
+well, an active window border, a scrollbar — plus whatever `custom` tokens your
+app adds for text of its own (a status row's shades live there). Everything
 else inherits the terminal's own foreground and background, so Tuile looks at
 home in the user's palette instead of fighting it. Tuile probes the terminal
 background at startup, pairs a dark and a light theme in a `ThemeDef`, and
@@ -148,6 +161,15 @@ read — `Screen#background_color` — for panes tinted a few percent off the
 terminal's own, LazyVim-style.
 → [chapter 6](book/06-theming.md)
 
+**A `Locale` holds conventions, never prose.** Date formats, the calendar,
+month and weekday names, the decimal separator — detected from `locale(1)` at
+startup, but only when the environment actually asked for something, since the
+POSIX default is American and "said nothing" is indistinguishable from "wants
+American". Everything else falls back to `Locale::ISO`. Tuile ships no message
+catalogue and no per-country presets: this is the formatting half of what POSIX
+splits, and the wording half stays your app's.
+→ [chapter 10](book/10-locale.md)
+
 ## Components
 
 Every component lives under `Tuile::Component::*`, and every one of them is a
@@ -198,6 +220,9 @@ carries the per-method reference: `bundle exec rake yard`, or
 | `IntegerField` | A one-row field whose `value` is an `Integer` or `nil`, filtering input to digits and one leading `-`. |
 | `FloatField` | The same, one Ruby type over: `value` is a `Float` or `nil`. |
 | `BigDecimalField` | The same for money, where a binary `Float` is the wrong answer. Tuile's one optional dependency — add `bigdecimal` yourself if you name this component. |
+| `DateField` | A one-row field whose `value` is a `Date` or `nil`, over a list of strftime formats taken from `Screen#locale`: it accepts any of them and writes the first one back when you leave the field. Manual entry — there is no calendar popup yet. |
+| `TimeField` | A one-row field whose `value` is a time of day — a `Time` on a fixed epoch date, or `nil` — spelled the way `Screen#locale` says. `step` is both the Up/Down stride and the precision: it shows seconds only when set below a minute. |
+| `DateTimeField` | The two above side by side on one row, behind a single `DateTime` at `+00:00`. Each half reddens its own bad input; the field reddens whole only for the fault no half can wear — one half filled and the other empty. |
 
 ### Choosing from a set — [book ch7](book/07-components.md#choosing-from-a-set)
 
@@ -223,18 +248,21 @@ carries the per-method reference: `bundle exec rake yard`, or
 |---|---|
 | `Overlay` | The bare floating layer: it wraps any component, paints nothing itself, and sits at the rect you assign it. Takes no focus and no keys — the building block for anchored panels and toasts. |
 | `Popup` | The modal dialog: an `Overlay` that centers itself, grabs focus, scopes keys to its own subtree and blocks clicks beneath it. Sized by `declared_size=` (a `Size` or a `Fraction` of the screen) rather than by its content; ESC or `q` dismisses. |
-| `Notification` | A transient corner toast — `Notification.show("Saved")` — stacking messages in one box that a single ticker drains. Non-modal, and it never takes focus. |
+| `Notification` | A transient corner toast — `Notification.show("Saved")` — stacking messages in one box that a single ticker drains. Non-modal, it never takes focus, and its inner `View` refuses the wheel so queued messages wait for the ticker. |
 | `ConfirmWindow` | The confirm dialog: a message and a row of buttons in a popup sized to fit. `alert` / `confirm` / `yes_no` cover the common shapes; `#button` builds any other. Every button closes; ESC, `q` or an outside click fire `on_dismiss`. See [The confirm dialog](book/07-components.md#the-confirm-dialog). |
 | `InfoWindow` | A `Window` with a read-only body, tiled or popped up: prose that wraps (`message=`), or rows that don't (`lines=`). |
-| `PickerWindow` | A `Window` of options identified by single keystrokes, firing a callback with the key that was pressed. |
+| `PickerWindow` | A `Window` of options identified by single keystrokes, firing a callback with the key that was pressed. Captions take a `StyledString` to color one. |
 | `LogTextView` | An auto-scrolling `TextView` for log output. Point your logger at a `LogTextView::IO` and lines land here from any thread, marshalled through the event queue. |
 | `LogWindow` | A `Window` framing a `LogTextView` — the framed log pane. |
 
 The mixins those share — `HasValue` (the `value` / `empty?` / `clear` /
-`on_value_change` seam every input speaks), `HasContent` (one-child
-containers) and `HasCaption` (app-authored chrome text) — are the seams to
-include when you write your own; chapter 7's "value seam" section is the
-walkthrough.
+`on_value_change` seam every input speaks), `HasValidation` (`error_message`,
+the verdict a validator writes and the field shows as a red well), `HasBadInput`
+(`bad_input?`, for a field whose input can be something its value cannot
+represent — a lone `-` in a number), `HasContent` (a primary child the caller
+populates, named `content`) and
+`HasCaption` (app-authored chrome text) — are the seams to include when you
+write your own; chapter 7's "value seam" section is the walkthrough.
 
 ## Geometry primitives
 
@@ -258,7 +286,7 @@ Tuile.logger = Logger.new(Tuile::Component::LogTextView::IO.new(view))
 ## Testing
 
 Tuile ships with a `Tuile::FakeScreen` that you install in place of the real
-screen for unit tests. It fixes the viewport at 160×50, disables the UI lock,
+screen for unit tests. It fixes the viewport at 160×50,
 paints into an in-memory back buffer (assert on it for painted content) while
 capturing cursor/housekeeping escapes into an array, and uses a synchronous
 `FakeEventQueue` (submitted blocks run inline; posted events are discarded).
@@ -303,6 +331,12 @@ Key hooks:
   to its current value should typically *not* invalidate.
 - `Screen.instance.clear` — drops accumulated `prints` without resetting
   invalidation.
+- `Tuile::Testing.get` / `.find` — locate a component to drive, by class,
+  mixin, `Component#id`, caption or a block:
+  `Testing.get(Component::Button, caption: "Save")`. `get` demands exactly
+  one match and prints the tree it searched when it doesn't get one; `find`
+  returns all matches and takes `count:`. Both take `in:` to scope the
+  search, and default to the whole screen. Call them qualified.
 
 Because `FakeEventQueue#submit` runs the block immediately on the calling
 thread, code paths that marshal work back via `screen.event_queue.submit { … }`
@@ -322,14 +356,16 @@ run `bundle exec rake spec` to run the tests. You can also run `bin/console`
 for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
-To release a new version, see [`RELEASING.md`](RELEASING.md).
+To release a new version, see [`design/releasing.md`](design/releasing.md).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
 <https://github.com/mvysny/tuile>. Please read [`AGENTS.md`](AGENTS.md) before
 opening a PR — it documents the architecture invariants (singleton screen,
-invalidation/repaint contract, threading rule) that the framework relies on.
+invalidation/repaint contract, threading rule) that the framework relies on,
+and routes you to [`design/`](design/), where
+[`decisions.md`](design/decisions.md) answers "why is it like this?".
 This project is intended to be a safe, welcoming space for collaboration, and
 contributors are expected to adhere to the
 [code of conduct](https://github.com/mvysny/tuile/blob/master/CODE_OF_CONDUCT.md).