tuile 0.15.0 → 0.17.0

data/README.md

@@ -12,10 +12,12 @@ providers — is described in
 Tuile is that approach applied to a terminal.
 
 Tuile is the only actively maintained component-oriented TUI framework for
-Ruby that we are aware of. If you have looked at the alternatives —
-tty-toolkit, vedeu, ratatui, or the curses bindings your distro packages —
-[COMPARISON.md](COMPARISON.md) sizes each one up and says which of them you
-can actually reach from Ruby.
+Ruby that we are aware of. Ruby does now reach two of the big non-Ruby
+toolkits — Rust's ratatui through `ratatui_ruby`, Go's Charm stack through
+CharmRuby — but both hand you a draw loop or an Elm-style model/update/view,
+not a tree of components. [The research notes](design/research.md) size up each
+neighbour, those two included, alongside tty-toolkit, vedeu and the curses
+bindings your distro packages.
 
 ## Installation
 
@@ -55,8 +57,8 @@ else in Tuile loads it.
 - **API reference:** every public class and method carries YARD headers —
   browse them at <https://rubydoc.info/gems/tuile>, or run
   `bundle exec rake yard` for a local site.
-- **[COMPARISON.md](COMPARISON.md)** places Tuile among the neighbouring
-  toolkits, and answers what a Ruby program can reach without writing
+- **[The research notes](design/research.md)** size up the neighbouring
+  toolkits, and answer what a Ruby program can reach without writing
   bindings first.
 
 ## Hello world
@@ -108,13 +110,14 @@ write escape sequences. They call `invalidate`, and paint styled cells into a
 back buffer when the loop asks them to; one flush per tick emits the
 **minimal diff** — only the cells that actually changed — inside a
 synchronized-output batch. There is no damage tracking to maintain and no
-clipping to think about: popups simply overdraw, because overdraw into a
-buffer is free. → [chapter 2](book/02-repaint.md)
+clipping to manage — a component is bounded by its own rectangle for you, and
+popups simply overdraw, because overdraw into a buffer is free.
+→ [chapter 2](book/02-repaint.md)
 
 **Layout is top-down, and that is the whole model.** A parent computes its
 children's rectangles in plain Ruby and assigns them; a component never
 advertises a size it would like. No `min`/`preferred`/`max`, no negotiation
-pass, no shrink-to-fit. Subclass `Layout::Absolute` when the arithmetic is
+pass, no shrink-to-fit. Subclass `Layout` when the arithmetic is
 yours, or use `Layout::Vertical` / `Layout::Horizontal` to declare each
 child's extent as `Fixed` / `Percent` / `Expand`.
 → [chapter 3](book/03-layout.md)
@@ -137,9 +140,20 @@ between panes. A paste is deliberately *not* a burst of keys: with bracketed
 paste it arrives whole, as one `handle_paste`.
 → [chapter 5](book/05-focus.md)
 
+**The mouse is routed by position, and claimed by one component.** A press
+focuses the innermost focusable under the pointer before any handler runs,
+then bubbles outward through `handle_mouse_down?` until someone answers
+`true` — and that claimant is *grabbed*, so the drags and the release reach
+it wherever the pointer goes. The wheel bubbles the same way, so a list
+already at its top hands the notch up to whatever scrolls around it. `capture_mouse:` picks how
+much the terminal reports: `:clicks`, `:drag`, or `:hover` with enter/exit
+hooks.
+→ [chapter 5](book/05-focus.md)
+
 **Theming is accents-only, and follows the OS.** A `Theme` carries semantic
-accent tokens — the list cursor, an input well, an active window border,
-status-bar hints — plus whatever `custom` tokens your app adds. Everything
+accent tokens for the chrome Tuile itself paints — the list cursor, an input
+well, an active window border, a scrollbar — plus whatever `custom` tokens your
+app adds for text of its own (a status row's shades live there). Everything
 else inherits the terminal's own foreground and background, so Tuile looks at
 home in the user's palette instead of fighting it. Tuile probes the terminal
 background at startup, pairs a dark and a light theme in a `ThemeDef`, and
@@ -171,8 +185,9 @@ carries the per-method reference: `bundle exec rake yard`, or
 
 | component | what it is |
 |---|---|
-| `Layout::Absolute` | Positions children by assigning their `rect` in a `rect=` override, and paints nothing itself. The base to subclass when the arithmetic is yours. |
-| `Layout::Vertical`, `Layout::Horizontal` | Stack children along one axis from declared extents — `Fixed[n]`, `Percent[n]`, `Expand[weight]` — with box-global `spacing` and `padding`. Sugar over `Absolute`, not a new sizing model. |
+| `Layout` | Positions children by assigning their `rect` in a `relayout` override, and paints nothing itself. The base to subclass when the arithmetic is yours. |
+| `Layout::Absolute` | Places each child at the fixed `Rect` it was added with; `constrain` moves one. |
+| `Layout::Vertical`, `Layout::Horizontal` | Stack children along one axis from declared extents — `Fixed[n]`, `Percent[n]`, `Expand[weight]`, a `Percent` bounded with `.clamp(range)` — with box-global `spacing` and `padding`. Sugar over a hand-written `relayout`, not a new sizing model. |
 
 ### Framing and switching — [book ch7](book/07-components.md#framing-content)
 
@@ -180,6 +195,10 @@ carries the per-method reference: `bundle exec rake yard`, or
 |---|---|
 | `Window` | A frame with a `caption`, one content slot, and a border that lights up while the window is on the focus chain. `footer_text=` decorates the bottom border; `footer=` mounts a real component in it; `scrollbar=` reclaims the right border column. |
 | `Slot` | A one-child region for content that may be absent, arrive late, or be swapped. Give a multi-region container one per region and the tree stays honest — the occupant fills the slot's rect, and an empty slot holds its place rather than collapsing. |
+| `Scroller` | A viewport onto a taller pile of components: one content child, a scrollbar column, and `content_rows` — you say how tall the content is, since nothing measures. The wheel scrolls it, the bar drags, and so does focus: Tab into a field below the fold and it comes into view. |
+| `VerticalScrollBar` | A one-column bar the user can drag, and press the track of to page. It moves nothing itself: it asks through `on_scroll_request` and the container that owns the column assigns `scroll_top_row`. Dragging wants `run_event_loop(capture_mouse: :drag)`. |
+| `FormItem` | One row of a form: a `caption` above a field, an optional required marker beside it, and the message the field reports against itself — a validator's verdict, or input it cannot parse — mirrored into the row below. Three rows that never reflow — the message row doubles as the gap. Hide the item, not the field. |
+| `FormLayout` | A column of `FormItem`s: `add(field, caption:, required:, rows:)` wraps the field, returns the item and stacks it below the last. No `spacing` — the message row is the gap — nothing measures, and items past the bottom edge are clipped rather than scrolled. |
 | `MenuBar` | A one-row strip of menu captions, each dropping a cascade of submenus that nests without limit. Items are handles from `#add_item`, each with its own `on_click`. See [Menus](book/07-components.md#menus). |
 | `Tabs` | A one-row strip of captions with one selected, Left/Right switching immediately. Knows nothing about content — pair it with `TabSheet`, or drive your own view swap from `on_tab_selected`. |
 | `TabSheet` | A `Tabs` strip plus the pane belonging to the selected tab. Unselected panes are *detached*, so they keep their state and stay out of the Tab cycle. See [Switching between views](book/07-components.md#switching-between-views). |
@@ -191,6 +210,7 @@ carries the per-method reference: `bundle exec rake yard`, or
 | `Label` | Static text, one row per line, no wrapping — long lines are ellipsized. Content is a `StyledString`, so ANSI passes through. |
 | `TextView` | A read-only viewer for prose: word-wrapped, scrollable, appendable, and addressable in named `Region`s when you want to rewrite one part of the text in place. |
 | `ProgressBar` | A one-row bar — `█` over a `░` track — driven by `value` within a `Range`, or `indeterminate` for a bouncing sweep that owns its own ticker while on screen. |
+| `Fill` | One glyph in every cell of its rect, in a `color` that may be a live `Theme.ref`. A one-column `Fill` of `│` is a vertical rule between borderless panes, a one-row `─` a horizontal one. |
 
 ### Editing text — [book ch7](book/07-components.md#editing-text)
 
@@ -209,18 +229,19 @@ carries the per-method reference: `bundle exec rake yard`, or
 | `BigDecimalField` | The same for money, where a binary `Float` is the wrong answer. Tuile's one optional dependency — add `bigdecimal` yourself if you name this component. |
 | `DateField` | A one-row field whose `value` is a `Date` or `nil`, over a list of strftime formats taken from `Screen#locale`: it accepts any of them and writes the first one back when you leave the field. Manual entry — there is no calendar popup yet. |
 | `TimeField` | A one-row field whose `value` is a time of day — a `Time` on a fixed epoch date, or `nil` — spelled the way `Screen#locale` says. `step` is both the Up/Down stride and the precision: it shows seconds only when set below a minute. |
+| `DateTimeField` | The two above side by side on one row, behind a single `DateTime` at `+00:00`. Each half reddens its own bad input; the field reddens whole only for the fault no half can wear — one half filled and the other empty. |
 
 ### Choosing from a set — [book ch7](book/07-components.md#choosing-from-a-set)
 
 | component | what it is |
 |---|---|
 | `Checkbox` | A one-row boolean: `[x]` / `[ ]` plus a caption, toggled by Space, Enter or a click on the glyph or label. |
-| `List` | The workhorse: a scrollable column of *typed items*, one row each, rendered lazily by a `renderer` you supply and handing your callbacks the item itself. Add a `Cursor` (or `Cursor::Limited`) to make it navigable. |
+| `List` | The workhorse: a scrollable column of *typed items*, one row each, rendered lazily by a `renderer` you supply and handing your callbacks the item itself. Add a `Cursor` (or `Cursor::Limited`) to make it navigable, or set `interactive = false` for a display-only pane Tab skips. |
 | `RadioGroup` | Single-select over a set of items, one row each, with the marker painted in front of the label. Its `value` is the selected item. |
 | `CheckboxGroup` | Multi-select over the same shape; its `value` is a frozen `Set` of the checked items. |
 | `Select` | The enum field: a one-row face plus a `▾`, dropping open a list of options. Claims no printable key but Space, so your app's own keys keep working while it has focus. |
 | `ComboBox` | A text field with a filtering dropdown — type to narrow, arrow to highlight, Enter to accept. Its `value` is the selected *item*, never the typed text. |
-| `ListDropdown` | The floating, non-focusable list that `Select` and `ComboBox` drop open, and the `Menu` variant an app can drive itself. You rarely instantiate it directly. |
+| `ListDropdown` | The floating, non-focusable list that `Select` and `ComboBox` drop open with `anchor_to(self)`, following the field as it moves, and the `Menu` variant an app can drive itself. You rarely instantiate it directly. |
 
 ### Taking an action — [book ch7](book/07-components.md#taking-an-action)
 
@@ -232,12 +253,12 @@ carries the per-method reference: `bundle exec rake yard`, or
 
 | component | what it is |
 |---|---|
-| `Overlay` | The bare floating layer: it wraps any component, paints nothing itself, and sits at the rect you assign it. Takes no focus and no keys — the building block for anchored panels and toasts. |
-| `Popup` | The modal dialog: an `Overlay` that centers itself, grabs focus, scopes keys to its own subtree and blocks clicks beneath it. Sized by `declared_size=` (a `Size` or a `Fraction` of the screen) rather than by its content; ESC or `q` dismisses. |
-| `Notification` | A transient corner toast — `Notification.show("Saved")` — stacking messages in one box that a single ticker drains. Non-modal, and it never takes focus. |
+| `Overlay` | The bare floating layer: it wraps any component, paints nothing itself, and sits where its placement says — `open(Overlay::At[rect])`; the pane assigns the rect, again on every resize. Takes no focus and no keys — the building block for anchored panels and toasts. |
+| `Popup` | The modal dialog: an `Overlay` placed centered by default, which grabs focus, scopes keys to its own subtree and blocks clicks beneath it. Sized by `declared_size=` (a `Size` or a `Fraction` of the screen) rather than by its content; ESC or `q` dismisses. |
+| `Notification` | A transient corner toast — `Notification.show("Saved")` — stacking messages in one box that a single ticker drains. Non-modal, it never takes focus, and its inner `View` refuses the wheel so queued messages wait for the ticker. |
 | `ConfirmWindow` | The confirm dialog: a message and a row of buttons in a popup sized to fit. `alert` / `confirm` / `yes_no` cover the common shapes; `#button` builds any other. Every button closes; ESC, `q` or an outside click fire `on_dismiss`. See [The confirm dialog](book/07-components.md#the-confirm-dialog). |
 | `InfoWindow` | A `Window` with a read-only body, tiled or popped up: prose that wraps (`message=`), or rows that don't (`lines=`). |
-| `PickerWindow` | A `Window` of options identified by single keystrokes, firing a callback with the key that was pressed. |
+| `PickerWindow` | A `Window` of options identified by single keystrokes, firing a callback with the key that was pressed. Captions take a `StyledString` to color one. |
 | `LogTextView` | An auto-scrolling `TextView` for log output. Point your logger at a `LogTextView::IO` and lines land here from any thread, marshalled through the event queue. |
 | `LogWindow` | A `Window` framing a `LogTextView` — the framed log pane. |
 
@@ -292,10 +313,12 @@ module Tuile
 
     it "renders text into its rect" do
       label = Component::Label.new
-      label.rect = Rect.new(0, 0, 5, 1)
       label.text = "hi"
-      label.repaint
-      assert_equal ["hi   "], Screen.instance.buffer.region_text(label.rect)
+      holder = Component::Layout::Absolute.new
+      holder.add(label, Rect.new(0, 0, 5, 1))   # a parent places it; nothing else may
+      Screen.instance.content = holder
+      Screen.instance.repaint
+      assert_equal ["hi   "], Screen.instance.buffer.region_text(label.absolute_rect)
     end
   end
 end
@@ -342,14 +365,16 @@ run `bundle exec rake spec` to run the tests. You can also run `bin/console`
 for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
-To release a new version, see [`RELEASING.md`](RELEASING.md).
+To release a new version, see [`design/releasing.md`](design/releasing.md).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
 <https://github.com/mvysny/tuile>. Please read [`AGENTS.md`](AGENTS.md) before
 opening a PR — it documents the architecture invariants (singleton screen,
-invalidation/repaint contract, threading rule) that the framework relies on.
+invalidation/repaint contract, threading rule) that the framework relies on,
+and routes you to [`design/`](design/), where
+[`decisions.md`](design/decisions.md) answers "why is it like this?".
 This project is intended to be a safe, welcoming space for collaboration, and
 contributors are expected to adhere to the
 [code of conduct](https://github.com/mvysny/tuile/blob/master/CODE_OF_CONDUCT.md).

data/book/02-repaint.md

@@ -10,7 +10,7 @@ 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.
+bookkeeping a UI toolkit would normally need.
 
 ## Components invalidate; they never paint the terminal
 
@@ -44,21 +44,37 @@ 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:
+Eventually the screen does call a component's {Tuile::Component#repaint},
+handing it a {Tuile::Canvas}. Even then, the component does not write to
+the terminal. It writes styled cells through the canvas, which puts them
+in the screen's **back buffer** — a {Tuile::Buffer}, an in-memory grid of
+styled cells mirroring the terminal. Three methods:
 
 ```ruby
-screen.buffer.set_text(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
+def repaint(canvas)
+  canvas.set_text(0, 0, styled_string)      # a run of text
+  canvas.set_char(4, 1, grapheme, style)    # one cell
+  canvas.fill(local_rect)                   # a blank region
+end
 ```
 
 That's the entire painting vocabulary. A component's `repaint` computes
-what its rectangle should look like and stamps it into the buffer. No
+what its rectangle should look like and stamps it through the canvas. No
 cursor moves, no color escapes, no `print` — just cells into a grid.
 
+Note the coordinates: `(0, 0)` is the component's **own** top-left, not
+the screen's. The canvas arrives positioned at the component's rectangle
+and offsets every write, so a `repaint` never mentions where on screen it
+sits — which is why `canvas.fill(local_rect)` above, and not
+`canvas.fill(rect)`.
+
+Those are the component's *own* coordinates, and they are the only ones
+it deals in. Its `rect` is measured inside its parent (chapter 3), a
+mouse event arrives counted from its corner (chapter 5), and the cursor
+position it reports is counted the same way. Nothing a component writes
+names where it sits on the terminal — and when you genuinely need that,
+`absolute_rect` and `to_screen` sum the offsets for you.
+
 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
@@ -80,15 +96,15 @@ invalidated set and draws it in a specific order:
    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.
+   No layer clips another, and there is 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.
+no z-buffer, no clip stack to push and pop. 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
 
@@ -123,9 +139,21 @@ 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
+The "never outside" half keeps siblings from corrupting each other, and
+Tuile enforces it rather than trusting you to get it right. {Tuile::Screen}
+bounds every component by its own `rect` and by every ancestor's, so a
+write past yours is dropped before it reaches the screen. A bug here
+therefore shows up as *your* widget looking truncated, never as someone
+else's cells going strange — which is much harder to trace back to
+whoever caused it.
+
+That bound is also what lets a parent hand out a rectangle it doesn't
+intend to show in full. A scrolling viewport gives its forty-row child
+all forty rows and shows five; the child paints normally, knowing
+nothing about it, and the thirty-five that don't fit go nowhere. It
+changes nothing about the rule you follow here.
+
+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.

data/book/03-layout.md

@@ -1,10 +1,10 @@
 # 3. Layout: the parent sets the size
 
-In chapter 1 every component gained a `rect` — its absolute position
-and size on the screen. In chapter 2 we saw that a component is
-responsible for painting every cell of that `rect` and nothing outside
-it. This chapter answers the question those two left open: **who decides
-what a component's `rect` is?**
+In chapter 1 every component gained a `rect` — its position and size
+*inside its parent*. In chapter 2 we saw that a component is responsible
+for painting every cell of that rectangle and nothing outside it. This
+chapter answers the question those two left open: **who decides what a
+component's `rect` is?**
 
 The answer is a single rule, and the rest of the chapter is about why
 that one rule is enough:
@@ -28,12 +28,20 @@ Every container positions its children by computing their rectangles
 from its own. A two-pane split is arithmetic:
 
 ```ruby
-left.rect  = Tuile::Rect.new(rect.left, rect.top, rect.width / 2, rect.height)
-right.rect = Tuile::Rect.new(rect.left + rect.width / 2, rect.top,
-                             rect.width - rect.width / 2, rect.height)
+half = width / 2
+left.rect  = Tuile::Rect.new(0, 0, half, height)
+right.rect = Tuile::Rect.new(half, 0, width - half, height)
 ```
 
-Notice there is no negotiation. `left` does not announce a desired
+Notice what is *absent*: this container never mentions where it sits.
+A child's rect is measured from the parent's own top-left, so `(0, 0)`
+is "my corner," not the terminal's — the same coordinates chapter 2's
+`repaint` paints in. Move the container and its whole subtree moves with
+it, no arithmetic re-run. When you do need to know where something
+landed on screen — to hang an overlay off a field, say — you ask:
+`field.absolute_rect` sums the offsets up the parent chain for you.
+
+Notice also there is no negotiation. `left` does not announce a desired
 width that the parent then reconciles against `right`'s desired width.
 The parent simply *decides*, and the two children fill exactly the
 rectangles they are given. If new content arrives that is too tall for
@@ -156,17 +164,18 @@ So staying simple isn't a compromise you're tolerating. On this medium
 it is the *correct* fit, and the elaborate alternative would degrade the
 common case, debuggability, and auditability all at once.
 
-## Placing children: `Layout::Absolute`
+## Placing children: subclass `Layout`
 
-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, 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.
+The place you actually write layout code is a `relayout` override. The
+base class for this is `Tuile::Component::Layout`: it inherits
+all the focus, key-dispatch and mouse-routing wiring, paints nothing
+itself, and asks only that you position your children. The framework
+calls `relayout` whenever anything that feeds your arithmetic changed —
+your own rectangle, a child added, removed or hidden — which covers
+startup, every resize, and every mutation in between.
 
 ```ruby
-class SplitPane < Tuile::Component::Layout::Absolute
+class SplitPane < Tuile::Component::Layout
   def initialize
     super
     @sidebar = Tuile::Component::List.new
@@ -175,14 +184,14 @@ class SplitPane < Tuile::Component::Layout::Absolute
     add(@main)
   end
 
-  def rect=(new_rect)
-    super
+  protected
+
+  def relayout
     # 40 / 60 split — resolved to exact integers, remainder assigned
     # explicitly to the right pane so no column is ever lost.
-    left_w = rect.width * 4 / 10
-    @sidebar.rect = Tuile::Rect.new(rect.left, rect.top, left_w, rect.height)
-    @main.rect    = Tuile::Rect.new(rect.left + left_w, rect.top,
-                                    rect.width - left_w, rect.height)
+    left_w = width * 4 / 10
+    @sidebar.rect = Tuile::Rect.new(0, 0, left_w, height)
+    @main.rect    = Tuile::Rect.new(left_w, 0, width - left_w, height)
   end
 end
 ```
@@ -198,27 +207,58 @@ method — collapse the sidebar below some width, give the main pane
 everything:
 
 ```ruby
-  def rect=(new_rect)
-    super
-    if rect.width < 60
-      @sidebar.rect = Tuile::Rect.new(0, 0, 0, 0)          # hidden
-      @main.rect    = rect
+  def relayout
+    if width < 60
+      @sidebar.rect = Tuile::Rect.new(0, 0, 0, 0)          # collapsed
+      @main.rect    = local_rect
     else
-      left_w = rect.width * 4 / 10
+      left_w = width * 4 / 10
       # …as above
     end
   end
 ```
 
+Note `local_rect` rather than `rect`: a rectangle is measured *inside*
+its parent, so a container divides its own rectangle moved to the origin
+and never adds its own position back in.
+
+One more rule, and it is the whole of the deferral story: **`relayout`
+is never called from inside the mutation that needs it.** Mutating marks
+the container, and the framework runs the pass once, at the end of the
+event that did the mutating. So your `relayout` always sees a container
+whose own bookkeeping is finished, twenty `add`s cost one pass, and you
+may write your own mutators in whatever order reads best. The one thing
+it costs: a rectangle read in the *same* turn that dirtied it is still
+the old one. If you need it now — a spec, or a container assembled
+before any screen exists — call `flush_layout`:
+
+```ruby
+form.add(field)
+form.flush_layout
+field.rect          # assigned, rather than whatever it had before
+```
+
 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.
 
+When the rectangles don't depend on the container's size at all, there
+is nothing to compute, and `Layout::Absolute` holds a fixed `Rect` per
+child instead. Moving a child is `constrain`, not a write to its `rect`,
+because the layout's `relayout` is still what assigns it:
+
+```ruby
+board = Tuile::Component::Layout::Absolute.new
+board.add(title, Tuile::Rect.new(0, 0, 40, 1))
+board.add(body,  Tuile::Rect.new(0, 2, 40, 10))
+board.constrain(body, Tuile::Rect.new(0, 2, 40, 20))
+```
+
 ## 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
+A hand-written `relayout` 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=`:
 
@@ -311,7 +351,7 @@ 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,
+two-pane `SplitPane` 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.
 
@@ -337,23 +377,32 @@ form.add(pair,   Fixed[2])                              # blank row around the p
 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`
+### Capping a proportion
 
-The boxes are sugar, not a replacement, and they can't say everything. A **cap
-on a proportion** is the case to recognise:
+"A third of the width, but never more than 16 columns" is a proportion with a
+bound, and a `Percent` takes one with `clamp` — the same `Range` that
+`Integer#clamp` takes:
 
 ```ruby
-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
+row.add(sidebar, Percent[33].clamp(..16))    # a third, but never more than 16
+row.add(list,    Percent[33].clamp(20..40))  # a third, but never <20 or >40
+row.add(log,     Expand[1])                  # takes what the cap gave up
 ```
 
-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).
+The cells a cap gives up are simply unassigned, so an `Expand` beside it picks
+them up. A floor is best-effort: when the box runs out, it still starves
+children in declaration order, clamped or not. Only a `Percent` clamps: a
+`Fixed` is already exact, and an `Expand`'s share depends on its siblings, so a
+cap would have to hand cells back to them — a whole-group calculation rather
+than a bound on one child.
+
+### When to keep your own `relayout`
+
+The boxes are sugar, not a replacement. Anything that isn't a stack — a child
+overlapping another, a position computed from something other than the space
+available — belongs in a `Layout` subclass. Nest it inside a box so only the
+awkward region carries any arithmetic. `examples/sampler.rb` started with 59
+hand-written rectangles; ported to boxes and clamps, it has none left.
 
 ## Geometry: `Point`, `Size`, `Rect`
 
@@ -498,8 +547,8 @@ once.
 
 You've already seen the mechanism without the plumbing: when the
 terminal resizes, the framework reassigns rectangles from the root down,
-and your `rect=` override recomputes its children. That's the *only*
-thing you do to be resize-aware — recompute in `rect=`. Do **not**
+and your `relayout` override recomputes its children. That's the *only*
+thing you do to be resize-aware — recompute in `relayout`. Do **not**
 install your own `SIGWINCH` handler; only one handler can win and the
 framework owns it. Chapter 4 covers how the resize event travels through
 the event queue and why it's handled there rather than off the signal.
@@ -528,5 +577,5 @@ sizes automatically, it's on the road back to the constraint solver.
 
 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.
+supplied, and they hand them down through the same `relayout`. No child is
+ever consulted.

data/book/04-event-loop.md

@@ -128,8 +128,9 @@ loop thread might be reading it mid-repaint.
 
 Note the division of error handling. A block you `submit` runs *inside*
 the loop, so if it raises, the exception flows through the loop's error
-path — {Tuile::Screen#on_error}, which by default re-raises and tears the
-app down loudly (unhandled exceptions are bugs; surface them). But a raise
+path — {Tuile::Screen#on_error}, which while *empty* re-raises and tears the
+app down loudly (unhandled exceptions are bugs; surface them); register a
+listener there and it takes the error instead. But a raise
 in your background thread *before* `submit` — in the `slow_http_fetch`
 itself — is yours to catch; it's your thread, and Tuile never sees it.
 Wrap the slow work in your own `rescue` and `submit` an error display if
@@ -188,28 +189,28 @@ class Spinner < Tuile::Component::Label
 
   protected
 
-  def on_attached
+  def handle_attached
     @ticker = screen.event_queue.tick_fps(8) { |n| self.text = FRAMES[n % FRAMES.size] }
   end
 
-  def on_detached
+  def handle_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
+`handle_attached` fires the moment this component's tree is mounted on the
+screen; `handle_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.**
+The contract is a mirror: **`handle_attached` starts what `handle_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
+to another gets `handle_detached` and then `handle_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.
+`handle_attached` you must release in `handle_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
@@ -226,11 +227,11 @@ class BuildStatus < Tuile::Component::Label
 
   protected
 
-  def on_attached
+  def handle_attached
     @subscription = @service.on_change { |s| screen.event_queue.submit { self.text = s } }
   end
 
-  def on_detached
+  def handle_detached
     @subscription&.unsubscribe
     @subscription = nil
   end
@@ -245,16 +246,16 @@ 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
+your `main` gives every component still on screen its `handle_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
+installs no `at_exit`. If your `handle_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
+`handle_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.
 
@@ -271,8 +272,8 @@ the loop thread — where re-laying-out the tree (chapter 3) is safe.
 This is why chapter 3 told you never to install your own `SIGWINCH`
 handler: only one handler can win, and the framework's owns it. You react
 to resize the normal way — recompute your children's rectangles in your
-`rect=` override — and the framework calls it for you when the resize
-event is processed.
+`relayout` override — and the framework calls it for you when the resize
+event has been processed.
 
 One consequence worth knowing: the screen's size is valid *before* the
 first resize ever happens. `Screen.instance.size` is seeded at