tuile 0.8.0 → 0.9.0

data/book/05-focus.md

@@ -0,0 +1,188 @@
+# 5. Focus and the keyboard
+
+Chapter 4 ended on a promise: because everything runs on one thread, this
+chapter can describe keyboard handling without a single caveat about
+concurrency. When a key is dispatched, nothing else is happening — no
+repaint mid-flight, no background thread mutating the tree. So the only
+question left is the interesting one: given a keystroke and a tree of
+components, *who gets it?*
+
+The answer has two halves. **Focus** decides which component is the
+current target. **Dispatch** decides the order in which components are
+offered a key — because focus is the common case, not the only case.
+
+## The focus chain
+
+At any moment, at most one component is **focused**. You set it directly:
+
+```ruby
+screen.focused = some_component     # or: some_component.focus
+screen.focused = nil                # nothing focused
+```
+
+Focus is not just a flag on one component, though — it's a *chain*.
+Setting focus walks from the target up through its parents to the root,
+and marks every component on that path **active**. Everything not on the
+path is deactivated. So if you focus a text field inside a window inside
+the content area, the field, the window, and the content are all active;
+their siblings are not.
+
+That active chain is what components paint against. A {Tuile::Component::Window}
+draws its border in the accent color when it's active and a plain color
+when it isn't — which is why, in a multi-window layout, exactly the
+window containing the focused widget lights up. "Active" means "on the
+path to what has focus," and it falls out of one assignment.
+
+## Two gates: `focusable?` and `tab_stop?`
+
+Not everything can be focused, and not everything focusable participates
+in every way of *getting* focused. Two predicates draw those lines, and
+they're independent on purpose.
+
+{Tuile::Component#focusable?} gates whether a component can become a focus
+target *at all*. It's `false` by default — a {Tuile::Component::Label} is
+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
+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.
+
+{Tuile::Component#tab_stop?} gates something narrower: whether Tab and
+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:
+
+- **Label** — neither. Decoration.
+- **Window, Popup** — focusable, not a tab stop. Clickable chrome,
+  skipped by Tab.
+- **TextField, List, Button** — both. Real inputs you can click *and*
+  Tab to.
+
+Tab cycling is confined to a **modal scope**: the topmost modal popup if
+one is open, otherwise the tiled content. Tab collects the tab stops in
+that scope in tree order and advances by one, wrapping around; Shift+Tab
+walks backward. This is what keeps Tab from escaping an open dialog — the
+scope is the dialog, so cycling stays inside it.
+
+## The dispatch order
+
+When a key arrives, it's offered to the tree in a fixed order, and the
+first handler to claim it wins. Understanding this order is the whole
+game, because a key you expected one component to get can be intercepted
+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.
+
+**2. Global shortcuts.** App-level shortcuts registered with
+{Tuile::Screen#register_global_shortcut} fire next, before any component
+sees the key. These are for app-wide actions — "Ctrl+L opens the log,"
+"F1 shows help" — that should work regardless of what's focused:
+
+```ruby
+screen.register_global_shortcut(Tuile::Keys::CTRL_L,
+                                hint: "^L #{screen.theme.hint("log")}") do
+  log_popup.open
+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.
+
+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
+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
+
+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?
+
+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**.
+
+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.
+
+## The status bar writes itself
+
+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.
+
+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:
+
+- **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).
+
+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.
+
+---
+
+Focus and dispatch are the last piece of the runtime. You now have the
+whole loop: build a tree (chapter 1), it repaints without flicker
+(chapter 2), sized top-down (chapter 3), driven by a single-threaded
+event loop (chapter 4), with keys routed through focus (this chapter).
+Chapter 6 adds the last cross-cutting concern — color — and then chapters
+7 and 8 turn from *how the framework works* to *what you build with it*.

data/book/06-theming.md

@@ -0,0 +1,250 @@
+# 6. Theming
+
+Every chapter so far has been about *structure* — the tree, the repaint,
+the loop, focus. This one is about a single presentational concern that
+cuts across all of them: color. It's the last cross-cutting piece of the
+runtime, and it's small, because Tuile takes a deliberately narrow view
+of what a "theme" is. A theme in Tuile is not a stylesheet. It does not
+describe how your app looks. It describes the handful of *accents* the
+framework itself paints — and nothing else.
+
+That restraint is the whole design. Understand why the theme is small
+and you understand theming.
+
+## The theme colors only the accents
+
+Look at any Tuile screen and most of what you see is the terminal's own
+colors: the default foreground text on the default background. A label's
+text, a window's interior, the body of a list — none of that is themed.
+It inherits whatever the user's terminal is set to, which already matches
+their preferences perfectly. Tuile writes no background fill and no
+foreground color for those cells, so they come out in the terminal's
+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
+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
+terminal's defaults everywhere, which is precisely the thing that makes a
+TUI look wrong on someone else's color scheme. The theme touches only
+what the framework must color to be legible, and leaves the rest to the
+terminal.
+
+So a {Tuile::Theme} is a frozen value type — a `Data.define` of four
+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.
+
+## Read at paint time, never cached
+
+There is one rule about *using* the theme that everything else depends
+on, and it's stated as an invariant in AGENTS.md because breaking it
+breaks live theme switching: **a component reads `screen.theme` at paint
+time, inside `repaint`, and never stores a theme color in an ivar.**
+
+The reason is the repaint model from chapter 2. When the theme changes,
+Tuile does not hunt down every component and tell it which colors to
+update. It does the crude, correct thing: it invalidates the entire tree
+and lets the normal repaint redraw everything. On that repaint each
+component asks `screen.theme` for its accents afresh — so it simply comes
+out in the new colors, with no per-component update logic anywhere. A
+component that cached `theme.active_bg_color` in its constructor would
+keep painting the old color after a switch, an island of stale palette in
+an otherwise-restyled screen. Read it every time; the lookup is a hash
+access, and the repaint that follows a theme change was going to redraw
+you regardless.
+
+This is why the built-in components need no theme-change handling at all.
+They read at paint time, the tree is invalidated, they repaint in the new
+colors. Done.
+
+## Two ways to apply a token
+
+When a component has a themed color in hand, it applies it in one of two
+ways, and which one depends on the text.
+
+For plain chrome — a border string, a status-bar hint — the theme's
+**rendering helpers** wrap the text in the token's SGR color and a reset:
+`theme.active_bg("[ Ok ]")`, `theme.hint("quit")`. The helper picks the
+right channel for the token's role (a `*_bg` token wraps as a background,
+a hint as a foreground) and passes the content through verbatim, so the
+string may already contain other escape sequences — which is how
+{Tuile::Component::Window} feeds its whole border line, cursor moves and
+all, through `active_border`.
+
+But chrome text is flat. Content is not. A list row or a label may be a
+{Tuile::StyledString} with its own per-span colors, and wrapping that in
+one blunt SGR color would flatten every span to a single hue. For those,
+the theme exposes the raw color as a `*_color` reader
+(`theme.active_bg_color`) and you hand it to the StyledString, which
+composites it *underneath* the existing spans — {Tuile::Component::List}
+highlights its cursor row with `base.with_bg(theme.active_bg_color)`,
+preserving whatever foreground colors the row already carried. The rule
+of thumb: **plain chrome text → helper; structured text → `*_color`
+reader plus StyledString.**
+
+## Following the terminal, automatically
+
+An app never has to ask which theme to use. Tuile picks one by detecting
+whether the terminal background is light or dark, through
+{Tuile::TerminalBackground}.detect — two mechanisms in order of
+reliability. First an **OSC 11 query**: Tuile writes an escape sequence
+asking the terminal for its background color, and a modern terminal
+replies with the RGB, whose luminance decides light versus dark.
+Terminals that don't understand the query simply never answer, so the
+read is bounded by a short timeout and falls through to the second
+mechanism, the `COLORFGBG` environment variable that a few terminals
+export. If both are inconclusive, Tuile assumes dark.
+
+The timing of that detection is subtle enough to be a design constraint.
+The OSC 11 *reply arrives on stdin* — the same stream the key thread will
+own once the event loop is running. If detection ran after the loop
+started, those reply bytes would land in the key thread and be consumed
+as a garbage keystroke. So detection must happen *before* stdin is
+claimed, which is why {Tuile::Screen} runs it in its constructor, seeding
+`theme` before your app has built a single component. This is not an
+implementation detail you can relocate — it's why the constructor, not
+some later `setup` call, is where the scheme is decided.
+
+Detection at startup handles the common case. But a user can also flip
+their OS between light and dark *while your app is running*, and Tuile
+follows that too, on terminals that support **mode 2031**. The event loop
+enables the mode on startup; the terminal then pushes a small report
+whenever the OS appearance changes; the key thread recognizes that report
+(it's a private-mode CSI sequence, longer than an ordinary key, so it's
+drained specially) and turns it into an {Tuile::EventQueue::ColorSchemeEvent};
+and the loop, receiving that event like any other, re-picks the matching
+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.
+
+## Theming an app durably
+
+Detection picks between *Tuile's* two themes. To give your app its own
+colors, you supply your own — and here the distinction between a
+transient override and a durable definition matters, because it's easy to
+reach for the wrong one.
+
+You *can* assign `screen.theme = ...` directly, and it works: the whole
+UI restyles immediately. But it's a **transient override**. The next time
+the OS appearance flips, Tuile re-picks from its theme *definition* and
+replaces whatever you set. A bare `theme=` is the right tool for a
+one-shot experiment, not for how your app looks.
+
+The durable tool is a {Tuile::ThemeDef} — a pair of themes, one for dark
+backgrounds and one for light — assigned once to `screen.theme_def=`.
+Now Tuile picks the matching member at startup *and* re-picks from your
+pair on every appearance flip, so your app stays your app's colors
+through a light/dark toggle. That's the durable path: define the pair,
+assign it once, forget about it.
+
+The pair is required to be a *pair* for a reason. A {Tuile::ThemeDef}
+enforces at construction time that its dark and light members declare the
+same set of custom tokens. Without that check, a token you defined only
+on the dark side would raise `KeyError` the moment the user flipped to
+light — at an unpredictable time, far from the mistake. Checking up front
+turns a lurking runtime crash into an immediate, obvious construction
+error.
+
+### Custom tokens
+
+Your app almost certainly paints colors the framework knows nothing
+about — a "tool call" cyan, an "error" red, diff-line backgrounds. Those
+live in the theme's `custom` hash, a `Hash{Symbol => Color}`. You read
+one with `theme[:accent]`, which **fail-fasts**: a typo'd token raises
+`KeyError` rather than silently painting a default, so a missing color is
+a loud bug and not a mystery. And you render with the generic `fg` / `bg`
+helpers — `theme.fg(:accent, "NEW")` — the custom-token counterparts of
+the built-in `hint` / `active_bg` helpers.
+
+For an app with more than a couple of custom tokens, the tidier move is
+to **subclass** {Tuile::Theme} and give each token a named coloring
+method:
+
+```ruby
+class AppTheme < Tuile::Theme
+  def error(text) = fg(:error, text)
+  def tool(text)  = fg(:tool, text)
+end
+```
+
+Call sites then read `theme.error("...")` instead of the stringly-typed
+`theme.fg(:error, "...")`, and because a `Data` subclass survives `with`,
+your `AppTheme` stays an `AppTheme` through any `with` derivation. You
+build the dark and light instances from the built-in themes plus your
+custom hashes and pair them in a `ThemeDef` — the pattern is small enough
+to state in full:
+
+```ruby
+class AppTheme < Tuile::Theme
+  def error(text) = fg(:error, text)
+
+  DARK  = new(**Tuile::Theme::DARK.to_h.merge(custom: { error: Tuile::Color::RED }))
+  LIGHT = new(**Tuile::Theme::LIGHT.to_h.merge(custom: { error: Tuile::Color::RED3 }))
+  THEME_DEF = Tuile::ThemeDef.new(dark: DARK, light: LIGHT)
+end
+
+screen.theme_def = AppTheme::THEME_DEF   # once, at boot
+```
+
+Note the light-side error color isn't the same red — bright ANSI accents
+that pop on black often turn illegible on white, so a real light theme
+steps its accents darker. That per-side tuning is the entire point of
+carrying two themes instead of one.
+
+One aside on declaring theme colors: a {Tuile::Theme} takes {Tuile::Color}
+instances *only*, never the lenient coercions (`"red"`, a bare palette
+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.
+
+## When the theme changes under your content
+
+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.
+
+The problem: when you build a {Tuile::StyledString} for a
+{Tuile::Component::Label} or a {Tuile::Component::List} row, its colors
+are **baked in at construction**. The string is a frozen value with its
+SGR bytes already computed; it does not consult the theme at paint time,
+because {Tuile::StyledString} deliberately knows nothing about `Screen` at
+all (that independence is what lets it be a pure, memoizable value type).
+So if you colored a label with `theme[:accent]` and the theme later
+changes, that label keeps its old accent — the framework can't fix it,
+because only *you* know which of the string's colors came from the theme
+versus which are inherent to the data (a log line's level color, say,
+should *not* follow the theme).
+
+The hook for this is {Tuile::Component#on_theme_changed}, fired on every
+attached component whenever the theme changes. Your handler does exactly
+one thing: **re-run the code that rendered the content**, so it rebuilds
+the StyledString against the now-current theme.
+
+```ruby
+label.on_theme_changed = -> { label.text = render_status_line }
+```
+
+There are two ways to consume it, matching how you built the component.
+If you assembled stock components, assign the `on_theme_changed=` proc as
+above. If you subclassed, override the method — and call `super`, so an
+assigned listener still fires. Either way the rule is the same: the hook
+is where theme-derived content gets rebuilt, and the framework handles
+everything else.
+
+---
+
+That closes the runtime. Across six chapters you've seen the whole
+machine: a tree of components (chapter 1), repainting without flicker
+(chapter 2), sized top-down by their parents (chapter 3), driven by a
+single-threaded event loop (chapter 4), with keys routed through focus
+(chapter 5) and accents drawn from a terminal-following theme (this one).
+Everything from here is *application*: chapter 7 tours the component
+library — what Tuile ships so you don't build it — and chapter 8 shows
+how to test a UI built this way, using the fakes the design has been
+quietly setting up all along.

data/book/07-components.md

@@ -0,0 +1,231 @@
+# 7. The component library
+
+The last six chapters were about the machine: the tree, the repaint, the
+loop, focus, color. This one turns the other way and asks what you
+actually assemble on top of it. Tuile ships a small toolbox of ready
+components, and the point of this chapter is not to enumerate their
+methods — the rdoc does that, per symbol, and links are scattered
+throughout below — but to answer the question you have when you start a
+screen: *given what I'm trying to show or capture, which component do I
+reach for?*
+
+So this is a tour organized by the job, not by the class name. And
+because every one of these is a {Tuile::Component}, everything you already
+know still holds: its parent sizes it top-down (chapter 3), it invalidates
+rather than paints (chapter 2), focus decides whether it sees a key
+(chapter 5), and it draws its accents from the theme at paint time
+(chapter 6). The components don't reintroduce any of that; they just fill
+in the leaves of the tree.
+
+## Showing text
+
+The simplest job is putting text on the screen, and the choice comes down
+to one question: **does it need to wrap?**
+
+If not — a title, a status line, a single field of data — reach for
+{Tuile::Component::Label}. A label shows one or more lines of text and
+does *not* word-wrap; a line too wide for its rect is truncated with an
+ellipsis. That's a feature, not a limitation: a label is chrome, and
+chrome that reflows unpredictably when the terminal narrows is worse than
+chrome that clips. Its text is a {Tuile::StyledString}, so embedded color
+survives, and you can hand it either a plain `String` (parsed for ANSI) or
+a StyledString directly:
+
+```ruby
+label = Component::Label.new("Ready")
+label.text = "#{files.size} files"
+```
+
+When the text *is* prose — a help screen, a rendered Markdown reply, a log
+of wrapped lines — reach for {Tuile::Component::TextView} instead. It's
+the read-only counterpart to a label: string-shaped content in, but
+word-wrapped to its width (preserving spans across the wrap, so color
+isn't lost on continuation rows) and vertically scrollable, with the
+scroll keys and optional scrollbar you'd expect. For a growing view it
+gives you the right primitives for the right shape of update — `append`
+(aliased `<<`) concatenates verbatim for streaming, `add_line` starts a
+fresh line like a log entry, and `remove_last_n_lines` retracts the tail
+when you're rebuilding reformattable content. Turn on `auto_scroll` to
+keep the latest content in view. A TextView is meant to live inside a
+{Tuile::Component::Window} — it leans on the surrounding chrome for focus
+indication and keyboard hints.
+
+So: **Label truncates, TextView wraps.** That single line is the whole
+decision.
+
+## Editing text
+
+When you need input back from the user, the two editable components share
+a base — {Tuile::Component::TextInput} — and differ only in shape.
+
+{Tuile::Component::TextField} is a single line with a real hardware caret.
+It does not scroll; a keystroke that would push the text past the field's
+width is simply rejected, so the field always shows its whole contents.
+Because it owns the hardware cursor while focused, it's the component that
+triggers the cursor-ownership rule from chapter 5 — printable keys flow
+straight to it and sibling shortcuts stay muted while you type.
+
+{Tuile::Component::TextArea} is the multi-line counterpart: a word-wrapping
+editor that scrolls vertically to keep the caret's line visible, with
+Enter inserting a newline as in any text editor. Like everything else,
+it's sized by its parent — it does not grow to fit its content; text that
+overflows the rect is reached by scrolling.
+
+Both inherit the same event hooks from the base, and this is where the
+design pays off: you customize an input by assigning callbacks, not by
+subclassing. `on_change` fires whenever the text changes; `on_escape`
+handles ESC (with a sensible default). The subtle one is `on_key` — an
+interceptor consulted *before* the input's own key handling, which is the
+building block for an autocomplete or slash-command overlay: while the
+overlay is open, `on_key` claims Up/Down/Enter/ESC and forwards them to
+the list, so the caret stays in the field and typing keeps refilling the
+suggestions.
+
+```ruby
+field = Component::TextField.new
+field.on_change = ->(text) { filter_results(text) }
+field.on_enter  = -> { submit }        # nil (default) → Enter bubbles to the parent
+```
+
+Note that `on_enter` / `on_key_up` / `on_key_down` on a TextField, when
+left `nil`, let those keys *fall through* to the parent — that's how Enter
+in a search field can trigger the surrounding window's action while the
+field still handles ordinary typing.
+
+## Choosing from a set
+
+{Tuile::Component::List} is the workhorse: a scrollable column of
+{Tuile::StyledString} lines, ellipsized (spans preserved) when too wide.
+What makes it flexible is that its *cursor behavior is a pluggable object*
+rather than a boolean. Assign one of three {Tuile::Component::List::Cursor}
+variants to fit the interaction:
+
+- **`Cursor::None`** (the default) — no cursor at all. The list is a
+  read-only scroll region: a log, a static report.
+- **`Cursor`** — a moving cursor that lands on any line. Arrows, `jk`,
+  Home/End, and Ctrl+U/D move it, and the list scrolls to follow. This is
+  the ordinary selectable list.
+- **`Cursor::Limited`** — a cursor confined to a fixed set of allowed
+  lines. For a list where only some rows are selectable (headers
+  interspersed with items, say), it skips the rest.
+
+Two callbacks cover the events you care about. `on_item_chosen` fires when
+the user commits to the cursor's row — Enter or a left-click — and is the
+"open this" signal. `on_cursor_changed` fires when the highlighted row
+*changes*, which is exactly what you wire to keep a details pane in sync
+with the selection. For a tailing list — a live log — set `auto_scroll`;
+it pins to the bottom as lines arrive, but politely stops yanking you down
+the moment you scroll up to read history, and resumes once you scroll back
+(`following?` tells you which). A scrollbar is one assignment
+(`scrollbar_visibility`).
+
+```ruby
+list = Component::List.new
+list.lines  = entries
+list.cursor = Component::List::Cursor.new
+list.on_item_chosen = ->(index, line) { open(entries[index]) }
+```
+
+For a discrete action rather than a selection, {Tuile::Component::Button}
+is a one-row `[ caption ]` that fires `on_click` on Enter, Space, or a
+left-click, highlighting its background while focused. It's a tab stop, so
+it joins the normal Tab cycle.
+
+## Framing content
+
+{Tuile::Component::Window} is the frame: a bordered box with a `caption`
+and a single content slot you fill via `content=`. Its border lights up in
+the theme's accent color when the window is on the focus chain (chapter 5
++ 6), which is what makes the active pane visually obvious in a multi-pane
+layout. A window paints its whole rect and does not clip against
+neighbors, so windows are meant to tile, not overlap — overlapping is what
+popups are for.
+
+The bottom border has two mutually exclusive uses, and the distinction is
+the top-down-layout principle from chapter 3 made concrete. `footer_text=`
+embeds decoration into the border line — chrome, mirroring the caption on
+top, not focusable. `footer=` mounts a *real focusable component* spanning
+the full inner width — the search-field-in-the-border case. A footer
+component present takes the row and hides the text; neither drives the
+window's size (the window was sized by its parent), so a footer that
+doesn't fit is clipped rather than growing the frame. And if the content
+supports scrolling, `scrollbar=` turns on a scrollbar by reclaiming the
+right border column.
+
+```ruby
+window = Component::Window.new("Files")
+window.content = Component::List.new.tap { _1.lines = entries }
+window.scrollbar = true
+```
+
+## Overlays
+
+{Tuile::Component::Popup} is how you float something above the tiled UI.
+The popup itself paints nothing — it's a transparent host that wraps any
+component as its content and manages the lifecycle (`open` / `close`,
+ESC/`q` to dismiss). Crucially, and per chapter 3, **it does not size
+itself to its content**: its box is declared by `size` — a `Fraction`
+(default `Fraction::HALF`, half the screen, re-resolved on every resize)
+or an absolute `Size`. The content then fills that box, so use content
+that can cope with overflow — a TextView or TextArea that scrolls, not a
+bare Label that only truncates.
+
+A popup is **modal by default**: centered, it grabs focus, eats keys, and
+blocks clicks beneath it — that's what makes an open dialog trap Tab and
+input inside itself. Pass `modal: false` for a non-modal overlay that
+floats above the content without taking focus — the autocomplete-list case
+from earlier, where the caller positions it against a field's caret and
+drives it from app code.
+
+Because the popup is just a transparent host, you get a bordered dialog by
+wrapping a Window:
+
+```ruby
+window = Component::Window.new("Help")
+window.content = Component::TextView.new.tap { _1.text = help_text }
+Component::Popup.new(content: window).open
+```
+
+A nested TextField that owns the cursor still swallows printable keys
+first, so typing `q` into a field inside a popup doesn't dismiss it — the
+same cursor-ownership rule, working through the layers.
+
+## Batteries-included windows
+
+The last three components are conveniences: common Window-plus-content
+assemblies you'd otherwise build by hand. Each works tiled (add it to a
+layout) *or* as a popup (via a class-level `open`).
+
+- {Tuile::Component::InfoWindow} — a Window preloaded with a List of
+  static lines. The read-only "here's some information" box;
+  `InfoWindow.open(caption, lines)` pops it up.
+- {Tuile::Component::PickerWindow} — a menu of options each bound to a
+  single key, firing your block with the picked key. Popped up via `open`,
+  it closes itself after a pick; ESC/`q` cancels without firing.
+- {Tuile::Component::LogWindow} — a Window wrapping an auto-scrolling,
+  scrollbar-equipped TextView, purpose-built for log output. Its `log`
+  method is **thread-safe** — it marshals the append back onto the UI
+  thread via the event queue (chapter 4), so background work can log
+  freely. And it carries an `IO`-shaped adapter so you can point a stdlib
+  `Logger` (or a `TTY::Logger`) straight at it:
+
+```ruby
+window = Component::LogWindow.new
+logger = Logger.new(Component::LogWindow::IO.new(window))
+logger.info("started")   # appears in the window, from any thread
+```
+
+That LogWindow adapter is the tidy end of the thread-safety story chapter
+4 opened: a background thread doesn't know or care that its log line has
+to reach the UI on the loop thread — it writes to a `Logger` as it always
+would, and the plumbing routes it through `submit` for you.
+
+---
+
+That's the toolbox. None of it is large, because the framework underneath
+is small and the components inherit most of their behavior from it — which
+is the recurring theme of this whole book. What remains is proving that a
+UI built this way actually works, without a terminal in the loop. The
+fakes the design has been quietly setting up since chapter 2 — the buffer
+you can read back, the synchronous event queue, the in-memory screen — are
+what make that possible, and chapter 8 puts them to work.