tuile 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e4cd91c879f7eea941fd0a60a453a69de1f672a4907269282a0964645d919f8
-  data.tar.gz: c5f6b3124a64904cf606cfd4bc8a28409e7335b2b52c45bc99c67844f2b7de41
+  metadata.gz: 9cbba5366b6871e4ac6972819d1a3b03cb7b106bea1b3efc42ebf7fac27e279e
+  data.tar.gz: a72af4f77ce12a70ca0f3c477081047c81b193f4e2b8b5ca48dae3551daff524
 SHA512:
-  metadata.gz: 0c2d866c691d81685c3db892f933ce094fa9f770c8b7394a652f4344975595ec53acea525f05f1528ddcc934ce9a966ff631be9bf1292d58651c2606dd22fdaa
-  data.tar.gz: 87889c8181d1da7c477678456a3eee02dcd3abcf553b162c9cc1b560856228a8e65f062dc46c6d0c0a1edff5a892dd3b295e506f509698bc5a5142925b5c9663
+  metadata.gz: 883f93623cde985b9287ad548d941ee6cbca89639fbd2c19f5978581b13d8ca231731392c1d83860a34fae0124f3ccb27630581cc26f045064d3592bc45dd9da
+  data.tar.gz: 1c1c3ec8411c4368ecd6c7edd44da1681701fada1dc6a1345060c40a40ced7712dff9bb9433e90961e76b3300fc646e60a3c5755ef4acae1b759a9405732f32e

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [0.9.0] - 2026-07-05
+
+Layout is now strictly top-down: a parent assigns each child's `rect`, and components no longer advertise how big they want to be. The book's chapter 3 is the long-form rationale.
+
+- Add `Tuile::Fraction` (`HALF` / `FULL`, int-coercing, floor-at-1 `resolve`) — the one relational sizing primitive, scoped to `Popup#size=`.
+- `Component::Popup#size=` accepts a `Size` (clamped to the screen) or a `Fraction` (resolved against the screen on every layout pass, so it tracks resize); default `Fraction::HALF`. Adds a `size:` kwarg to `Popup.new` / `Popup.open`, forwarded through `InfoWindow.open`. Popups no longer auto-size to their content.
+- `Component::Window`: the single footer slot is split into two purpose-fit members — `footer_text=` (a `StyledString` embedded into the bottom border line at its own width with dashes filling the remainder, mirroring `caption` on top; not a component, not focusable) and `footer=` (a focusable component always spanning the full inner width of the bottom row). A `footer=` component present hides `footer_text`.
+- Add optional `Component::Label.new(text = nil)` — constructor symmetry with `Window.new(caption)`, reusing the `text=` coercion path (`String | StyledString | nil`). Purely additive; `Label.new` still works.
+- Add `EventQueue#tick_fps(fps)` = `tick(1.0 / fps)` for the frames-per-second animation idiom; lands on both the real and fake queues.
+- Fix `Buffer#flush` corrupting the left neighbour of a wide glyph: a dirty continuation cell (the right half of a wide glyph) no longer opens a flush run, so the next glyph is no longer shifted onto — and blanked by — the wide glyph's right half (e.g. an emoji vanishing when an adjacent cell changed, persisting across tmux window switches).
+- Memoize display-width measurement in `Buffer` and measure each grapheme once per paint: a full-screen 160×50 repaint drops from ~29.5ms to ~5.8ms (~5×). Adds `rake benchmark` (excluded from the packaged gem).
+- **Breaking:** the eager bottom-up sizing channel is deleted — `Component#content_size` / `content_size=` / `on_child_content_size_changed`, and the `Component#popup_min_height` / `popup_max_height` height-advice hooks added in 0.8.0. Containers now compute their children's rectangles in plain Ruby (in a `rect=` override) and hand them down; content fills or scrolls within the rect it's given. Custom components that advertised a size must move that logic into the parent.
+- **Breaking:** `Tuile::Sizing` (`FILL` / `WRAP_CONTENT` / `Sizing.fixed`) and `Window#footer_sizing`, both added in 0.6.0, are removed — a bottom-row `footer=` widget is always FILL by construction.
+- **Breaking:** `EventQueue#tick(seconds)` now takes an interval in **seconds**, not frames-per-second. `tick(4)` used to mean "4 times a second"; it now means "every 4 seconds", matching `sleep` / `TimerTask` and every other Ruby scheduler. Use the new `tick_fps(fps)` for the animation mental model.
+
 ## [0.8.0] - 2026-06-11
 
 - Render through a back buffer: `Screen#buffer` is now a `Tuile::Buffer` cell grid sized to the viewport. Components paint into it; `Screen#repaint` flushes only the cells that changed since the last frame, wrapped with the cursor move in one synchronized-output batch (DEC mode 2026). Repaint is flicker-free on **any** terminal regardless of mode-2026 support, because an unchanged cell is never rewritten — the full-scene overdraw a shrinking popup forces no longer reaches the wire. `FakeScreen` exposes the populated buffer for content assertions (`row_text`/`row_ansi`/`region_text`/`region_ansi`/`cell`); `prints` now holds only the assembled frame and cursor housekeeping.

data/README.md

@@ -49,7 +49,16 @@ gem "tuile", git: "https://github.com/mvysny/tuile.git"
 
 Tuile requires Ruby 3.3+.
 
-API documentation: <https://rubydoc.info/gems/tuile>.
+## Documentation
+
+- **[The Tuile guide](book/README.md)** teaches Tuile cover to cover — the
+  component tree, the top-down layout model and the case for why it's
+  enough, the single-threaded event loop and background work, focus, and
+  theming. Start here to learn the concepts and the *why*. It grows a
+  chapter at a time; the layout chapter is the heart of the design.
+- **API reference:** every public class and method carries YARD headers —
+  browse them at <https://rubydoc.info/gems/tuile>, or run
+  `bundle exec rake yard` for a local site.
 
 ## Hello world
 
@@ -101,27 +110,37 @@ attachment checks and child-removed callbacks all work uniformly.
 
 ### Layout and repaint
 
-Tuile uses the simplest possible repaint model — no damage tracking, no
-clipping, no diffing:
+Repainting has two halves: an *invalidation* pass decides which components
+re-render, and a *back buffer* turns their output into the minimal set of
+bytes sent to the terminal. There is no clipping in between.
 
 1. A component that needs to redraw calls `invalidate`. This just records the
    component in a set on the screen.
 2. After the event loop drains the current batch of keyboard/mouse/posted
    events, the screen runs a single `repaint` pass:
    - Invalidated **tiled** components are sorted by tree depth (parents first)
-     and each one fully redraws its `rect`.
+     and each one repaints its `rect`.
    - If anything tiled was redrawn, **all popups** are drawn on top in
      stacking order. Popups deliberately overdraw content; there is no
-     clipping.
+     clipping — overdraw is free because it only touches the buffer.
    - The hardware cursor is moved to the focused component's
      `cursor_position` (e.g. into a focused text field).
 
-This means a component is responsible for fully covering its own `rect` —
-parents do not paint behind their children. `Layout` enforces this by simply
-not drawing anything itself; its children must tile the entire layout area.
-The trade-off is that if you leave gaps, they will show stale characters; the
-upside is that the repaint code is tiny and predictable, and there is no
-flicker because the terminal is written to in a single batched pass per tick.
+Components never write escape sequences to the terminal. They paint styled
+cells into a back buffer (`Tuile::Buffer`) via `set_line` / `fill` /
+`set_char`. When the pass finishes, `Buffer#flush` emits the **minimal diff**
+— only the cells that actually changed since the last flush — wrapped in one
+synchronized-output batch. That is what keeps repaint flicker-free on any
+terminal regardless of mode-2026 support: an unchanged cell is never
+rewritten, so a popup overdrawing content costs nothing on the wire unless it
+changes a visible cell.
+
+A component must fully cover its own `rect`, but it need not tile that rect
+with children: the default `repaint` clears the background behind any gaps and
+re-invalidates its children to paint on top, so a layout with mixed-width
+fields shows no stale characters. Components that paint their entire rect
+themselves (`Window`, `List`) opt out of that default. `Layout` paints nothing
+of its own and positions its children within its rect.
 
 ### Single-threaded event loop
 
@@ -397,7 +416,7 @@ label = Tuile::Component::Label.new
 label.text = "Hello, #{screen.theme.hint('world')}!"
 ```
 
-Key API: `text=`, `content_size`.
+Key API: `text=`, `bg=`.
 
 ### `Component::Layout`
 
@@ -493,14 +512,16 @@ popup by default).
 ### `Component::Popup`
 
 A modal overlay. It paints nothing itself: it wraps any component as
-`content`, centres itself on the screen, auto-sizes to the wrapped content,
-and consumes `q` / `ESC` to close. Popups are drawn on top of the tiled
-content; multiple popups stack.
+`content`, sizes itself top-down from `size:` (a `Size`, or a `Fraction` of
+the screen resolved every layout pass — default `Fraction::HALF`), centres
+itself, and consumes `q` / `ESC` to close. The content fills that box and
+scrolls/wraps within it; it does *not* drive the popup's size. Popups are
+drawn on top of the tiled content; multiple popups stack.
 
 ```ruby
 window = Tuile::Component::Window.new("Help")
 window.content = help_list
-Tuile::Component::Popup.open(content: window)
+Tuile::Component::Popup.open(content: window, size: Tuile::Fraction::HALF)
 # or, equivalently:
 popup = Tuile::Component::Popup.new(content: window)
 popup.open
@@ -508,7 +529,9 @@ popup.open
 ```
 
 Bare content also works (a `Label`, a `List`…) and yields a borderless popup;
-wrap in a `Window` if you want a frame.
+wrap in a `Window` if you want a frame. Pass `modal: false` for a non-modal
+overlay that floats above the content without grabbing focus — the caller
+positions and drives it.
 
 ### `Component::InfoWindow`
 
@@ -578,10 +601,10 @@ Tuile.logger = Logger.new(Tuile::Component::LogWindow::IO.new(window))
 
 Tuile ships with a `Tuile::FakeScreen` that you install in place of the real
 screen for unit tests. It fixes the viewport at 160×50, disables the UI lock,
-collects every string the framework "would have printed" into an array, and
-uses a synchronous `FakeEventQueue` (submitted blocks run inline; posted
-events are discarded). No terminal IO happens, so the TTY running the tests
-is never painted over.
+paints into an in-memory back buffer (assert on it for painted content) while
+capturing cursor/housekeeping escapes into an array, and uses a synchronous
+`FakeEventQueue` (submitted blocks run inline; posted events are discarded).
+No terminal IO happens, so the TTY running the tests is never painted over.
 
 The standard setup is `Screen.fake` / `Screen.close` as a before/after pair —
 this resets the singleton between examples, so state can't leak across
@@ -600,7 +623,7 @@ module Tuile
       label.rect = Rect.new(0, 0, 5, 1)
       label.text = "hi"
       label.repaint
-      assert_equal [TTY::Cursor.move_to(0, 0), "hi   "], Screen.instance.prints
+      assert_equal ["hi   "], Screen.instance.buffer.region_text(label.rect)
     end
   end
 end
@@ -608,8 +631,12 @@ end
 
 Key hooks:
 
-- `Screen.instance.prints` — array of strings the screen would have written
-  to the terminal. Assert against it (or `.join`) for repaint output.
+- `Screen.instance.buffer` — the back buffer painted content lands in. Assert
+  on `buffer.region_text(rect)` / `buffer.region_ansi(rect)` (per-row arrays)
+  or `buffer.cell(x, y)` for a single cell's grapheme and style.
+- `Screen.instance.prints` — array of cursor/housekeeping escapes and the
+  assembled frame string. Assert against it (or `.join`) for cursor behavior,
+  not for painted content.
 - `Screen.instance.repaint` — drive a repaint synchronously; production code
   must not call this, but specs use it to flush the invalidated set after a
   mutation.

data/book/01-first-app.md

@@ -0,0 +1,186 @@
+# 1. Your first Tuile app
+
+This chapter builds the smallest useful Tuile program — a bordered window
+that says hello — and uses it to name the handful of ideas the rest of
+the guide leans on. There's almost no depth here on purpose: the goal is
+the *shape* of a Tuile program and the mental model, not the details.
+Every concept named in passing gets its own chapter later.
+
+## Install
+
+Tuile is a gem; it needs Ruby 3.3 or newer. Add it to a project with
+`bundle add tuile`, or install it standalone with `gem install tuile`,
+and `require "tuile"` at the top of your script. That's the whole
+prerequisite — Tuile builds on the `tty-*` toolkit but pulls in what it
+needs itself, and it talks to the terminal you already have.
+
+## The whole program
+
+Here is a complete Tuile app. It draws a framed window containing the
+text "Hello, world!" and waits; pressing `q` or `Esc` exits.
+
+```ruby
+require "tuile"
+
+# The Screen must exist before you wire components together: attaching a
+# component (content=, focus, …) reaches for Tuile::Screen.instance.
+screen = Tuile::Screen.new
+
+label = Tuile::Component::Label.new("Hello, world!")
+
+window = Tuile::Component::Window.new("Tuile")
+window.content = label
+
+screen.content = window
+window.focus
+
+begin
+  screen.run_event_loop
+ensure
+  screen.close
+end
+```
+
+That's it — no configuration, no layout file, no main loop you write by
+hand. The rest of this chapter walks the seven lines that matter and
+names what each one introduces.
+
+## Build the screen first
+
+```ruby
+screen = Tuile::Screen.new
+```
+
+{Tuile::Screen} is the runtime: it owns the terminal, the event loop, and
+the one back buffer everything paints into. It is a **process
+singleton** — there is exactly one screen per app, and `Screen.new`
+installs it as *the* instance. After this line, any component can find it
+with `Tuile::Screen.instance` (which is how the base {Tuile::Component}
+implements its `screen` accessor).
+
+Order matters: construct the screen *before* you start wiring components
+together. Building a bare component (`Label.new`) touches nothing, but
+the moment you attach one to the tree — `window.content = label`,
+`window.focus` — that component reaches for `Screen.instance` to register
+itself. No screen yet, and you get a "Screen not initialized" error. In
+practice the rule is simply: `Screen.new` is the first line.
+
+## Build a tree of components
+
+```ruby
+label = Tuile::Component::Label.new("Hello, world!")
+
+window = Tuile::Component::Window.new("Tuile")
+window.content = label
+```
+
+Everything you see on screen is a {Tuile::Component}: a piece of UI that
+occupies a rectangle and knows how to paint itself into it. Components
+nest into a **tree** — a component has a `parent` and `children` — and
+that tree *is* your UI.
+
+Here the tree is two nodes deep. A {Tuile::Component::Label} is a passive
+one-liner of text, given straight to the constructor (or assigned later
+with `label.text =`). A {Tuile::Component::Window} is a bordered frame
+with a caption (`"Tuile"`, which you'll see drawn into the top edge) and a
+single content slot. `window.content = label` puts the label inside the
+window's frame and makes the window its parent. Assigning content is also
+what *attaches* the label to the live tree, so from this point the label
+is a real, paintable thing.
+
+Notice you never say where anything goes or how big it is. You didn't
+give the label a position or the window a size. **A component's parent
+decides its rectangle** — the window will size the label to fit inside
+its border, and something will size the window to fill the terminal.
+That "something" is the next line, and the top-down layout rule behind it
+is the whole of chapter 3.
+
+## Put it on screen, and focus it
+
+```ruby
+screen.content = window
+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.
+
+`window.focus` marks the window as the **focused** component: the one
+that receives keystrokes. Focus flows down toward interactive content
+where it can, so focusing the window is the natural way to say "this is
+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.
+
+## 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:
+
+```
+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)
+```
+
+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.
+
+## Run the loop, and always close
+
+```ruby
+begin
+  screen.run_event_loop
+ensure
+  screen.close
+end
+```
+
+{Tuile::Screen#run_event_loop} is where your program *lives*. It puts the
+terminal into raw mode, then loops: read a key (or a mouse event, or a
+resize), dispatch it into the component tree, and — once the dust settles
+— repaint whatever changed. It's a single thread doing one thing at a
+time, and that single-threadedness is a deliberate, load-bearing design
+choice (chapter 4). The loop returns when the user presses `q` or `Esc`
+without any component consuming the key first.
+
+The `ensure` is not optional. `run_event_loop` reconfigured your
+terminal — raw mode, a hidden cursor, mouse tracking — and
+{Tuile::Screen#close} is what puts it all back. Skip it and a crash leaves
+the user staring at a terminal that no longer echoes what they type. Wrap
+the loop in `begin`/`ensure` so teardown happens no matter how you exit.
+
+## The shape of every Tuile program
+
+Strip away the specifics and every Tuile app is the same four beats:
+
+1. **Make the screen** — `Screen.new`, first, so components can find it.
+2. **Build a tree** of components and hand its root to `screen.content=`.
+3. **Run the loop** — `run_event_loop` reads input, updates the tree, and
+   repaints.
+4. **Close** in an `ensure`, always.
+
+That's the whole skeleton. Everything else in this guide is about the
+second and third beats: how to build richer trees (the component library,
+chapter 7), how the tree gets sized (layout, chapter 3), how it repaints
+without flicker (chapter 2), and how input and background work move
+through the loop (chapters 4 and 5).
+
+Next up: chapter 2, on what actually happens between "a component changed"
+and "the terminal shows it" — the repaint model.

data/book/02-repaint.md

@@ -0,0 +1,177 @@
+# 2. How the screen repaints
+
+In chapter 1 you built a tree and ran the loop, and text appeared. This
+chapter is about the gap between those two — what happens between "a
+component changed" and "the terminal shows it." The short version is that
+components don't paint when they change, and they never write to the
+terminal at all. They *invalidate*, and once per loop tick the screen
+paints everything that asked to be repainted, in one flicker-free batch.
+
+Understanding this model matters for two reasons. It's the contract every
+custom component has to honor (paint your rectangle, don't touch the
+wire). And it's *why* Tuile stays smooth without any of the damage-region
+or clipping machinery a UI toolkit would normally need.
+
+## Components invalidate; they never paint the terminal
+
+When something about a component changes — its text, its focus, its size
+— it does not repaint itself on the spot, and it certainly doesn't emit
+escape sequences to the terminal. It calls one protected method:
+
+```ruby
+invalidate
+```
+
+That does exactly one thing: it records "this component needs to be
+repainted" in a set the {Tuile::Screen} owns. Nothing is drawn yet. If
+the same component is invalidated ten times before the next repaint —
+because an event handler changed its text, then its color, then its size
+— it's still just one entry in the set, and it repaints once.
+
+That coalescing is the whole point of deferring. A single keystroke can
+ripple through a dozen components; a naive "repaint on every change"
+would draw the screen a dozen times per key, and you'd see it flicker and
+tear. By separating *"I changed"* (`invalidate`, cheap, happens whenever)
+from *"the screen is now redrawn"* (once per tick, batched), Tuile makes
+the number of repaints independent of the number of changes.
+
+`invalidate` is deliberately protected — you don't call it from outside a
+component. You mutate a component through its public setters (`text=`,
+`content=`, `rect=`, …) and *they* invalidate. And it's a no-op on a
+component that isn't attached to the live tree, so mutating a component
+you've stashed off-screen (say, inside a closed popup) is silent rather
+than an error.
+
+## When a component does paint, it paints into a buffer
+
+Eventually the screen does call a component's {Tuile::Component#repaint}.
+Even then, the component does not write to the terminal. It writes styled
+cells into the screen's **back buffer** — a {Tuile::Buffer}, an in-memory
+grid of styled cells mirroring the terminal — through three methods:
+
+```ruby
+screen.buffer.set_line(x, y, styled_string)   # a run of text
+screen.buffer.set_char(x, y, grapheme, style) # one cell
+screen.buffer.fill(rect, style)               # a blank region
+```
+
+That's the entire painting vocabulary. A component's `repaint` computes
+what its rectangle should look like and stamps it into the buffer. No
+cursor moves, no color escapes, no `print` — just cells into a grid.
+
+Keeping the buffer between the component and the terminal is what unlocks
+everything in the rest of this chapter, so it's worth saying plainly: the
+buffer *is* the seam. Components produce a desired grid state; the screen
+turns grid state into the minimal set of bytes on the wire. Neither side
+knows about the other's job.
+
+## The repaint pass, once per tick
+
+The event loop (chapter 4) processes whatever arrived — a key, a click, a
+resize — and each of those may invalidate some components. When the queue
+runs dry, the loop fires one repaint pass. The screen walks the
+invalidated set and draws it in a specific order:
+
+1. **Tiled components first, parent before child.** The framework walks
+   the tree in pre-order, which naturally visits a parent before its
+   children. That order matters: a parent lays down its background (and,
+   for a container with gaps between its children, re-clears them) *first*,
+   so a child drawing afterward paints on top of a clean surface rather
+   than fighting whatever was there before.
+2. **Popups last, on top.** Any popups (chapter 7) repaint after the tiled
+   layer, in stacking order, so they overdraw the content beneath them.
+   There is no clipping and no "punch a hole in the content" step —
+   popups simply draw over what's below. If a tiled repaint touched cells
+   a popup also covers, the whole popup stack is reasserted on top so it
+   stays visually in front.
+
+Notice what's *absent*: no region tracking, no dirty-rectangle geometry,
+no z-buffer, no clip stack. The order is just "tree order, then popups,"
+and the correctness comes from painting in that order into a buffer that
+sorts out the rest.
+
+## Overdraw is free; the wire is minimal
+
+The reason all that overdraw doesn't cost anything is the buffer's flush.
+After every component has painted into the buffer, the screen calls
+{Tuile::Buffer#flush}, which computes the **minimal diff**: it compares the
+buffer to the state the terminal was left in by the previous flush and
+emits escape sequences only for the cells that actually changed. An
+unchanged cell is never rewritten, no matter how many components painted
+over it this tick.
+
+So "overdraw is free" is literal. A popup can repaint over the entire
+content area, a parent can re-clear a region a child then fills — none of
+it reaches the terminal unless the *net* result differs from what was
+already on screen. You get to write dead-simple paint code (just draw
+your whole rectangle, every time) and pay only for what visibly changed.
+
+The whole diff, plus the cursor repositioning, is wrapped in one
+**synchronized-output batch** (the terminal's mode-2026 escape) and
+written in a single `write`. A terminal that supports synchronized output
+composites the frame atomically — no partial frame is ever visible. But
+here's the part that makes Tuile flicker-free *everywhere*: the
+smoothness doesn't depend on that support. Because an unchanged cell is
+never touched, there's nothing to flicker even on a terminal that ignores
+the batch escape entirely. Synchronized output is a bonus on top of a
+model that's already tear-free.
+
+## The contract: cover your own rect, and only your rect
+
+All of this rests on one rule every component must follow:
+
+> A component paints every cell it's responsible for, and never a cell
+> outside its `rect`.
+
+The "never outside" half keeps siblings from corrupting each other —
+there's no clipping to save you, so drawing out of bounds means drawing
+on someone else's cells. The "every cell it's responsible for" half is
+what keeps stale pixels from surviving: if your rectangle used to show
+"Loading…" and now shows nothing, the cells that held the old text have
+to be actively overwritten (with blanks), or they'd linger.
+
+Meeting that second half is easy, because the default
+{Tuile::Component#repaint} does the tedious part for you:
+
+- 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
+  damage-tracking pass.
+
+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
+rect themselves and don't want the redundant clear — {Tuile::Component::Window}
+(its border and interior cover the whole rect) and
+{Tuile::Component::List} (it paints every row explicitly). Everything else
+should `super`.
+
+You are *not* required to tile your rect with children — leaving gaps is
+fine, the default handles it. You're only required to make sure that when
+the dust settles, every cell you own reflects the current state, not a
+previous one.
+
+## Don't reach for repaint
+
+One last rule, and it follows from everything above: **never call
+`Screen#repaint` from inside a component.** Repaint is the loop's job,
+fired once per tick after the queue drains. If you call it yourself you
+break the coalescing — you force a draw mid-event, before other
+components have reacted, and you may draw a half-updated frame. Just
+`invalidate` (or, in practice, mutate through a setter that invalidates)
+and let the loop batch it.
+
+The one place you *will* see `Screen#repaint` called directly is in tests,
+which drive the system a step at a time and need to force a paint to
+assert on the buffer's contents. That's chapter 8; in application code,
+invalidation is the only lever you touch.
+
+With the repaint model in hand, the natural next question is the one this
+chapter kept deferring: who decides a component's `rect` in the first
+place? That's chapter 3 — layout.