tuile 0.9.0 → 0.11.0

data/README.md

@@ -49,6 +49,12 @@ gem "tuile", git: "https://github.com/mvysny/tuile.git"
 
 Tuile requires Ruby 3.3+.
 
+One component — `Component::BigDecimalField` — additionally needs the
+`bigdecimal` gem, which Tuile deliberately does *not* depend on (it has been a
+bundled gem since Ruby 3.4, so Bundler no longer puts it on the load path for
+free). Add `gem "bigdecimal"` to your Gemfile if you use that field; nothing
+else in Tuile loads it.
+
 ## Documentation
 
 - **[The Tuile guide](book/README.md)** teaches Tuile cover to cover — the
@@ -98,9 +104,8 @@ Shift+Tab move focus between the list and the demo's widgets.
 ### Component tree
 
 Everything on screen is a `Tuile::Component`. Components have a `parent`,
-`children`, a `rect` (absolute position), an `active?` flag (true for every
-component on the focus chain root → focused), and an optional `key_shortcut`
-that the framework will route keys to from anywhere in the tree.
+`children`, a `rect` (absolute position), and an `active?` flag (true for
+every component on the focus chain root → focused).
 
 A single `Tuile::Screen` (process singleton) owns the tree. Under it sits a
 structural `ScreenPane` with three slots: tiled `content` (your app's main
@@ -194,11 +199,13 @@ mechanism that handles it wins:
    screen.unregister_global_shortcut(Tuile::Keys::CTRL_L)
    ```
 
-   Only unprintable keys are accepted (control characters, ESC, BACKSPACE,
-   arrows, F-keys); printable keys raise so they can't hijack typing into
-   a `TextField`. By default, the shortcut is suppressed while any popup
-   is open and the popup receives the key; pass `over_popups: true` to
-   pre-empt the popup.
+   This registry sits above the component tree and nothing suppresses it,
+   so it only accepts keys no widget can need: printable keys raise (they'd
+   hijack typing), as do Tab/Shift+Tab and `Screen::EDITING_KEYS` (Enter,
+   Backspace, Delete, the arrows). Control characters, ESC, `PgUp`/`PgDn`
+   and F-keys are yours. By default, the shortcut is suppressed while any
+   popup is open and the popup receives the key; pass `over_popups: true`
+   to pre-empt the popup.
 
    Pass `hint:` to surface the shortcut in the status bar. It's a
    preformatted string the caller fully owns (color it however the rest
@@ -207,23 +214,10 @@ mechanism that handles it wins:
    `over_popups: true` hints show up, prepended before the popup's
    `q Close`. Omit `hint:` to leave the shortcut silent in the status bar.
 
-3. **`Component#key_shortcut`** — a declarative hotkey attached to a
-   component. The framework walks the focused component's subtree for a
-   match and focuses the winner. Good fit for "press F to focus the filter
-   field" or one-key tab pickers. The lookup is suppressed while the
-   focused component owns the hardware cursor (e.g. a `TextField` the user
-   is typing into) so editing isn't interrupted:
-
-   ```ruby
-   filter_field.key_shortcut = "f"
-   ```
-
-4. **`Component#handle_key`** — override this on your own component when
+3. **`Component#handle_key`** — override this on your own component when
    it needs to react to keys directly (a list reacting to arrows, a custom
    widget handling Enter, …). Return `true` to mark the key handled,
-   `false` to let the dispatcher keep walking. Call `super` to keep the
-   default `key_shortcut` subtree lookup; suppress it only when you
-   deliberately want this component to swallow everything:
+   `false` to let the key keep travelling:
 
    ```ruby
    class Toggle < Tuile::Component
@@ -233,7 +227,26 @@ mechanism that handles it wins:
          invalidate
          true
        else
-         super
+         false
+       end
+     end
+   end
+   ```
+
+   The key goes to the focused component first, then **bubbles up its
+   ancestors** to the scope root (the topmost popup, or the tiled content).
+   That makes an ancestor the right home for scope-wide keys — a form's
+   default button, or one-key jumps between panes — and it needs no special
+   protection, because a focused `TextField` consumes the key before the
+   ancestor ever sees it:
+
+   ```ruby
+   class AppLayout < Tuile::Component::Layout::Absolute
+     def handle_key(key)
+       case key
+       when "1" then @files.focus; true
+       when "2" then @log.focus; true
+       else false
        end
      end
    end

data/book/03-layout.md

@@ -125,6 +125,15 @@ complex TUIs — tmux, neovim's splits, k9s, lazygit, htop — are all
 them needs flex grow/shrink/wrap/basis or a constraint solve. The
 hardest real terminal UIs already live comfortably inside "simple."
 
+Be precise about what that validates, though: it's TUI *app architecture*,
+not TUI *framework feature lists*. Several terminal frameworks do ship a
+full engine — Textual has CSS, Ink embeds Yoga (the flexbox engine React
+Native uses), ratatui runs a real Cassowary solver. The reason isn't that
+terminals need one; it's that those frameworks never hand you a rectangle,
+so an engine is the only way their users can lay anything out. Tuile hands
+you coordinates, which is what makes richer layout *optional* here —
+available where it helps, declinable everywhere else.
+
 It's stronger than "simple happens to work," though. Importing a CSS-like
 system would be *actively worse* on a terminal, for three concrete
 reasons:
@@ -204,6 +213,146 @@ That's the whole "responsive" story: plain Ruby, recomputed on a
 discrete resize event. No breakpoint DSL, no media queries — just the
 arithmetic you'd write anyway.
 
+## Stacks without the arithmetic: `Vertical` and `Horizontal`
+
+`Absolute` is the right tool for genuinely two-dimensional geometry, and
+tedious for the most common shape in any app: a stack. So Tuile ships two
+*box* layouts that do that arithmetic for you. You declare what extent each
+child should get, and the box hands down rectangles through the very same
+`rect=`:
+
+```ruby
+form = Tuile::Component::Layout::Vertical.new(spacing: 1)
+form.add(prompt, Tuile::Component::Layout::Fixed[3])    # 3 rows
+form.add(field,  Tuile::Component::Layout::Fixed[1])    # 1 row
+form.add(log,    Tuile::Component::Layout::Expand[1])   # …all that's left
+```
+
+`Horizontal` is the same with the axes swapped — the constraint is a width,
+and `Expand` claims the rest of the row:
+
+```ruby
+split = Tuile::Component::Layout::Horizontal.new
+split.add(sidebar, Tuile::Component::Layout::Fixed[30])
+split.add(main,    Tuile::Component::Layout::Expand[1])
+```
+
+Inside a subclass the constraint names need no prefix, since they live on
+`Layout`, an ancestor:
+
+```ruby
+class LoginForm < Tuile::Component::Layout::Vertical
+  def initialize
+    super(spacing: 1, padding: Insets[top: 1])
+    add(@user = Tuile::Component::TextField.new, Fixed[1], cross: Fixed[30])
+    add(@log  = Tuile::Component::TextView.new,  Expand[1])
+  end
+end
+```
+
+### The three constraints
+
+- **`Fixed[n]`** — exactly `n` cells, clamped to what's still unassigned.
+- **`Percent[n]`** — `n`% of the space *available*, measured after padding
+  and the gaps between children come off. So two `Percent[50]` children fit
+  exactly instead of overflowing by the gap between them.
+- **`Expand[weight]`** — a share of whatever is left once the `Fixed` and
+  `Percent` children have taken theirs, split in proportion to the weights.
+
+That's the entire vocabulary, and the omission is the point: **there is no
+`Auto`.** Nothing asks a child how big it would like to be. This is the same
+rule as the rest of the chapter, wearing a friendlier face.
+
+Two more knobs, both on the box rather than on each child: `spacing:` (blank
+cells between adjacent children) and `padding:` (an inset from the box's own
+rect — `Insets[top: 1, left: 2]`, or a plain integer for all four edges).
+
+### The cross axis, and alignment
+
+Each child also gets a `cross:` constraint — its width in a `Vertical`, its
+height in a `Horizontal`. It defaults to `Percent[100]`, so children fill the
+box across the axis, which is usually what you want. Narrow one when it isn't:
+
+```ruby
+form.add(field, Fixed[1], cross: Fixed[30])                  # 30 columns
+form.add(title, Fixed[1], cross: Percent[50], align: :center)
+```
+
+`align:` is `:start`, `:center` or `:end` — axis-agnostic on purpose, since
+`:start` means the left edge in a `Vertical` and the top edge in a
+`Horizontal`. It does something only when the child is narrower than the
+space available.
+
+Alignment might look like it contradicts the top-down rule — surely centering
+needs to know how wide the child is? It doesn't. It needs *a* width, and the
+`cross:` constraint is where that width came from. Nothing gets measured.
+(`Expand` is main-axis only for a related reason: across the axis a child has
+no siblings to compete with, so a weight would have nothing to mean. Passing
+one as `cross:` raises.)
+
+### Packing, starving, and remainders
+
+Three behaviours worth knowing, because they are what you get *instead of* a
+solver:
+
+**Children pack from the start edge.** With no `Expand` among them the slack
+is simply left at the end — there's no invisible filler to add, the way
+Swing's `BoxLayout` needs glue.
+
+**Over-subscription starves rather than raising.** If the children ask for
+more than there is, they're satisfied in declaration order and whoever is
+left over gets an empty rect — which, as chapter 2 established, paints
+nothing. A pane too short for its content degrades quietly instead of
+throwing or spilling outside its rect.
+
+**A remainder goes to the earliest `Expand` children, one cell each.** Five
+equal `Expand`s in 12 rows get `3, 3, 2, 2, 2` — never `2, 2, 2, 2, 4`, which
+is what "give the leftover to the last one" produces. On a character grid a
+doubled pane is plainly visible, so spare cells are spread rather than dumped.
+One wrinkle, since this chapter showed you the hand-written version first: the
+two-pane `Absolute` example above gives the odd column to the *right* pane,
+while two `Expand[1]` children give it to the *left*. Both are deterministic;
+they're just different code.
+
+### Varying the gap: nest, don't configure
+
+`spacing` belongs to the box rather than to individual children, deliberately.
+A gap sits *between* two children, so "whose gap is it?" has no good answer —
+and both possible conventions confuse readers.
+
+When you want tighter grouping, nest a box. A `spacing: 0` stack inside a
+`spacing: 1` stack keeps two rows flush while the rest of the form breathes:
+
+```ruby
+pair = Tuile::Component::Layout::Vertical.new           # spacing: 0
+pair.add(bar,     Fixed[1])
+pair.add(caption, Fixed[1])                             # flush under the bar
+
+form = Tuile::Component::Layout::Vertical.new(spacing: 1)
+form.add(prompt, Fixed[4])
+form.add(pair,   Fixed[2])                              # blank row around the pair
+```
+
+That *states* the grouping instead of faking it with a per-child gap — boxes
+within boxes, which is how the rest of Tuile composes anyway.
+
+### When to stay with `Absolute`
+
+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
+```
+
+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.
+
 ## Geometry: `Point`, `Size`, `Rect`
 
 The values you compute with are three small frozen types
@@ -369,11 +518,7 @@ own code and set the size top-down. Keep measurement opt-in and
 caller-side; the moment the framework starts consulting children for
 sizes automatically, it's on the road back to the constraint solver.
 
-And if you find yourself building many dynamic, user-draggable splits by
-hand and wishing for a `Layout.vertical([Length(3), Fill(1), …])`
-convenience — that's a known, *deliberately deferred* addition. It would
-be pure sugar: a rect producer running a small greedy 1-D pass and
-feeding results to the very same `rect=` setter you already use, with no
-change to the foundation. Absolute-first is the base; a descriptive
-split layer is an optional convenience on top, added if and when the
-convenience pays for itself.
+Note that the box layouts above are not an exception to any of this. They
+compute rectangles *for* you, but they compute them from constraints you
+supplied, and they hand them down through the same `rect=`. No child is ever
+consulted.

data/book/04-event-loop.md

@@ -172,6 +172,92 @@ Reach for `tick` when you're pacing work ("check every two seconds"),
 `tick_fps` when you're driving an animation ("spin at 8 fps"). Same
 machinery underneath; pick the unit that matches how you're thinking.
 
+## Owning a resource for as long as you're on screen
+
+Both examples above end with a loose thread: *who calls `cancel`, and
+when?* If the spinner lives in a popup the user can close, then someone
+has to remember to stop the ticker at exactly the moment the popup goes
+away — and "someone remembers" is how you end up with a timer firing
+against a component nobody can see, forever.
+
+The component itself is the only thing that knows. So it gets told:
+
+```ruby
+class Spinner < Tuile::Component::Label
+  FRAMES = %w[/ - \\ |]
+
+  protected
+
+  def on_attached
+    @ticker = screen.event_queue.tick_fps(8) { |n| self.text = FRAMES[n % FRAMES.size] }
+  end
+
+  def on_detached
+    @ticker&.cancel
+    @ticker = nil
+  end
+end
+```
+
+`on_attached` fires the moment this component's tree is mounted on the
+screen; `on_detached` fires the moment it's unmounted. Add the spinner to a
+popup and it starts; close the popup and it stops. Nothing at the call site
+remembers anything — `popup.close` is the whole teardown.
+
+The contract is a mirror: **`on_attached` starts what `on_detached` stops.**
+Keep both cheap and idempotent, because a component *moved* from one parent
+to another gets `on_detached` and then `on_attached` — between those two
+calls it genuinely is off the screen, possibly for a long time, so stopping
+and restarting is the honest thing to do. And whatever you acquire in
+`on_attached` you must release in `on_detached`, because nothing else will.
+
+This generalizes well beyond tickers, and the interesting case is
+subscriptions. A component may depend on a service, but a service must never
+reach back up into the UI — so when data has to flow *upward*, the component
+subscribes and the service emits blind. That subscription is a resource with
+exactly the lifetime the hooks describe:
+
+```ruby
+class BuildStatus < Tuile::Component::Label
+  def initialize(service)
+    super()
+    @service = service
+  end
+
+  protected
+
+  def on_attached
+    @subscription = @service.on_change { |s| screen.event_queue.submit { self.text = s } }
+  end
+
+  def on_detached
+    @subscription&.unsubscribe
+    @subscription = nil
+  end
+end
+```
+
+Note the `submit` inside the listener — the service emits from whatever
+thread it likes, and marshalling onto the UI thread is the listener's job,
+exactly as earlier in this chapter. What the hooks add is the other half:
+the subscription exists for precisely as long as the component is on
+screen, and no view-closing code path has to know that the subscription
+exists at all.
+
+`screen.close` counts as unmounting, so the `screen.close` at the end of
+your `main` gives every component still on screen its `on_detached` — the
+tickers stop, the subscriptions come off, and you didn't write any of that
+teardown. What *doesn't* fire is a process that exits without closing the
+screen at all: these are lifecycle hooks, not destructors, and Tuile
+installs no `at_exit`. If your `on_detached` does something that matters
+beyond the process — flushing a file, say — close the screen deliberately
+rather than relying on exit.
+
+The other thing the hooks are not is a place to do layout. When
+`on_attached` runs, your parent hasn't assigned your `rect` yet. If you need
+to paint, invalidate here and do the work in `repaint`, which is what
+chapter 2 was about anyway.
+
 ## Resize is just another event
 
 A terminal resize could have been handled off the `SIGWINCH` signal

data/book/05-focus.md

@@ -55,8 +55,8 @@ Shift+Tab land on this component while cycling. It's also `false` by
 default, and it *implies* focusable — a tab stop is always a valid focus
 target, but not every focus target is a tab stop. The distinction matters
 for containers: a {Tuile::Component::Window} is focusable (so a click on
-its chrome, or a `key_shortcut`, can focus it) but is *not* a tab stop
-(Tab should skip the frame and stop on the actual inputs inside it). So:
+its chrome can focus it) but is *not* a tab stop (Tab should skip the frame
+and stop on the actual inputs inside it). So:
 
 - **Label** — neither. Decoration.
 - **Window, Popup** — focusable, not a tab stop. Clickable chrome,
@@ -80,8 +80,8 @@ earlier.
 **1. Tab and Shift+Tab — focus navigation, first, always.** These are
 intercepted before anything else and drive the cycling described above.
 They're taken off the top deliberately: a focused text field swallows
-almost every printable key (step 3 explains how), and if Tab weren't
-reserved here, a field would trap it too and you could never Tab out.
+almost every printable key, and if Tab weren't reserved here, a field would
+trap it too and you could never Tab out.
 
 **2. Global shortcuts.** App-level shortcuts registered with
 {Tuile::Screen#register_global_shortcut} fire next, before any component
@@ -95,32 +95,24 @@ screen.register_global_shortcut(Tuile::Keys::CTRL_L,
 end
 ```
 
-Only *unprintable* keys are allowed here (control keys, function keys,
-escape sequences). Printable keys are rejected at registration time,
-because a global binding on `a` would hijack someone typing `a` into a
-text field — that's what the per-component `key_shortcut` in step 3 is
-for. A shortcut can opt to fire even while a modal popup is open
-(`over_popups: true`); by default it's suppressed while a popup is up, so
-the popup stays modal.
-
-**3. A `key_shortcut` anywhere in the focused scope.** Every component can
-carry a {Tuile::Component#key_shortcut} — a single key that, when pressed,
-*jumps focus to that component*. The screen searches the current modal
-scope's subtree for a component whose shortcut matches; if it finds one,
-it focuses it and consumes the key. A window advertises its shortcut in
-its caption (`[f]-Files`), so a whole pane can be reachable with one key.
-
-But this search is **suppressed while a text widget is mid-edit** — and
-that suppression is the subtle, important part, so it gets its own
-section below.
-
-**4. `handle_key` on the focus chain.** Finally, if nothing above claimed
-the key, it's delivered to the focused component's
-{Tuile::Component#handle_key}, and if that returns `false` (didn't handle
-it), it bubbles up the ancestor chain — the focused component, then its
-parent, then *its* parent — until someone returns `true` or the scope
-root is reached. This is how a list handles arrow keys itself but lets an
-unhandled key rise to the window around it.
+This registry is the only keyboard mechanism that sits *above* the
+component tree, and nothing suppresses it — which is exactly why it's
+picky about what it accepts. Printable keys are rejected at registration
+time, because a global binding on `a` would hijack someone typing `a` into
+a text field. So are Tab and Shift+Tab (step 1 already took them), and so
+are `Screen::EDITING_KEYS` — Enter, Backspace, Delete and the arrows —
+because every editable widget needs those, and a global binding would
+break text entry app-wide with no way for a field to defend itself. What's
+left is yours: control keys, ESC, PgUp/PgDn, function keys. A shortcut can
+opt to fire even while a modal popup is open (`over_popups: true`); by
+default it's suppressed while a popup is up, so the popup stays modal.
+
+**3. `handle_key`, delivered to focus and bubbling up.** Everything else
+goes to the focused component's {Tuile::Component#handle_key}, and if that
+returns `false` (didn't handle it), the key bubbles up the ancestor chain —
+the focused component, then its parent, then *its* parent — until someone
+returns `true` or the scope root is reached. This is how a list handles
+arrow keys itself but lets an unhandled key rise to the window around it.
 
 A component only ever receives a key when it's on the focus chain, so
 `handle_key` implementations act on the key alone — they never need to
@@ -128,32 +120,73 @@ check their own `active?` state. And if focus is `nil`, or sits outside
 the current modal scope, delivery reaches no one: that's precisely what
 makes an open modal popup modal.
 
-## Why a text field can just type
+Three rungs, and that's the whole ladder. Tuile used to have a fourth — a
+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.
 
-Here's the problem the cursor-ownership rule solves. Suppose a window has
-a search field, and elsewhere in the same window a list has `key_shortcut
-= "d"` for "delete." You click into the field and type "add item." Should
-the "d" in "add" trigger delete?
+## Scope-wide keys live on an ancestor
 
-Obviously not — and step 3 is where it would go wrong, because "d" *is* a
-registered `key_shortcut` in the scope. The rule that saves you: the
-`key_shortcut` search in step 3 is skipped whenever a component **owns
-the hardware cursor**.
+Two things every app wants: `1`/`2`/`3` to jump between panes, and Enter to
+submit a form. Neither is a *global* action — each belongs to one region of
+the tree — and neither needs machinery, because bubbling already has the
+right shape. **Put the key on the ancestor that owns the region.**
+
+```ruby
+class AppLayout < Tuile::Component::Layout::Absolute
+  def handle_key(key)
+    case key
+    when "1" then @files.focus; true
+    when "2" then @log.focus; true
+    else false
+    end
+  end
+end
+```
+
+Now think about what happens when the user clicks into a search field
+inside `@files` and types "add item". Should the `1` in a typed "item 1"
+jump panes? Obviously not — and it doesn't, for a reason that requires no
+special case at all: **the focused field consumes the key at step 3 and
+returns `true`, so the layout never sees it.** An ancestor only hears the
+keys its descendants declined. That's the whole protection.
+
+The same mechanism gives you a form's default button, one form per popup:
+
+| focused widget | Enter | outcome |
+|---|---|---|
+| `TextArea` | consumes it (newline) | the form never sees it |
+| `TextField` with an `on_enter` | consumes it | no double-submit |
+| `TextField` without one | declines | bubbles up → submit |
+| `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 |
+
+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
+is also why registering Enter globally is refused in step 2: the registry
+would take it away from all of them at once.
+
+The one thing this shape asks of you is that the *parent* holds the key →
+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.
+
+## Where the cursor comes in — and where it doesn't
 
 A component signals cursor ownership through
 {Tuile::Component#cursor_position} — return a `Point` and the terminal
-cursor is shown there; return `nil` (the default) and there's no cursor.
-A {Tuile::Component::TextField} being edited returns its caret position,
-which is non-`nil`, so the screen knows a text widget is mid-edit and
-suppresses shortcut capture. The "d" flows straight through step 3 to
-step 4, where the focused field's `handle_key` inserts it. Tab (step 1)
-still works, because it's reserved above all this — so you can always Tab
-out of the field, at which point the cursor goes away and shortcuts light
-back up.
-
-That's the entire mechanism: printable keys belong to whoever owns the
-cursor, and owning the cursor mutes the sibling shortcuts that would
-otherwise pick them off.
+cursor is shown there; return `nil` (the default) and there's no cursor. A
+{Tuile::Component::TextField} being edited returns its caret position, so
+the caret you see blinking is the focused component's answer to that one
+question.
+
+That's all it does. It positions the hardware cursor; it does not route
+keys. Tuile briefly used it as a proxy for "this widget is in text-entry
+mode, don't steal its printable keys" — a signal the deleted fourth rung
+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
 

data/book/06-theming.md

@@ -38,6 +38,55 @@ colors plus an app-extensible `custom` hash — and that's all. Two are
 built in: {Tuile::Theme::DARK}, the colors Tuile has always used, and
 {Tuile::Theme::LIGHT}, counterparts legible on a pale background.
 
+## Backgrounds are opt-in
+
+The stance above — paint accents, leave the rest to the terminal — is how
+the *framework* paints. But sometimes your *app* wants a real background:
+an overlay panel, a slash-command menu, a dropdown that has to read as one
+solid tinted block floating over the content beneath it — filler rows
+included, not a ragged half-shaded box. That is {Tuile::Component#bg_color}.
+
+Set it on a component and that component paints a background behind
+everything it draws; leave it unset (the default) and you get the
+terminal default, exactly as before. The useful part is that it
+**inherits**: set `bg_color` once on a container — a
+{Tuile::Component::Popup}, a layout, a window — and every descendant that
+hasn't set its own picks it up. You tint the panel, and the labels and
+lists inside come out on the same tint without being told individually.
+
+That inheritance has to be *manufactured*, because a terminal has no
+transparency: every cell holds exactly one background, and painting a
+glyph replaces the whole cell (chapter 2's opaque grid). So Tuile resolves
+the effective background at paint time by walking up to the nearest
+ancestor that set a `bg_color` — the same read-at-paint discipline the
+theme uses, and for the same reason: change a container's background and
+its subtree is invalidated and simply repaints in the new color. The
+terminal default is just the root of that chain, which is why an unset
+`bg_color` everywhere behaves exactly like it always has.
+
+A widget with a background of its *own* keeps it. A text field paints its
+well across its whole rect, so dropping one into a tinted panel shows the
+field in its own well, not the panel tint — the explicit background wins
+over the inherited one, the terminal equivalent of a CSS element that sets
+its own `background`.
+
+`bg_color` takes either a concrete {Tuile::Color} or a *live theme
+reference* — `Theme.ref(:panel_bg)` — that names one of your app's custom
+tokens and re-resolves it against the current theme on every paint. The
+reference is the ergonomic path: assign it once and the panel follows
+light and dark on its own, with no `on_theme_changed` handler. That works
+precisely because a background — unlike the baked-in colors of your
+*content* (below) — is resolved *live* at paint, exactly like the
+framework's own accents; `bg_color` is a single value read late, so
+late-binding it to a token costs nothing. It is the one place an app color
+tracks the theme without the hook.
+
+A reference reaches your *custom* tokens only, never a framework-imposed
+global, so the "no global background token" line holds either way: the
+framework still paints no background of its own. You opt in per
+component — a concrete `Color` when you want it fixed, a `Theme.ref` when
+you want it to follow the scheme.
+
 ## Read at paint time, never cached
 
 There is one rule about *using* the theme that everything else depends
@@ -207,7 +256,10 @@ declaration site says nothing.
 
 The built-in components restyle for free because they read the theme at
 paint time. Your *content* can't always do that — and this is the one
-theming responsibility that lands on the app.
+theming responsibility that lands on the app. (A *background* is the
+exception: `bg_color = Theme.ref(:token)` tracks the theme live with no
+handler, because it's resolved at paint — see "Backgrounds are opt-in"
+above. The hook below is for baked-in *content* colors.)
 
 The problem: when you build a {Tuile::StyledString} for a
 {Tuile::Component::Label} or a {Tuile::Component::List} row, its colors