tuile 0.13.0 → 0.14.0

data/README.md

@@ -6,25 +6,16 @@ and Tuile runs a single-threaded event loop that dispatches keys and mouse
 events, then repaints everything that was invalidated since the last tick. The
 name is French for "roof tile": small pieces that compose into a larger whole.
 
-The design philosophy — "boxes within boxes" that talk via listeners and data
+The design philosophy — "composing components in layouts to create something bigger" that talk via listeners and data
 providers — is described in
 [component-oriented programming](https://mvysny.github.io/component-oriented-programming/).
 Tuile is that approach applied to a terminal.
 
-If you have looked at the alternatives:
-
-- [tty-toolkit](https://ttytoolkit.org/) (`tty-prompt`, `tty-cursor`, …) is a
-  set of low-level building blocks rather than a framework: there is no
-  component tree, no event loop, no invalidation. Tuile sits on top of
-  `tty-cursor`/`tty-screen` and adds the framework layer.
-- [vedeu](https://github.com/gavinlaking/vedeu) is the closest Ruby comparable
-  but is no longer maintained (last release 2017).
-- [ratatui](https://github.com/ratatui/ratatui) is the popular TUI framework
-  in the Rust ecosystem; its immediate-mode API is closer to `tty-prompt` than
-  to Tuile's retained component tree.
-
 Tuile is the only actively maintained component-oriented TUI framework for
-Ruby that we are aware of.
+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.
 
 ## Installation
 
@@ -64,6 +55,9 @@ 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
+  bindings first.
 
 ## Hello world
 
@@ -149,7 +143,9 @@ status-bar hints — plus whatever `custom` tokens your app adds. 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
-re-picks on a live OS appearance flip.
+re-picks on a live OS appearance flip. The probed background is also yours to
+read — `Screen#background_color` — for panes tinted a few percent off the
+terminal's own, LazyVim-style.
 → [chapter 6](book/06-theming.md)
 
 ## Components
@@ -174,6 +170,7 @@ carries the per-method reference: `bundle exec rake yard`, or
 | component | what it is |
 |---|---|
 | `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. |
 | `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). |
@@ -224,11 +221,14 @@ carries the per-method reference: `bundle exec rake yard`, or
 
 | component | what it is |
 |---|---|
-| `Popup` | The modal overlay host: it wraps any component, paints nothing itself, and is sized by `size=` (a `Size` or a `Fraction` of the screen) rather than by its content. ESC or `q` dismisses. |
+| `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. |
-| `InfoWindow` | A `Window` of static lines, tiled or popped up. For read-only information you don't want to assemble by hand. |
+| `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. |
-| `LogWindow` | A scrolling log view. Point your logger at a `LogWindow::IO` and lines land here from any thread, marshalled through the event queue. |
+| `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. |
 
 The mixins those share — `HasValue` (the `value` / `empty?` / `clear` /
 `on_value_change` seam every input speaks), `HasContent` (one-child
@@ -252,7 +252,7 @@ interface:
 ```ruby
 Tuile.logger = Logger.new($stderr)              # or:
 Tuile.logger = TTY::Logger.new                  # duck-typed, works directly
-Tuile.logger = Logger.new(Tuile::Component::LogWindow::IO.new(window))
+Tuile.logger = Logger.new(Tuile::Component::LogTextView::IO.new(view))
 ```
 
 ## Testing

data/TERMINOLOGY.md

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

data/book/03-layout.md

@@ -160,8 +160,9 @@ common case, debuggability, and auditability all at once.
 
 The place you actually write layout code is a `rect=` override. The base
 class for this is `Tuile::Component::Layout::Absolute`: it inherits all
-the focus and key-dispatch wiring, paints nothing itself, and asks only
-that you position your children whenever your own rectangle is assigned —
+the focus, key-dispatch and mouse-routing wiring, paints nothing itself,
+and asks only that you position your children whenever your own rectangle
+is assigned —
 which happens once at startup and again on every resize.
 
 ```ruby
@@ -396,24 +397,24 @@ class Fraction < Data.define(:width, :height)   # each a float in 0.0..1.0
 end
 ```
 
-A popup's size is set with `Popup#size=`, which accepts either a
+A popup's box is set with `Popup#declared_size=`, which accepts either a
 `Fraction` (resolved against the screen at layout time, so it tracks
 resize) or an absolute `Size` (clamped to the screen):
 
 ```ruby
 popup = Tuile::Component::Popup.new(content: some_window)
-popup.size = Tuile::Fraction::HALF     # the default — half the screen, centered
-popup.size = Tuile::Fraction::FULL     # fullscreen
-popup.size = Tuile::Fraction.new(0.8, 0.5)          # 80% wide, half tall
-popup.size = Tuile::Size.new(50, 12)                # exact, clamped to screen
+popup.declared_size = Tuile::Fraction::HALF     # the default — half the screen, centered
+popup.declared_size = Tuile::Fraction::FULL     # fullscreen
+popup.declared_size = Tuile::Fraction.new(0.8, 0.5)          # 80% wide, half tall
+popup.declared_size = Tuile::Size.new(50, 12)                # exact, clamped to screen
 ```
 
 The default is `Fraction::HALF`, resolved on every layout pass, so a
 popup you never size at all is half-screen and follows the terminal as
 it resizes. `Fraction::FULL` is the fullscreen shorthand.
 
-A subtle but important point: `size=` is **authoritative, not a
-preference**. The name is `size`, not `preferred_size`, on purpose.
+A subtle but important point: `declared_size=` is **authoritative, not a
+preference**. The name says *declared*, not *preferred*, on purpose.
 There is no parent that might negotiate it downward — the screen simply
 *applies* what you asked for (clamping an oversized absolute `Size` to
 fit). Calling it a preference would invite a future "well, the parent
@@ -434,7 +435,7 @@ wrong for a paragraph.
 > height) and it isn't even reliably pretty — a single long line
 > collapses the popup to one row. Half-screen-and-wrap sidesteps all of
 > it. When you genuinely know the right size — an autocomplete dropdown
-> whose items you own — you set it yourself: `popup.size =
+> whose items you own — you set it yourself: `popup.declared_size =
 > Tuile::Size.new(longest_item, [items.size, 8].min)`. That's still
 > caller-decides, top-down.
 
@@ -482,6 +483,12 @@ A component in the footer slot always fills the width — there is no
 sizing policy to configure, because the window already knows its inner
 width and that's the only dimension a bottom-row widget needs.
 
+The word *slot* is literal here: the footer is a
+{Tuile::Component::Slot}, the one-child region you'd use for the same job
+in a container of your own (chapter 7). That's why `footer=` needs no
+sizing argument and why setting it to `nil` restores the border cleanly —
+the region stays in the tree either way, occupied or not.
+
 The two are mutually exclusive by precedence: if a `footer=` component
 is present it occupies the bottom row and `footer_text` is hidden;
 otherwise `footer_text` embeds into the border. No window needs both at

data/book/05-focus.md

@@ -45,7 +45,10 @@ decoration; clicking one shouldn't yank focus away from the window around
 it. Controls that accept input (a text field, a list, a button) override
 it to `true`. This gate is what makes click-to-focus sane: clicking lands
 focus on the component under the cursor *only if it's focusable*,
-otherwise the click is ignored for focus purposes. The same rule governs
+otherwise the click is ignored for focus purposes. A click descends the
+tree — every component whose rectangle contains the point sees it, outermost
+first — so "the component under the cursor" is really all of them, and focus
+settles on the deepest focusable one. The same rule governs
 the automatic focus-forwarding a container does when it's focused — a
 window handed focus passes it down to its content, but only if that
 content is focusable.

data/book/06-theming.md

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

data/book/07-components.md

@@ -674,6 +674,39 @@ window.content = Component::List.new.tap { _1.lines = entries }
 window.scrollbar = true
 ```
 
+### Reserving a region: `Slot`
+
+A `Window` has one content region. When *you* build a container with
+several — a dialog with a message, a button row and maybe a header — give
+each region a {Tuile::Component::Slot}: a component whose whole job is to
+hold one child and size it to itself.
+
+```ruby
+@message = Component::Slot.new
+add(@message, Expand[1])              # the region, wired once at construction
+@message.content = Component::Label.new("Delete this file?")   # the occupant
+```
+
+The reason to bother is an arithmetic problem you'd otherwise have to
+solve. Children are ordered, and order decides paint order and Tab order —
+so if you held the message and the buttons as direct children, "where does
+the message get inserted?" would depend on whether the header happens to be
+present right now. Inside a slot the answer is always index 0, because the
+slot itself never leaves the tree. Add regions, reorder them, leave some
+empty: none of it changes a swap.
+
+Which leads to the one thing that surprises people: **an empty slot doesn't
+collapse.** It keeps the rectangle its parent gave it and clears it, so a
+dialog with no message shows the hole — exactly as it would with an *empty*
+message. If you want the gap closed, that's the parent's arithmetic (give
+the slot a zero extent), which is the same top-down rule as everything else
+in chapter 3. Don't detach the slot to make it go away; that hands you back
+the insert-index problem it exists to remove.
+
+A slot is invisible to input: it can't take focus, clicks pass straight
+through to the occupant, and when an occupant leaves, the focus repair is
+handed up to your container rather than stranding focus on the slot.
+
 ## Switching between views
 
 When a screen has more content than fits and the parts are *alternatives*
@@ -1008,22 +1041,24 @@ every GUI dismisses its menus on a window resize too.
 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`
+itself to its content**: its box is set by `declared_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
+A popup is **always modal**: 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.
-
-**A left click outside a popup closes it**, modal or not — the same light
-dismissal a desktop dialog gives you. It's a per-popup switch,
-`close_on_outside_click`, on by default; a popup that must survive stray
+input inside itself. For a layer that floats *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 — use its base class, `Overlay`,
+directly. An `Overlay` is a Popup minus the modality: same open/close
+lifecycle, same outside-click dismissal, but it sits at the rect you assign
+and never disturbs focus or key dispatch.
+
+**A left click outside an overlay closes it**, modal or not — the same light
+dismissal a desktop dialog gives you. It's a per-overlay switch,
+`close_on_outside_click`, on by default; one that must survive stray
 clicks turns it off, as a Notification does. The click still reaches
 whatever was beneath it, unless an open modal swallowed it — in which case
 the first click dismisses and a second one acts.
@@ -1050,6 +1085,116 @@ A nested TextField still swallows printable keys first, so typing `q` into
 a field inside a popup doesn't dismiss it — the popup's own `q` handler sits
 on the ancestor, and only sees keys the field declined.
 
+## The confirm dialog
+
+That Window-in-a-Popup assembly is how you build any dialog. One dialog is
+so common it comes pre-assembled: {Tuile::Component::ConfirmWindow}, the
+"are you sure?" box — a caption, a short message, a row of buttons.
+
+```ruby
+Component::ConfirmWindow.confirm("Delete Report Q4?", "This cannot be undone.",
+                                 confirm: "Delete") { delete! }
+```
+
+```
+              ┌Delete Report Q4?───────────┐
+              │ This cannot be undone.     │
+              │                            │
+              │    [ Delete ]  [ Cancel ]  │
+              └────────────────────────────┘
+```
+
+Three factories cover the shapes you'll actually write: `alert(caption,
+message)` is the one-button acknowledgement, `confirm` the two-button
+question — its labels are keywords, so it is also your OK/Cancel and
+Delete/Cancel — and `yes_no` the other canonical phrasing. That's
+deliberately the whole list: Windows' `MessageBoxButtons` enum grew six
+values by naming every label pair, and any set the factories don't cover is
+a few lines of the builder below.
+
+### Why a block, and not an answer
+
+Everyone's first instinct here is the blocking call — `if confirm?("Delete?")`
+— because that's what Swing's `JOptionPane`, tkinter's `askyesno` and GTK's
+`dialog.run` all offer. Tuile can't, and it's worth understanding why: the
+whole UI runs on one thread (chapter 4), so a call that *waits* for the
+answer would have to nest a second event loop inside the first, re-entering
+raw mode under a key thread that's already reading stdin. The dialog
+therefore takes callbacks: the block is the action, and the dialog returns
+immediately.
+
+### One kind of way out
+
+Every button closes the dialog. A button *with* a block then fires it; a
+button *without* one is a Cancel. And ESC, `q`, a click outside the box and
+that Cancel button are all the same event — `on_dismiss`, fired exactly
+once, and only when no action button was chosen. You never write a `case`
+over outcomes, and you never have to enumerate the ways out: there is the
+action you asked about, and there is "do nothing", however the user spells
+it.
+
+There is deliberately no way to keep the dialog open after a press. A
+dialog that leads somewhere — "Copy files" showing a progress window —
+opens the next window *from its callback*, which is safe because the block
+fires after the dialog has already closed and focus has been repaired.
+
+For any other button set, the component is its own builder — buttons are
+declared one at a time, each a caption and an optional block:
+
+```ruby
+dialog = Component::ConfirmWindow.new("Unsaved changes")
+dialog.message = "Save your changes before leaving?"
+dialog.button("Save")    { save! }
+dialog.button("Discard") { discard! }
+dialog.button("Cancel")            # no block: pressing it dismisses
+dialog.on_dismiss = -> { stay_put }
+dialog.open
+```
+
+### Keys, and the underlined letters
+
+Focus opens on the first button — which, since Enter presses the *focused*
+button, makes it the default. Left/Right and Tab walk the row; Enter or
+Space press.
+
+Each button also answers to a **mnemonic**: a letter, underlined in its
+caption, that presses the button from anywhere in the dialog. By default
+it's the caption's first letter (Save gets `s`, Discard `d`), matched
+case-insensitively; pass `mnemonic:` to pick another letter — the case you
+give chooses which occurrence gets the underline — or `nil` for none. The
+underline isn't decoration: Tuile draws no status bar to advertise keys in,
+so the caption *is* the advertisement.
+
+Three letters are never mnemonics. `q` is unconditionally the do-nothing
+route out — a dialog that forces a choice only thinks it does, since the
+user can always Ctrl+C, and pretending there's no escape route just trains
+them to reach for it. And `g`/`G` belong to the message: the body scrolls
+*without taking focus* — Up/Down, PgUp/PgDn, Ctrl+U/D, Home/End and the
+less-style `g`/`G` are handed to it while a button keeps focus, so a long
+message reads without any focus gymnastics. The body is also a tab stop:
+Shift+Tab reaches it, so overflowing prose is visibly reachable, not
+secretly scrollable.
+
+### The popup that sizes itself
+
+Chapter 3 was firm that nothing in Tuile sizes itself to its content, and a
+plain Popup takes half the screen whatever it wraps — absurd around a
+one-line "Delete?". The confirm dialog is the sanctioned exception *shape*:
+it measures **content it owns** — its caption, its message, its buttons —
+and asks the screen for exactly that box, still capped at half the screen
+(a message longer than the cap wraps and scrolls). Assign a `Component` as
+the message and the measuring honestly gives up: injected content is not
+the dialog's to measure, so the popup takes the full half-screen box.
+
+### What it deliberately isn't
+
+The message is prose — a `String` or {Tuile::StyledString}, which on a TTY
+already covers color, emphasis and iconography — not a content slot. A
+dialog collecting *input* is not a confirm dialog: the moment you want a
+form, a picker or a diff view in there, you've outgrown the sugar, and the
+general mechanism is one line away — `Popup.new(content: your_layout)`,
+exactly as in the previous section.
+
 ## Notifications
 
 {Tuile::Component::Notification} is the one overlay you don't assemble at
@@ -1105,18 +1250,23 @@ 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::InfoWindow} — a Window with a read-only body, in one
+  of two presentations: `message=` is *prose*, wrapped by a scrollable
+  TextView; `lines=` is *rows*, a List keeping one item per row and
+  truncating — the choice for columnar output, where a wrap would destroy
+  the alignment. `InfoWindow.open(caption, body)` pops it up, picking the
+  presentation from the body's type (an Array is rows, text is prose).
 - {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:
+- {Tuile::Component::LogWindow} — a Window framing a
+  {Tuile::Component::LogTextView}: an auto-scrolling, scrollbar-equipped
+  TextView purpose-built for log output. The view is where the behavior
+  lives — compose it bare into a layout when you don't want the frame.
+  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 the view carries an `IO`-shaped adapter so you can point
+  a stdlib `Logger` (or a `TTY::Logger`) straight at either of them:
 
 ```ruby
 window = Component::LogWindow.new

data/book/08-testing.md

@@ -108,9 +108,25 @@ key, so you assert on that too:
 
 ```ruby
 list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
+```
+
+**A mouse test needs the component mounted, where a key test doesn't.** A
+click doesn't only *do* something, it also *focuses* — and
+{Tuile::Screen#focused=} refuses a component that isn't on the pane, so
+`handle_mouse` on a component you never attached raises "is not attached to
+this screen". Give it a tree first:
+
+```ruby
+screen.content = list                      # a click focuses; focus needs a tree
+list.rect = Rect.new(0, 0, 10, 5)
 list.handle_mouse(MouseEvent.new(:left, 5, 2))
 ```
 
+That applies to containers too, and to more of them than you might expect:
+a click descends to every child whose rect contains the point, so testing a
+window's footer by clicking it exercises the window, the footer's slot and
+the footer, all of which want to be attached.
+
 **High: go through the pane.** {Tuile::ScreenPane#handle_key} runs the
 dispatch rung from chapter 5 that routing is actually about: delivery to
 {Tuile::Screen#focused}, then the bubble up its ancestor chain to the scope

data/book/09-styled-text.md

@@ -29,7 +29,7 @@ tangle has to be re-untangled on every edit.
 {Tuile::StyledString} untangles it once, structurally. A styled string is
 a sequence of **spans**, each a maximal run of characters that share one
 complete {Tuile::StyledString::Style} — foreground, background, bold,
-italic, underline, strikethrough. The spans are non-overlapping and tile
+italic, underline, strikethrough, inverse. The spans are non-overlapping and tile
 the whole string: every character belongs to exactly one span, and that
 span's `style` *is* the character's style. There are no overlay layers to
 merge, no running state to reconstruct. "What's the style at column 5?"
@@ -100,8 +100,8 @@ by default.**
 
 Strict means it recognizes exactly the SGR codes that map to a
 {Tuile::StyledString::Style}'s attributes — the foreground and background
-colors, bold, italic, underline, strikethrough — and *raises* on anything
-else. An unmodeled attribute like blink or reverse video, an unknown SGR
+colors, bold, italic, underline, strikethrough, inverse — and *raises* on
+anything else. An unmodeled attribute like blink or conceal, an unknown SGR
 code, a non-SGR escape like a cursor move or an OSC sequence: all of them
 are a {Tuile::StyledString::ParseError}, not a shrug. The reason is a
 contract worth protecting: `parse(to_ansi(x)) == x`. If parsing silently

data/examples/file_commander.rb

@@ -82,7 +82,7 @@ module FileCommanderExample
       @on_cwd_changed&.call
     rescue SystemCallError => e
       @cwd = previous
-      Tuile::Component::InfoWindow.open("Cannot open", [path, e.message])
+      Tuile::Component::InfoWindow.open("Cannot open", "#{path}\n#{e.message}")
     end
 
     def load_entries