tuile 0.12.0 → 0.14.0

data/TERMINOLOGY.md

@@ -4,7 +4,7 @@ Tuile's house vocabulary — one line per term, looked up by word.
 
 This file owns **definitions only**. The *rules that bite* live in AGENTS.md
 ("Nomenclature" and the sections each word belongs to); the *why we chose a word
-and not its synonym* lives in DECISIONS.md (`D-scroll-nomenclature` for the
+and not its synonym* lives in DECISIONS.md (`D_scroll_nomenclature` for the
 row/line/item split); the *concepts* live in the book. When a definition here
 needs a paragraph of justification, that paragraph belongs in one of those three.
 
@@ -15,14 +15,16 @@ needs a paragraph of justification, that paragraph belongs in one of those three
 | **row** | one row of the terminal grid — the framework's only word for it. A wrapped unit of text *is* a row; wrapping is what turns text into rows. |
 | **column** | one cell-column of the terminal grid; the unit `display_width` counts. |
 | **cell** | one grid position: a grapheme plus a {Tuile::StyledString::Style}, in {Tuile::Buffer}. |
-| **glyph** | what the terminal draws in one or more cells. Ambiguous-width glyphs count as **one** column (the bet in `D-ambiguous-width`). |
+| **glyph** | what the terminal draws in one or more cells. Ambiguous-width glyphs count as **one** column (the bet in `D_ambiguous_width`). |
 | **cluster** | a grapheme cluster — the unit measurement, slicing, caret motion and deletion all work in. Never `each_char`. |
 | **row_in_viewport** | a row measured `0...rect.height`, i.e. relative to a component's own rect. |
 | **scroll_top_row** | the content row currently sitting at the top of the viewport. |
+| **left_column** | the content column currently painted in a widget's leftmost cell — the horizontal counterpart of `scroll_top_row`. Private wherever it exists (`TextField`, `Tabs`, `MenuBar`): what a caller relies on is the invariant it maintains — the caret, or the selected segment, is in view — not the number. |
 | **viewport_rows** | how many rows of content are visible — always `rect.height`; kept private, since `rect.height` is the public form. |
 | **row_count** | how many rows the wrapped content occupies. Public on `TextArea` (with `caret_row`, its companion); also on the private `WrappedText` and as `VerticalScrollBar.new(row_count:)`. Not on `TextView` / `List`, which have no caller for it. |
 | **caret_row** | the row a text input's caret sits in, counted from the content's first row. `TextArea` only. |
-| **extent** | the sub-rect a one-row caption widget actually occupies (`min(caption width + 4, rect.width)`), used for its highlight and hit test — narrower than its `rect`. |
+| **extent** | the `Size` a widget actually paints inside the `rect` it was given — `Component#extent`, `nil` unless declared, always at the rect's top-left (`Component#extent_rect` positions it). What the widget clears outside of, hit-tests, highlights and anchors its dropdown to. The arithmetic is each widget's own (a `Checkbox`'s glyph plus caption; a `Tabs` strip's segments and separators). Distinct from a *slot extent*. |
+| **segment** | one tab's span on a {Tuile::Component::Tabs} strip: its caption plus a padding column either side. The unit a click resolves to; the separator column between two segments belongs to neither. |
 
 **Space rule 1.** An object with only one row space leaves `row` unqualified:
 {Tuile::Buffer} *is* the grid, so its rows are screen rows;
@@ -40,10 +42,11 @@ content-space.
 | **line_count** | a count of `\n` units (`TextView::Region#line_count`). Never a row count. |
 | **item** | a domain object a widget holds and renders — `List#items`, and the enum widgets above it. |
 | **renderer** | the `item -> row` proc a generic component uses to render an item it knows nothing about. |
+| **selection** | which item or tab a selector currently points at. *View state* when nothing would save it ({Tuile::Component::Tabs}`#selected`), a *value* when a form would (`RadioGroup#value`) — the split `D_tabs` calls the "would a form save it?" test. |
 | **item_count** / **item_index** | how a `List::Cursor` counts and addresses; equal to a row count in a `List`, but the cursor indexes *items*. |
 | **text** | the user-editable **value** of an input ({Tuile::Component::HasValue}, aliased as `text` on `AbstractStringField`). |
 | **caption** | app-authored **chrome** text ({Tuile::Component::HasCaption}) — a `Window` title, a `Button` label. Never a value. |
-| **chrome** | framework- or app-authored decoration around content: captions, borders, footers, the status bar. |
+| **chrome** | framework- or app-authored decoration around content: captions, borders, footers, an app's status line. |
 | **caret** | the index into an input's `text` where editing happens; always on a cluster boundary. Distinct from the *cursor*. |
 
 ## Tree, paint and theme
@@ -51,9 +54,16 @@ content-space.
 | term | means |
 |---|---|
 | **component** | a node of the UI tree ({Tuile::Component}); the only thing that paints. |
+| **slot extent** | in a `Layout::Box`, the size a parent *allocates* a child along an axis — what `Fixed` / `Percent` / `Expand` declare, and what `main_extent` / `cross_extent` measure. The parent's allocation, where a component's *extent* is the child's own painted region; `D_extent` turns on the two being different. Here `slot` is the box's allocation for one child and has **nothing** to do with {Tuile::Component::Slot} — the phrase is glossary-only (the code says `main_extent` / `cross_extent`), so read it as one term, never as "the extent of a `Slot`". |
 | **tile** / **tiled** | the non-popup part of the tree — `ScreenPane#content` and its descendants. Also *to tile*: to cover a rect completely. |
 | **attached** | reachable from a {Tuile::ScreenPane} via the parent chain — the one axis `attached?` consults. |
-| **slot** | a named child a container holds by identity (`content`, `footer`) as well as in `children`. |
+| **slot** | a named region of a container, reached by identity (`content`, `footer`) as well as through `children`. Two forms: a plain named child, when the occupant is permanent and integral (`HasContent#content`); or a {Tuile::Component::Slot}, the one-child region component, when the occupant may be absent or swapped (`Window#footer`). Capital-`S` `Slot` always means the class. |
+| **cascade** | the stack of open {Tuile::Component::ListDropdown} panels a {Tuile::Component::MenuBar} drives, one per level, the last deepest. Each is an overlay on the pane, not a child of the bar. |
+| **submenu** | a menu item that opens a further panel instead of doing something — `MenuBar::Item#submenu?`, true iff the item has children. Painted with a trailing `▸`. |
+| **mnemonic** | a letter that activates one {Tuile::Component::MenuBar} item, underlined in its caption. Always *level-scoped*: matched against the top-level items while the cascade is closed and the deepest open panel while it is open, never across the two. |
+| **strip** | the one-row {Tuile::Component::Tabs} component: captions, one selected, no content of its own. A {Tuile::Component::MenuBar} has one too — same word, and the same extent-based hit testing, deliberately not the same look. |
+| **tab** | a {Tuile::Component::Tabs::Tab} — a caption plus an identity, minted and owned by the strip. Not a component (it never paints itself) and not an *item* (it holds per-element state, and the set is never assigned whole). Say "a tab" and "the Tab key"; never let the two words touch. |
+| **pane** | the component a {Tuile::Component::TabSheet} shows for the selected tab. The unselected ones are *detached*, which is how Tuile hides a component. |
 | **invalidate** | record a component as needing repaint; the loop coalesces and repaints once per tick. |
 | **cursor** | *(two senses, both live)* the hardware terminal cursor (`Screen#cursor_position`), and a `List::Cursor` — the selection position within a list. |
 | **well** | the explicit background an input paints over its whole rect (`Theme#input_bg_color` / `#active_bg_color`), which opts it out of `bg_color` inheritance. |

data/book/01-first-app.md

@@ -104,11 +104,10 @@ window.focus
 
 `screen.content = window` makes the window the screen's **tiled content**
 — the component that fills the terminal. Setting it triggers a layout
-pass: the window is handed a rectangle spanning the whole screen (minus
-one bottom row, which we'll get to), and it in turn sizes the label
-inside its border. This is the top-down cascade in miniature — the screen
-sizes the window, the window sizes its content — and it re-runs, top
-down, every time the terminal is resized.
+pass: the window is handed a rectangle spanning the whole screen, and it
+in turn sizes the label inside its border. This is the top-down cascade in
+miniature — the screen sizes the window, the window sizes its content —
+and it re-runs, top down, every time the terminal is resized.
 
 `window.focus` marks the window as the **focused** component: the one
 that receives keystrokes. Focus flows down toward interactive content
@@ -117,30 +116,36 @@ the active thing." In a one-window app it's mostly cosmetic (it draws the
 border in the active color); in a real app, focus is what routes the
 keyboard, and it gets its own chapter (chapter 5).
 
-You may have noticed you never created a status bar, yet the app has one
-— the bottom row showing `q quit`. That's because your window isn't the
-whole story of what's on screen.
+Run it and you'll notice what *isn't* there: no status bar, no menu, no
+title chrome beyond the border you asked for. **Tuile paints nothing you
+didn't build.** Other TUI toolkits hand you a status row and a hint line
+for free; Tuile gives your content the whole terminal and lets you decide
+whether a bottom row is worth one of your rows. A status line is three
+lines of layout when you want one — `examples/hello_world.rb` adds one,
+and chapter 3 shows the mechanism.
+
+That is the same instinct as top-down layout: the framework declines to
+make sizing decisions on your behalf, here by declining to spend a row.
 
 ## The tree you didn't build
 
 Your `window` isn't actually the root of the tree. The real root is a
 structural node called the {Tuile::ScreenPane}, owned by the screen, and
-it holds three things:
+it holds two things:
 
 ```
 ScreenPane                (structural root — paints nothing itself)
 ├── content               your window (the tiled UI)
-├── popups                modal overlays, when you open them (none yet)
-└── status_bar            the bottom row (that "q quit" hint)
+└── popups                modal overlays, when you open them (none yet)
 ```
 
 You only ever manage the `content` slot directly (via `screen.content=`);
-the pane, the popup stack, and the status bar are the framework's. The
-reason everything — including popups — lives under one parent is
-uniformity: focus traversal, "is this component still on screen?", and
-cleanup when a component is removed all work the same way for every node,
-with no special cases. You'll meet popups in chapter 7; for now it's
-enough to know the pane is up there, quietly being the root.
+the pane and the popup stack are the framework's. The reason everything —
+including popups — lives under one parent is uniformity: focus traversal,
+"is this component still on screen?", and cleanup when a component is
+removed all work the same way for every node, with no special cases.
+You'll meet popups in chapter 7; for now it's enough to know the pane is
+up there, quietly being the root.
 
 ## Run the loop, and always close
 

data/book/02-repaint.md

@@ -136,14 +136,27 @@ Meeting that second half is easy, because the default
 - A **leaf** component (no children) gets its background cleared
   automatically, so you can paint your content and trust the rest is
   blanked.
-- A **container whose children exactly tile its rect** skips the clear —
-  the children will cover everything anyway.
 - A **container with gaps** between its children (a form with
-  mixed-width fields, say) gets the background cleared *and* its children
-  re-invalidated, so they repaint cleanly on top. This is what makes
-  gappy layouts safe without every container writing its own
+  mixed-width fields, say) gets the background cleared, because those gap
+  cells are ones no child will paint over.
+- A **container whose children exactly tile its rect** skips the clear —
+  the children cover every cell anyway, and blanking a cell you are about
+  to repaint would only mark it dirty for the flush.
+- **Either way, a container re-invalidates its children.** That is what
+  makes gappy layouts safe without every container writing its own
   damage-tracking pass.
 
+That last point is worth a moment, because the obvious optimization is
+wrong. A clear wipes the container's *whole* rect — every descendant's
+cells, not just the gaps — but a container only ever notifies its own
+direct children, so the notice has to keep travelling down on its own. A
+tiling container that stayed quiet ("my children cover everything, nothing
+to do") would be a dead end: its grandchildren would never learn their
+cells had been blanked by an ancestor, and their content would vanish until
+some unrelated event happened to invalidate them. Repainting more than
+strictly necessary costs nothing here — identical glyphs leave a cell
+unchanged, so the diff is still empty and nothing reaches the wire.
+
 The practical rule for writing a component: **call `super` in your
 `repaint`** to inherit that clearing, then paint your content. The only
 components that skip `super` are the few that paint every cell of their

data/book/03-layout.md

@@ -40,9 +40,9 @@ rectangles they are given. If new content arrives that is too tall for
 its pane, the pane scrolls or clips — it does not push back on the
 parent to grow.
 
-This is already how Tuile's tiled UI works today: `ScreenPane` sizes
-your content and the status bar; every real layout you write positions
-its children the same way. The chapter's job is to convince you that
+This is already how Tuile's tiled UI works today: `ScreenPane` hands your
+content the whole terminal; every real layout you write positions its
+children the same way. The chapter's job is to convince you that
 this is a feature, then show you the few pieces of vocabulary that make
 it comfortable.
 
@@ -160,8 +160,9 @@ common case, debuggability, and auditability all at once.
 
 The place you actually write layout code is a `rect=` override. The base
 class for this is `Tuile::Component::Layout::Absolute`: it inherits all
-the focus and key-dispatch wiring, paints nothing itself, and asks only
-that you position your children whenever your own rectangle is assigned —
+the focus, key-dispatch and mouse-routing wiring, paints nothing itself,
+and asks only that you position your children whenever your own rectangle
+is assigned —
 which happens once at startup and again on every resize.
 
 ```ruby
@@ -342,16 +343,17 @@ The boxes are sugar, not a replacement, and they can't say everything. A **cap
 on a proportion** is the case to recognise:
 
 ```ruby
-list_width  = (rect.width / 3).clamp(20, 40)  # a third, but never <20 or >40
 group_width = [16, rect.width / 3].min        # a third, but never more than 16
+list_width  = (rect.width / 3).clamp(20, 40)  # a third, but never <20 or >40
 ```
 
-Both of these are in `examples/sampler.rb`, and both keep a `rect=`
-override. That's the intended division of labour rather than a gap to work
-around: use a box for the stack, drop to `Absolute` for the region that
-genuinely needs arithmetic — usually nesting one inside the other, so only the
-awkward part carries any. The sampler does exactly that, and porting it to
-these layouts took it from 59 hand-written rectangles down to 7.
+The first is in `examples/sampler.rb` twice — the sidebar in its CheckboxGroup
+pane and the one in its List pane — and both keep a `rect=` override. That's
+the intended division of labour rather than a gap to work around: use a box for
+the stack, drop to `Absolute` for the region that genuinely needs arithmetic —
+usually nesting one inside the other, so only the awkward part carries any. The
+sampler does exactly that, and porting it to these layouts took it from 59
+hand-written rectangles down to a handful (5 today).
 
 ## Geometry: `Point`, `Size`, `Rect`
 
@@ -395,24 +397,24 @@ class Fraction < Data.define(:width, :height)   # each a float in 0.0..1.0
 end
 ```
 
-A popup's size is set with `Popup#size=`, which accepts either a
+A popup's box is set with `Popup#declared_size=`, which accepts either a
 `Fraction` (resolved against the screen at layout time, so it tracks
 resize) or an absolute `Size` (clamped to the screen):
 
 ```ruby
 popup = Tuile::Component::Popup.new(content: some_window)
-popup.size = Tuile::Fraction::HALF     # the default — half the screen, centered
-popup.size = Tuile::Fraction::FULL     # fullscreen
-popup.size = Tuile::Fraction.new(0.8, 0.5)          # 80% wide, half tall
-popup.size = Tuile::Size.new(50, 12)                # exact, clamped to screen
+popup.declared_size = Tuile::Fraction::HALF     # the default — half the screen, centered
+popup.declared_size = Tuile::Fraction::FULL     # fullscreen
+popup.declared_size = Tuile::Fraction.new(0.8, 0.5)          # 80% wide, half tall
+popup.declared_size = Tuile::Size.new(50, 12)                # exact, clamped to screen
 ```
 
 The default is `Fraction::HALF`, resolved on every layout pass, so a
 popup you never size at all is half-screen and follows the terminal as
 it resizes. `Fraction::FULL` is the fullscreen shorthand.
 
-A subtle but important point: `size=` is **authoritative, not a
-preference**. The name is `size`, not `preferred_size`, on purpose.
+A subtle but important point: `declared_size=` is **authoritative, not a
+preference**. The name says *declared*, not *preferred*, on purpose.
 There is no parent that might negotiate it downward — the screen simply
 *applies* what you asked for (clamping an oversized absolute `Size` to
 fit). Calling it a preference would invite a future "well, the parent
@@ -433,7 +435,7 @@ wrong for a paragraph.
 > height) and it isn't even reliably pretty — a single long line
 > collapses the popup to one row. Half-screen-and-wrap sidesteps all of
 > it. When you genuinely know the right size — an autocomplete dropdown
-> whose items you own — you set it yourself: `popup.size =
+> whose items you own — you set it yourself: `popup.declared_size =
 > Tuile::Size.new(longest_item, [items.size, 8].min)`. That's still
 > caller-decides, top-down.
 
@@ -481,6 +483,12 @@ A component in the footer slot always fills the width — there is no
 sizing policy to configure, because the window already knows its inner
 width and that's the only dimension a bottom-row widget needs.
 
+The word *slot* is literal here: the footer is a
+{Tuile::Component::Slot}, the one-child region you'd use for the same job
+in a container of your own (chapter 7). That's why `footer=` needs no
+sizing argument and why setting it to `nil` restores the border cleanly —
+the region stays in the tree either way, occupied or not.
+
 The two are mutually exclusive by precedence: if a `footer=` component
 is present it occupies the bottom row and `footer_text` is hidden;
 otherwise `footer_text` embeds into the border. No window needs both at

data/book/05-focus.md

@@ -45,7 +45,10 @@ decoration; clicking one shouldn't yank focus away from the window around
 it. Controls that accept input (a text field, a list, a button) override
 it to `true`. This gate is what makes click-to-focus sane: clicking lands
 focus on the component under the cursor *only if it's focusable*,
-otherwise the click is ignored for focus purposes. The same rule governs
+otherwise the click is ignored for focus purposes. A click descends the
+tree — every component whose rectangle contains the point sees it, outermost
+first — so "the component under the cursor" is really all of them, and focus
+settles on the deepest focusable one. The same rule governs
 the automatic focus-forwarding a container does when it's focused — a
 window handed focus passes it down to its content, but only if that
 content is focusable.
@@ -125,6 +128,17 @@ scan of the scope for a component carrying a matching "shortcut key,"
 which would jump focus to it. It's gone; the next section explains why the
 bubble does that job better.
 
+One thing does happen *after* the ladder, and it lives in the loop rather
+than in dispatch: if nothing handled the key and it was `q` or ESC, the
+loop stops and your program exits. That is what a `q quit` hint in an app's
+status line is describing — not a binding anyone registered, but the fate
+of an unclaimed quit key. It also explains why ESC means different
+things in different places: an open {Tuile::Component::Popup} handles ESC
+itself (dismissing is its job), so the loop never sees it and the popup
+closes instead of the app. And a widget keeps a stray `q` from quitting
+simply by consuming it, which a focused {Tuile::Component::TextField} was
+doing anyway — it's a printable character.
+
 ## Scope-wide keys live on an ancestor
 
 Two things every app wants: `1`/`2`/`3` to jump between panes, and Enter to
@@ -161,6 +175,7 @@ The same mechanism gives you a form's default button, one form per popup:
 | `Button` | consumes it | activates *itself*, not the default |
 | `Checkbox` | consumes it (toggles) | the form never sees it |
 | `Select` | consumes it (opens, then commits) | the form never sees it |
+| `Tabs` | declines | bubbles up → submit |
 
 Because bubbling stops at the scope root, two forms in two popups each get
 their own Enter — something a global registry structurally cannot do. This
@@ -172,6 +187,76 @@ child table, rather than each widget declaring its own mnemonic. That's a
 fair trade: which key jumps where is a decision about the assembly, and it
 reads well in one place.
 
+## Paste is not a keystroke
+
+Everything above is about keys. A paste looks like keys — and that
+resemblance is a genuine problem, not a convenience.
+
+Ask a terminal to paste eight lines and, by default, it types them at your
+program: one byte at a time, with every line break converted to `\r`. That
+`\r` is byte-identical to the Enter you press with your finger. So a prompt
+that rebinds Enter to "submit" submits eight times, and no amount of
+cleverness in `handle_key` can tell the two apart — by the time the key
+arrives, the information is gone.
+
+The fix has to happen one layer down, at the code that talks to the
+terminal. {Tuile::Screen#run_event_loop} enables **bracketed paste** (DEC
+private mode 2004), which asks the terminal to wrap pasted text in
+`\e[200~` … `\e[201~` markers. Tuile's key thread recognizes the opening
+marker, reads the payload raw up to the terminator, and posts it as a
+single `PasteEvent` — which never enters the ladder at all:
+
+- no Tab traversal, no global shortcuts, no `handle_key`;
+- straight to {Tuile::Component#handle_paste}, delivered down the focus
+  chain and bubbling exactly like a key;
+- the whole clipboard as one `String`, `\n`-normalized.
+
+The default `handle_paste` returns `false` and the text is dropped.
+{Tuile::Component::AbstractStringField} overrides it to insert at the caret
+as **one** mutation — so `on_change` fires once for the paste rather than
+once per character, and a subclass that claims Enter needs no paste code of
+its own:
+
+```ruby
+class PromptTextArea < Tuile::Component::TextArea
+  protected
+
+  def handle_text_input_key(key)
+    return super unless key == Tuile::Keys::ENTER
+
+    submit(text)   # a typed Enter, and only ever a typed Enter
+    self.text = ""
+    true
+  end
+end
+```
+
+Override `handle_paste` yourself when a paste should mean something other
+than "insert this": collapsing a huge clipboard to a `[Pasted 230 lines]`
+placeholder, say, or pulling a file path out of it.
+
+```ruby
+def handle_paste(text)
+  return super if text.lines.size < 20
+
+  attach_as_file(text)
+  self.text = "#{text.lines.size} lines attached"
+  true
+end
+```
+
+Two smaller consequences worth knowing. Because the payload is read raw
+rather than through {Tuile::Keys.getkey}, a pasted ESC or Tab stays payload
+— unbracketed, a pasted Tab moves focus and a pasted ESC swallows the five
+bytes behind it. And the line endings are normalized for you: terminals
+disagree about whether a bracketed line break is `\r`, `\r\n` or `\n`, so
+Tuile settles on `\n` before the text reaches a component.
+
+`run_event_loop(bracketed_paste: false)` turns the mode off, the same way
+`capture_mouse: false` turns off mouse tracking. Then a paste is keystrokes
+again, with the ambiguity that implies — reach for it only if a terminal
+mishandles the mode.
+
 ## Where the cursor comes in — and where it doesn't
 
 A component signals cursor ownership through
@@ -188,28 +273,61 @@ needed. With dispatch resting on nothing but "did you return `true`," the
 proxy is gone, and a component's decision to consume a key is the only
 declaration in the system.
 
-## The status bar writes itself
+## Writing a status line
+
+Chapter 1 pointed out that Tuile draws no status bar. This is the chapter
+where you find out that's a decision about *ownership*, not an omission —
+and that most status lines don't need this chapter's machinery at all.
+
+A status line is a `Label` in your layout. That's the whole idea:
 
-You've seen the bottom row showing hints like `q quit` since chapter 1.
-It's driven by focus. Whenever focus changes, the screen rebuilds the
-status bar from two sources: the currently-relevant shortcuts, and the
-focused context's own advertised hint.
+```ruby
+status = Tuile::Component::Label.new
+status.text = "q #{screen.theme.hint("quit")}  Tab #{screen.theme.hint("Switch")}"
+
+root = Tuile::Component::Layout::Vertical.new
+root.add(main_ui, Tuile::Component::Layout::Expand[1])
+root.add(status, Tuile::Component::Layout::Fixed[1])
+```
+
+If the keys your app offers are the same wherever the user is, you are
+done — set the text once and never touch it again. `examples/file_commander.rb`
+is exactly this: Tab, Enter and Backspace work in both panes, so its row is
+a constant. Reaching for a focus callback there would be machinery computing
+a value that never changes.
 
-A component advertises its hint by overriding
-{Tuile::Component#keyboard_hint} to return a preformatted string
-(components build these with `theme.hint(...)` so the styling matches).
-The screen composes the bar differently depending on what's in front:
+Two details about the text itself. `theme.hint(...)` styles the descriptive
+half of a `key what` pair so hints look consistent (chapter 6), and it
+**bakes the color in** — so a label built from it rebuilds itself from
+`on_theme_changed` to follow a light/dark flip. And keys registered with
+{Tuile::Screen#register_global_shortcut} don't advertise themselves: the
+registry runs actions, it doesn't describe them, so a `^K menu` in your row
+is text you write next to the registration.
 
-- **Tiled (no popup):** `q quit`, then any global-shortcut hints, then the
-  active window's `keyboard_hint`.
-- **Popup open:** the over-popups global hints, then the popup's own hint
-  (a popup owns its `q Close` prefix).
+### When the row does depend on focus
+
+Some apps genuinely show different keys in different places — a window with
+a search mode, or a pane whose commands only apply to it. For those,
+{Tuile::Screen#on_focus_changed=} is the notification:
+
+```ruby
+screen.on_focus_changed = -> { status.text = hint_for(screen.focused) }
+```
 
-You don't assemble the bar yourself; you override `keyboard_hint` on the
-components that have shortcuts worth advertising, register global
-shortcuts with a `hint:`, and the composition happens on every focus
-change. The status bar is a *view* of the focus state, not a thing you
-maintain.
+It fires after every focus *change* — to and from `nil` included, and after
+the repair that runs when a popup closes. It's edge-triggered, so
+re-focusing what already has focus fires nothing and your callback can
+rebuild the string unconditionally. Two things it must tolerate: `focused`
+being `nil`, and firing during `screen.close`, which clears focus as it
+unmounts.
+
+What `hint_for` does is entirely yours — Tuile has no notion of a hint and
+no method for one, so there is no interface here to conform to.
+`examples/sampler.rb` names the focused component's class, which makes Tab
+traversal visible as you walk a pane. An app with per-window keys usually
+walks up the focus chain from `screen.focused` and takes the first answer,
+because that mirrors the direction a key bubbles — but that's an app's
+design decision, not a framework pattern.
 
 ---
 

data/book/06-theming.md

@@ -24,7 +24,7 @@ defaults for free.
 What Tuile *does* color is the small set of cues that signal
 interaction: the highlight behind the focused list row, the border of the
 active window, the resting "well" of a text field, the shortcut captions
-in the status bar. Those are the accents, and they are exactly the tokens
+in a status line you write. Those are the accents, and they are exactly the tokens
 a {Tuile::Theme} carries — `active_bg_color`, `active_border_color`,
 `input_bg_color`, `hint_color`. There is no global `bg` or `fg` token,
 and that absence is intentional: adding one would mean painting over the
@@ -170,6 +170,104 @@ theme. From your code's perspective a live appearance flip and a startup
 detection are the same thing arriving through the same channel — which is
 exactly the single-threaded-loop payoff chapter 4 promised.
 
+## Building on the terminal's own background
+
+Everything so far picks colors to sit *against* the background. Some
+designs want the opposite: a color derived *from* it. The borderless-pane
+idiom — LazyVim's editor-versus-explorer split is the one most people
+have seen — leaves the primary pane at the terminal's own background and
+tints the secondary panes a few percent off it. No borders, no boxes; the
+panes separate because one is very slightly lighter than the other.
+
+You cannot do that with a fixed color. A tint tuned against `#1e1e2e`
+looks like a deliberate panel against `#000000` and disappears entirely
+against `#282c34`. What the effect needs is the terminal's *actual*
+background, and Tuile has it: the OSC 11 reply carries the RGB, and
+{Tuile::Screen}`#background_color` hands it to you as a
+{Tuile::Color}.
+
+```ruby
+bg = Tuile::Screen.instance.background_color
+sidebar.bg_color =
+  bg ? Tuile::Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }) : FALLBACK_TINT
+```
+
+That `FALLBACK_TINT` is not defensive padding — it's the branch you
+should expect to hit. Plenty of terminals answer neither probe, and the
+`COLORFGBG` fallback reports a palette *index* with no RGB behind it, so
+`background_color` is nil for every one of them. The fixed near-neutral
+you would have shipped anyway becomes the fallback; the reported color is
+the upgrade for terminals that can support it.
+
+The value stays honest across an appearance flip, and doing so takes one
+more round trip than you might expect. The mode-2031 report says only
+"the OS is light now" — it carries no RGB — so when the screen sees one,
+it writes the OSC 11 query again, and the reply comes back through the
+key thread as another event. The new color therefore lands a frame after
+the new theme. When it does, Tuile fires
+{Tuile::Component}`#on_theme_changed` across the tree exactly as a theme
+swap does, on the reasoning that a tint derived from the background *is*
+a theme-derived color, and that hook is already where you rebuild those.
+So the same override handles both halves of a flip, and you don't need to
+know which one woke you.
+
+## Not every terminal can show what you computed
+
+There is a catch hiding in that last section, and it is worth seeing
+clearly because it applies to every color you *compute* rather than
+declare.
+
+A 24-bit color goes out as `\e[48;2;30;30;34m`. That sequence assumes the
+terminal on the other end understands 24-bit color — and plenty don't.
+A `TERM=xterm-256color` session understands only the 256-color palette; a
+Linux console understands sixteen colors; tmux without
+`terminal-features "*:RGB"` mangles or approximates whatever passes
+through it. When you *declared* your colors, this was somebody else's
+problem: you picked them by eye, in a terminal you were looking at, and
+if they came out wrong you picked different ones. A tint computed at
+runtime from the reported background has nobody to eyeball it.
+
+So Tuile detects what the terminal can show, and degrades on the way out.
+
+```ruby
+Tuile::Screen.instance.color_depth   # => :truecolor, :palette256, or :ansi16
+```
+
+Detection reads the environment — `COLORTERM`, then `TERM` — and never
+asks the terminal anything, so unlike the background probe there is no
+timing to respect and no staleness to worry about: the depth is settled
+at construction and stays put. Terminals do lie, in both directions, and
+`COLORTERM` in particular tends not to survive ssh or tmux. Two things
+make that survivable. Misdetection lands *conservatively* — a truecolor
+tmux advertising only `tmux-256color` reads as `:palette256`, which
+renders coarser but never garbled — and `TUILE_COLOR_DEPTH` overrides the
+detection outright, which is what you reach for when a terminal reports
+itself wrong.
+
+The part that matters for your code is that **you don't have to do
+anything about it**. The degradation happens inside
+{Tuile::Buffer}`#flush`, at the moment cells become bytes: every color is
+mapped to the nearest one the terminal can actually show, and the RGB
+you computed is what stays in the component. Paint `Color.rgb(30, 30, 34)`
+on a 256-color terminal and the wire carries palette cell 234; read the
+component back and it still holds your RGB. Nothing you store is ever
+quantized — which is the point, because a stored palette cell has
+forgotten what it was derived from, and the next tint you compute from it
+would compound the error.
+
+That leaves one thing worth doing deliberately, and only sometimes. If
+you want to know what a color will *become* — checking that a computed
+tint still contrasts with the background after both round to the same
+coarse palette — ask it:
+
+```ruby
+tint.quantize(Tuile::Screen.instance.color_depth)   # => the color the terminal will show
+```
+
+This is a question, not a step you owe the framework. It returns the
+receiver unchanged whenever the depth can show the color as-is, so it is
+also the cheapest way to ask "would this degrade at all?".
+
 ## Theming an app durably
 
 Detection picks between *Tuile's* two themes. To give your app its own
@@ -250,7 +348,10 @@ integer) that {Tuile::Color}.coerce accepts elsewhere. A theme is
 declared once per app, so the extra verbosity buys self-documentation —
 `Color.palette(130)` says "palette index," and the named constant
 `Color::DARK_ORANGE3` says even more, where a bare `130` at the
-declaration site says nothing.
+declaration site says nothing. All 256 xterm palette names are there as
+constants — `Color::DODGER_BLUE1`, `Color::GREY37` — and
+`Color::PALETTE_NAMES` is the enumerable map behind them if you'd rather
+browse than guess.
 
 ## When the theme changes under your content