tuile 0.9.0 → 0.10.0

data/book/07-components.md

@@ -56,14 +56,36 @@ decision.
 ## Editing text
 
 When you need input back from the user, the two editable components share
-a base — {Tuile::Component::TextInput} — and differ only in shape.
+a base — {Tuile::Component::AbstractStringField} — and differ only in shape.
 
 {Tuile::Component::TextField} is a single line with a real hardware caret.
-It does not scroll; a keystroke that would push the text past the field's
-width is simply rejected, so the field always shows its whole contents.
-Because it owns the hardware cursor while focused, it's the component that
-triggers the cursor-ownership rule from chapter 5 — printable keys flow
-straight to it and sibling shortcuts stay muted while you type.
+Its width bounds what you can *see*, not what it can hold: the text scrolls
+horizontally, moving by the minimum needed to keep the caret in view. If you
+want an actual limit, set `max_text_length` — a cap in characters, after
+which typing quietly does nothing. Because it consumes every printable key
+while focused (including the ones it ignores at the cap), it's also what
+keeps a scope-wide key binding from firing while you type: as chapter 5
+explains, an ancestor only hears the keys its descendants declined.
+
+That cap counts *characters*, and the distinction matters more than it
+looks. A field position is either an index into the text or a column on the
+terminal, and the two coincide only while every glyph is one column wide —
+a fullwidth CJK character is two columns, a combining mark zero. So `caret`
+and `max_text_length` speak indices, while `rect`, `left_column` and a mouse
+click speak columns, and the field converts between them rather than
+assuming they're the same number. You don't need to think about this to use
+a TextField; you do the moment you write a component that paints text.
+
+There's a third unit hiding in there, and it's the one your *user* thinks
+in: the glyph they see. A single visible character can be several characters
+of storage — an `e` with a combining accent, a flag, an emoji family — and
+editing a field one storage character at a time is how you get a Backspace
+that strips the accent and leaves a bare `e`. So while `caret` counts
+characters, it may only ever sit *between* glyphs, and the editing keys work
+in glyphs too: one arrow press moves over one, one Backspace deletes one,
+however many characters that turns out to be. Assign a caret into the middle
+of a glyph and the field quietly moves it to that glyph's far edge — where
+it was already being drawn anyway.
 
 {Tuile::Component::TextArea} is the multi-line counterpart: a word-wrapping
 editor that scrolls vertically to keep the caret's line visible, with
@@ -71,6 +93,29 @@ Enter inserting a newline as in any text editor. Like everything else,
 it's sized by its parent — it does not grow to fit its content; text that
 overflows the rect is reached by scrolling.
 
+{Tuile::Component::PasswordField} is a text field that paints a mask —
+one `*` per character — instead of its text. Everything else is the text
+field's, unchanged: you edit it, click into it, and scroll it exactly the
+same way, and `value` hands back the plaintext whenever you ask. Setting
+`revealed = true` shows the real text; there's no in-field reveal button,
+because a terminal row has nowhere to put one, so apps wire that to a
+"show password" checkbox or a key of their own.
+
+Two of its details are worth knowing, because both come straight from the
+index-versus-column distinction above. The mask is one *single-column*
+glyph per character, which is why the default is a plain `*` rather than a
+prettier `•`: a bullet is one of those characters whose width depends on
+how the terminal is configured, and a mask that's occasionally two columns
+wide would put the caret in the wrong place. (You can still set
+`mask_char` yourself if you know your terminal.) And because the mask
+replaces each character with exactly one column, a masked CJK passphrase
+takes *fewer* columns than the plaintext would — which is fine, and the
+field's caret, scrolling and click handling all measure the mask rather
+than the hidden text. The one thing it deliberately does *not* do is
+protect the plaintext in memory: it's an ordinary Ruby string, and
+anything stronger is a job for a type the whole application cooperates
+with.
+
 Both inherit the same event hooks from the base, and this is where the
 design pays off: you customize an input by assigning callbacks, not by
 subclassing. `on_change` fires whenever the text changes; `on_escape`
@@ -92,6 +137,68 @@ left `nil`, let those keys *fall through* to the parent — that's how Enter
 in a search field can trigger the surrounding window's action while the
 field still handles ordinary typing.
 
+## The value seam
+
+Every input component — a text field today, a combo box or a date field
+tomorrow — answers the same handful of questions, so Tuile gives them a
+shared vocabulary: the {Tuile::Component::HasValue} mixin. Read or set
+`value`, ask `empty?`, `clear` it, and subscribe to `on_value_change`.
+Write code against that seam and it doesn't care which kind of input each
+field is.
+
+The idea worth internalizing is that **a component's `value` is of its own
+natural type, not a string**. A text field's value *is* its text (a
+`String` — `value` and `text` are two names for the one buffer, `text`
+reading better while you're editing prose). But a combo box's value is the
+*object you picked*, not the text shown for it — pick a `User` and you get
+the `User` back, even when two users render to the same name. That typing
+is free in Ruby: a "value" is just whatever you stored, there's no generic
+to declare, so Tuile leans into it rather than making everything a string
+you map back by hand.
+
+A typed value can relate to the text on screen in two different ways, and
+the input components show both. A combo box's value is kept *quite apart*
+from the text — you type a query, but the value is the object you pick. An
+{Tuile::Component::IntegerField}'s value is instead *derived from* the
+text: it holds an `Integer` (or `nil`), parsed from the buffer on demand.
+You may type only digits and at most one leading `-`; anything else is
+quietly refused without so much as nudging the caret, and Up/Down step the
+number by one (an empty field counting as zero). Read `value` and you
+get an `Integer`, or `nil` when the buffer is blank or only half a number
+(a lone `-`). It reports changes as you type, but only when the number
+*itself* changes — padding `7` out to `07` moves the text without moving
+the value, and stays silent.
+
+```ruby
+qty = Component::IntegerField.new
+qty.on_value_change = ->(n) { recompute(n) }  # n is an Integer, or nil
+qty.value = 3
+```
+
+Both the combo box and the integer field are built the same way, and it's
+worth seeing why: each *wraps* a text field rather than *being* one. A
+subclass would inherit the text field's `String`-typed value and wear it
+on its face right next to the real typed one — two conflicting answers to
+"what's your value?". Composing sidesteps that: the wrapper holds a text
+field privately, does its own filtering and parsing, and exposes only the
+value that makes sense for it. (This is the "configure a generic component
+to make a domain one" idea from the architecture the whole library is
+built on.)
+
+The password field is the same rule read the other way. Its value *is* its
+text — same type, same vocabulary — so there's no second seam to collide
+with, and it simply *is* a text field, subclassed to paint differently.
+That's the test when you build your own input: if what you hand back
+differs in type from what the user types, wrap a field; if it's the same
+thing shown another way, extend one.
+
+Turning a field's value into a domain model — parsing, validation, the
+box-holds-a-`String` ⟷ bean-holds-an-`Integer` conversion — is
+deliberately *not* the field's job; it belongs to a forms/binder layer
+that will one day sit above these components. So the seam is kept thin on
+purpose: `on_value_change` carries just the new value, and there's no
+read-only or required flag yet. Room left for that layer to grow into.
+
 ## Choosing from a set
 
 {Tuile::Component::List} is the workhorse: a scrollable column of
@@ -126,11 +233,258 @@ list.cursor = Component::List::Cursor.new
 list.on_item_chosen = ->(index, line) { open(entries[index]) }
 ```
 
+When the set is long and the user roughly knows what they want, a plain
+list makes them scroll for it. {Tuile::Component::ComboBox} is the answer:
+a text field with a dropdown that filters as you type. Hand it `items` (of
+any type) and, when their `to_s` isn't what you want shown, an
+`item_label` strategy to render each one; type to narrow, arrow to move,
+Enter or click to accept. It's the value seam doing real work — its
+`value` is the selected *item*, the object and not its label, so a combo
+over `User`s hands back a `User`. The field's text is merely a transient
+query: it reverts to the selection's label when you dismiss the dropdown,
+and only a real commit fires `on_value_change`. The dropdown itself is a
+borderless popup tinted apart from the content beneath it (chapter 6's
+background inheritance again), floating below the field or flipping above
+when it's near the bottom of the screen.
+
+```ruby
+combo = Component::ComboBox.new
+combo.items = User.all
+combo.item_label = ->(u) { u.full_name }
+combo.on_value_change = ->(u) { show(u) }
+```
+
+When the choice is simply yes-or-no, {Tuile::Component::Checkbox} is a
+single row — `[x] Enable syslog forwarding` — that Space or a left-click
+flips. Its `value` is the value seam again, at its simplest: always `true`
+or `false`, never `nil`. Unchecked is the *empty* value, so a fresh
+checkbox reports `empty?` and `clear` unchecks it. Because `value` reads a
+little colorlessly in application code, the same state answers to
+`checked?`, `checked=` and `toggle` — four names, one piece of state, and
+one write path, so your `on_value_change` listener fires exactly once
+however you flip it.
+
+```ruby
+cb = Component::Checkbox.new("Enable syslog forwarding", value: true)
+cb.on_value_change = ->(on) { config.syslog = on }
+cb.toggle       # unchecks it, firing the listener with false
+```
+
+Two of its choices are worth understanding, because they're really
+statements about how Tuile widgets behave in general. The first: **Enter
+does nothing.** A checkbox has no action to confirm — Space is the native
+gesture for flipping one — so Enter is left unhandled, and by chapter 5's
+rules it bubbles up to an ancestor. It's tempting to read that as a
+guarantee, as though the framework kept Enter clear for a form's
+submit button. It doesn't, and chapter 5's table shows why: a text area
+claims Enter for a newline, a button claims it to activate itself. Whether
+Enter reaches your form depends on the widget that has focus. A checkbox
+declines it because it has nothing to do with it — which is a fact about
+this widget, not a promise about all of them.
+
+The second is about *where the widget actually is*. A form column will
+happily hand a checkbox forty columns for a caption that needs twenty-two,
+and the extra eighteen are blank. Both the focus highlight and the click
+target stop at the end of the caption rather than filling the row — the
+painted glyph is the affordance, so a click that visibly lands on nothing
+must not toggle anything, and a full-width highlight band would read as a
+selected *row*, which is the wrong signal for one field among ten.
+(Clicking the blank tail still moves *focus* there; it's the field's row,
+after all.) {Tuile::Component::Button} follows the identical rule, which is
+why both expose that painted region as `extent`.
+
+The glyphs are plain ASCII — `[x] ` and `[ ] `, three columns and a space
+— rather than the prettier `☑`/`☐`. Not for the column-width reason you
+might expect: those box characters genuinely measure one cell everywhere. They're simply missing from most monospace fonts, and missing
+*asymmetrically* — `☐` is the worse-covered of the two, so the unchecked
+state can degrade to tofu while the checked one renders, which reads as a
+bug rather than a fallback.
+
+When the user should pick *several* things from a handful,
+{Tuile::Component::CheckboxGroup} stacks those rows into one widget: a
+cursor moves with the arrows, Space toggles the row it sits on, and `value`
+is the `Set` of items you selected.
+
+```ruby
+levels = Component::CheckboxGroup.new(items: LogLevel.all)
+levels.item_label = ->(l) { l.name }
+levels.on_value_change = ->(set) { refilter(set) }   # a Set of LogLevels
+```
+
+Notice what `value` holds: the *items*, exactly as the combo box does — a
+group over `LogLevel`s hands back `LogLevel`s, so filtering is
+`selected.include?(level)` and never a lookup from a label back to the
+thing it named. A `Set` rather than an array, because the selection has no
+inherent order — which brings a wrinkle worth knowing up front. The set
+iterates in the order things were *toggled*, so if you need the order the
+rows are shown in, ask for it: `items & value.to_a`. Treat the set as
+unordered and you'll never be surprised.
+
+The set is also **frozen**. That's deliberate, and it's the one thing that
+can bite you if you don't expect it: `group.value << item` raises rather
+than quietly working. It has to, because a listener that fires on change
+can only notice a change if the value is *replaced* rather than edited in
+place — mutate the set you were handed and the group would have no way to
+tell anyone. So assign a new selection instead (an array is fine, it's
+coerced), and let the widget's own toggling build the new sets for you.
+
+Here the cursor and the selection are genuinely two different things — the
+cursor says *where you are*, the checkmarks say *what you picked* — and
+that shape is exactly what a list already provides. So a checkbox group
+doesn't paint rows itself; it holds a {Tuile::Component::List} and gets the
+cursor, the scrolling, the scrollbar and the per-row mouse handling for
+free, in the same "wrap a generic component to make a domain one" way the
+combo box wraps a text field. That inheritance goes further than
+convenience: a click anywhere on a row toggles it, and Enter toggles the
+cursor's row, because those are the list's own gestures for choosing an
+item.
+
+Which is worth pausing on, because it looks like a contradiction of what
+you just read about the standalone checkbox, where a click on the blank
+space past the caption pointedly does *not* toggle. Both are right, and the
+difference is what the user is aiming at. A lone checkbox in a form column
+is a small painted thing surrounded by emptiness — the glyph is the
+target. A row in a list is a *row*: it highlights across its full width, so
+its full width is what you can click. The rule didn't bend; the thing being
+clicked changed.
+
+One thing the group deliberately does *not* do is reconcile `items` against
+`value`. Replacing the items changes only what's on screen — the selection
+is left exactly as it was, even if some of it is now invisible, and no
+change event fires. It sounds careless until you picture a form: a user
+ticks three boxes, some code refreshes the item list, and a selection
+silently narrows itself. The user saves without touching anything and has
+just changed data they never edited. Keeping `value` authoritative means
+that can't happen, and reconciling — when you actually want it — is a line
+of your own: `group.value &= group.items.to_set`. The combo box makes the
+identical promise for its single value.
+
+When exactly one of a handful will do, {Tuile::Component::RadioGroup} is
+the same widget with a single answer.
+
+```ruby
+sort = Component::RadioGroup.new(items: SORT_ORDERS)
+sort.item_label = ->(order) { order.label }
+sort.on_value_change = ->(order) { resort(order) }
+```
+
+Its `value` is the selected item — the object, not its label, as always —
+and `nil` when nothing is selected, which is where a fresh group starts.
+That `nil` is also the only way back out: Space on the row that's already
+selected does nothing, because a radio group has no deselect gesture. If
+"none of these" is a legitimate answer, give it a row of its own. Items
+are chrome here too, with the same reasoning as above: replacing them
+never touches `value`, and a selection that's no longer among the rows
+simply shows nothing marked.
+
+The interaction is worth dwelling on, because it deliberately breaks with
+the desktop convention. In a graphical radio group the arrow keys move the
+*selection*: press Down and you have chosen the next option. Tuile splits
+the two. The arrows move a cursor, and you select with Space, Enter or a
+click — the same gestures as the checkbox group above.
+
+Two reasons, the second of which decides it. First, consistency: "a cursor
+roams, Enter chooses" is how every list-shaped thing in Tuile behaves, and
+two group widgets sitting one Tab apart in the same form must not answer
+Down differently. Second, and more practically, selection-follows-arrows
+fires your listener once per row you cross. Arrow from the first option to
+the fifth, and a listener that re-sorts a table, refetches a page or
+rewrites a config file does that work four times — three of them for
+choices the user never made. Committing on a keystroke means it happens
+once, when it was meant.
+
+So the cursor is *chrome*: presentation state, like `items`, rather than
+part of the value. Assigning `value` doesn't move it, and the two
+indicators say two different things — the `(*)` marks what's selected and
+is always visible, while the highlighted row marks where you are and fades
+when focus leaves. The one thing that *does* move the cursor is `items=`,
+which pulls it back into range when the row set shrinks beneath it.
+
+The glyphs are `(*) ` and `( ) `, and this time the reason is the column
+width the checkbox section set aside. A filled bullet — `(•)` — is the
+nicer mark, but U+2022 is one of Unicode's East-Asian *ambiguous* width
+characters: a terminal configured for CJK text draws it two cells wide, a
+Western one draws it in a single cell, and a program cannot ask which it's
+talking to. Guess wrong and every row's text sits one column off — not a
+cosmetic blemish but a coordinate error, since Tuile computes every rect
+and clip from the width it believes each character has. Tuile bets on
+one cell, and keeps the set of characters riding on that bet small enough
+to enumerate, so a new widget reaches for ASCII and offers the pretty
+glyph only where someone can opt in knowing their terminal.
+
 For a discrete action rather than a selection, {Tuile::Component::Button}
 is a one-row `[ caption ]` that fires `on_click` on Enter, Space, or a
 left-click, highlighting its background while focused. It's a tab stop, so
 it joins the normal Tab cycle.
 
+## Reporting progress
+
+Everything so far either shows text or captures input.
+{Tuile::Component::ProgressBar} does neither: it reports, and it is the
+first component in this tour you never focus and never type into. A run of
+`█` grows left to right over a `░` track, measured against a range you set:
+
+```ruby
+bar = Component::ProgressBar.new(range: 0..files.size)
+bar.value = done
+```
+
+The first thing to notice is what it *doesn't* have — text. No percentage
+sits on the bar, and there is no slot to put one there. That looks like an
+omission until you try to write the alternative: centering a string over a
+fill boundary means slicing it in two and restyling each half so it stays
+legible against both, and the result can only ever be one centered line
+clipped to the bar's width. A {Tuile::Component::Label} underneath is
+strictly more capable and costs one line:
+
+```ruby
+label.text = "#{bar.percent}% — #{done}/#{files.size} files"
+```
+
+Now the app words it. "Scanning…", a filename, two lines, a count — none of
+which a formatting knob on the bar could have produced. This is the
+composition argument from chapter 1 in miniature, and the frameworks Tuile
+takes after land in the same place: Vaadin's `ProgressBar` has no text API
+either, and its own docs tell you to put a label beside it.
+
+That leaves `fraction` and `percent` as real API rather than conveniences,
+since they're what the label reads. Both scale the same way, and it's worth
+knowing the rule: **the endpoints are exact.** A full bar means done and
+`percent` returns 100 only at the maximum — 99.9 % floors to 99 and paints
+one empty cell. The alternative, rounding, paints a *full* bar at 97.5 % on
+a 20-cell rect, and a progress bar that says "finished" before it is has
+told you the one lie it exists to avoid. At the other end the rule is
+mirrored: anything above zero lights at least one cell, because a job that
+has started and shows nothing reads as a job that has hung.
+
+When you don't know the total, say so:
+
+```ruby
+bar.indeterminate = true
+```
+
+and the fill is replaced by a block sliding across the bar. It animates
+itself — the bar starts a ticker when it's added to the tree and cancels it
+when it's removed, so there is nothing to remember and nothing to leak.
+That is the attach-hook idiom from chapter 4, and this is the first
+component to use it. The cost is that an animating bar keeps the event loop
+awake, so switch it off (or take the bar off screen) when the work ends.
+
+One consequence of measuring against a range is worth calling out because
+it looks like an edge case and isn't: `range = 0..0` is legal, and reads as
+complete. An empty file list is a job with nothing outstanding, so
+`bar.range = 0..files.size` needs no special case for the empty run — and
+an app that reaches that state because it hasn't counted yet wanted
+`indeterminate` anyway.
+
+The bar takes its color from `bar_color`, which is `nil` by default — the
+terminal's own foreground, the same choice chapter 6 makes for every
+non-accent cell. Assign a {Tuile::Color} for a branded or threshold color
+(green under 50 %, red over 90 %), or a `Theme.ref` to have it track the
+light/dark scheme. Both glyphs take that one color: what distinguishes
+filled from empty is the *density* of the character, not its hue, so the
+bar still reads on a terminal with no color at all.
+
 ## Framing content
 
 {Tuile::Component::Window} is the frame: a bordered box with a `caption`
@@ -186,9 +540,9 @@ window.content = Component::TextView.new.tap { _1.text = help_text }
 Component::Popup.new(content: window).open
 ```
 
-A nested TextField that owns the cursor still swallows printable keys
-first, so typing `q` into a field inside a popup doesn't dismiss it — the
-same cursor-ownership rule, working through the layers.
+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.
 
 ## Batteries-included windows
 

data/book/08-testing.md

@@ -97,14 +97,27 @@ list.handle_key(Keys::DOWN_ARROW)          # exercises the cursor directly
 list.handle_mouse(MouseEvent.new(:left, 5, 2))
 ```
 
-**High: go through the screen.** {Tuile::Screen#handle_key} runs the *full*
-dispatch pipeline from chapter 5 — Tab cycling, global shortcuts, the
-subtree `key_shortcut` search, then the focus chain. When your test is
-about routing — that a shortcut jumps focus, that a modal popup traps Tab,
-that a focused text field swallows a key its sibling would otherwise claim
-— you drive `Screen.instance.handle_key` and let the real machinery run.
-Set focus the way production does, with `screen.focused = component` or
-`component.focus`.
+**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
+root. So when your test is about routing — that a layout's one-key pane jump
+fires, that a focused text field swallows a key its ancestor would otherwise
+claim, that an open modal keeps the content beneath it from seeing keys — you
+drive the pane and let the real machinery run:
+
+```ruby
+screen.focused = list                # focus as production does — or list.focus
+assert screen.pane.handle_key("1")   # the layout's ancestor binding fires
+```
+
+The two rungs *above* the pane have their own doors, because `Screen`'s own
+`handle_key` — the top of the ladder — is private: it belongs to the key
+thread, not to app code. Tab cycling is {Tuile::Screen#focus_next} /
+`focus_previous`, both already scoped to the topmost modal popup, which is
+what "a popup traps Tab" means. A global shortcut is a block you registered,
+so test the action it calls; the registry itself is a lookup table `Screen`
+consults before handing the key to the pane, and `register_global_shortcut`
+is worth a test only for what it *rejects* (printables, Tab, `EDITING_KEYS`).
 
 Two more test-only hooks close the loop. After you mutate something, call
 `Screen.instance.repaint` to flush the pending invalidations into the

data/book/09-styled-text.md

@@ -0,0 +1,132 @@
+# 9. Styled text
+
+Everything Tuile draws is, eventually, text with colors on it — a
+highlighted list row, a red error label, a border in the active accent.
+The value type that carries "text plus styling" through the whole
+framework is {Tuile::StyledString}, and it's worth one chapter of *why*,
+because the obvious representation — a plain `String` with ANSI escape
+codes threaded through it — is the one Tuile deliberately does *not* use.
+
+## Why not just a String with escape codes in it
+
+A terminal styles text with SGR escape sequences: `"\e[31mred\e[0m"` is
+the word "red" in red. It's tempting to treat a styled string as exactly
+that — a normal `String` that happens to contain those bytes — and let
+the terminal sort it out.
+
+The trouble shows up the moment you do anything *structural* to the text.
+Slice out columns 5 through 10: which colors are active at column 5? To
+answer, you have to scan every escape sequence from the start of the
+string, tracking the running SGR state, because the color at column 5 was
+set by some `\e[...m` that might be twenty characters earlier. Word-wrap
+it across a narrow viewport: every break point needs that same running
+state re-established on the next line, or the color bleeds or resets
+wrong. Concatenate two of them: whose reset wins? Every operation becomes
+"parse the SGR state machine, figure out what's active here, splice
+carefully." The escape codes and the text are tangled together, and the
+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
+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?"
+is just "which span contains column 5?" — a lookup, not a replay.
+
+That's the trade. You pay one extra type — you construct or parse a
+{Tuile::StyledString} instead of building a raw `String` — and in return
+slicing, wrapping, and concatenation become ordinary operations on a list
+of spans, each of which already knows its own style. For a framework that
+slices and wraps text constantly, on every repaint, that's the right side
+of the trade.
+
+## The algebra
+
+Once text is spans, the operations you'd want on a string come back, but
+style-aware. You concatenate with `+` (a plain `String` operand is parsed
+first, so embedded escapes round-trip). You take substrings by *display
+column* with `slice` — display column, not byte offset, because a
+fullwidth CJK character is two columns wide and a combining mark is zero,
+and the terminal cares about columns. You split on newlines with `lines`,
+word-wrap to a width with `wrap`, and truncate-with-ellipsis with
+`ellipsize`. Every one of them returns a fresh {Tuile::StyledString} with
+the spans carried across the cut intact — the value is immutable and its
+spans are frozen and shared, so these are cheap.
+
+Two details are worth knowing because they're choices, not accidents.
+Slicing **never splits a glyph**: if a two-column character straddles the
+boundary of your slice, it's dropped rather than rendered as half a
+character, which the terminal couldn't do anyway. "Glyph" there means a
+*grapheme cluster*, not a character, and the distinction is not pedantic —
+a letter plus its combining accent is two characters and one glyph, and a
+slice that kept the letter but dropped the mark would hand you back a
+visibly different word. Emoji make the same point louder: a thumbs-up plus
+a skin-tone modifier is two characters, one glyph, and two columns. Tuile
+measures clusters throughout and credits a combined emoji its real width
+rather than adding up its pieces, so text with emoji in it lays out and
+paints at the same size. And wrapping guarantees
+no output line exceeds the target width *whenever every character fits in
+that width* — a single glyph wider than the whole viewport still lands on
+its own line at its natural width, because there's nowhere narrower to put
+it. The exact signatures live in the rdoc; this is the shape of the
+toolbox.
+
+## Rendering and the minimal diff
+
+Two spans, both red, sitting next to each other, should not each re-emit
+`\e[31m` — the terminal is already red. {Tuile::StyledString#to_ansi}
+renders the spans to escape codes by **diffing** each span's style against
+the one before it, emitting only the codes that actually changed. A
+transition back to the plain default style emits a single `\e[0m` rather
+than laboriously turning each attribute off. The rendered run always
+closes with `\e[0m` if it ended non-default, so styling never bleeds into
+whatever the terminal prints next.
+
+This isn't just tidiness. The same style-diffing logic
+({Tuile::StyledString::Style#sgr_to}) is what the back buffer uses when it
+flushes changed cells to the terminal (chapter 2) — cell-to-cell there,
+span-to-span here, identical minimal sequences. Styled text and the
+flicker-free repaint model are the same idea at two scales: never rewrite
+what's already correct.
+
+## The parser: strict by default, lenient on request
+
+You can go the other way too — parse an ANSI-coded `String` *into* spans
+with {Tuile::StyledString.parse}. Here Tuile makes a sharp choice that's
+easy to get wrong, so it's worth stating plainly: **the parser is strict
+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
+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
+dropped what it didn't understand, that round-trip would quietly lie, and
+a styled string that survived a save/load cycle might come back subtly
+different. Strict parsing keeps the round-trip honest — anything the model
+can't represent is refused at the door, not swallowed.
+
+But strictness is wrong for one common job: piping in colored output you
+didn't produce and don't control — `git --color` through a pager, a build
+tool's output, anything that sprinkles cursor moves and exotic attributes
+you have no intention of modeling. For that, pass `lenient: true`. Now the
+parser keeps the colors and attributes it understands and **discards
+everything else** — unmodeled codes, malformed extended colors, cursor
+moves, OSC and other string sequences, stray escapes — instead of
+raising. It's lossy by definition (`parse(x, lenient: true)` does not
+round-trip back to `x`), and that's the point: "give me the colors, throw
+the rest away." Strict for text you own and must preserve exactly; lenient
+for text you're borrowing and only want the colors from.
+
+---
+
+{Tuile::StyledString} is the quiet primitive under everything visible.
+You rarely construct one by hand for simple cases — a {Tuile::Component::Label}
+takes a plain `String` and wraps it for you — but the moment you render
+your own content with per-span colors (a log line, a syntax-highlighted
+snippet, a diff), this is the type you're building, and the theming hook
+from chapter 6 is where you rebuild it when the palette changes.

data/book/README.md

@@ -29,7 +29,9 @@ theming (including live OS light/dark flips). Chapters 7–8 close out
 **narratively** — a tour of the shipped component toolbox framed around
 when and why to reach for each, and how to test a Tuile app end to end.
 Those two lean on the rdoc for the exact APIs; the guide keeps to the
-walkthroughs and use-cases.
+walkthroughs and use-cases. Chapter 9 is a **deep dive** on
+`Tuile::StyledString`, the text primitive under everything the framework
+draws — read it when you start rendering your own styled content.
 
 The book grows organically — a chapter exists when a concept has earned
 one, not to fill an outline.
@@ -59,21 +61,25 @@ one, not to fill an outline.
    `submit`, and how terminal resize (`SIGWINCH`) is plumbed through the
    same queue rather than handled off the signal.
 5. **[Focus and the keyboard](05-focus.md).** The focus chain and
-   `focusable?`, and the order in which a keystroke is offered to the
-   tree — Tab, global shortcuts, a component's `key_shortcut`, then
-   `handle_key`. How a focused text field swallows printable keys, and
-   how `keyboard_hint` drives the status bar.
+   `focusable?`, and the three-rung order in which a keystroke is offered
+   to the tree — Tab, global shortcuts, then `handle_key` delivered to
+   focus and bubbling up its ancestors. Why scope-wide keys (pane jumps, a
+   form's default button) belong on an ancestor, and how `keyboard_hint`
+   drives the status bar.
 6. **[Theming](06-theming.md).** Semantic color tokens read at paint
-   time, light/dark auto-detection at startup and live OS appearance
-   flips, pairing variants in a `ThemeDef`, app-specific custom tokens,
-   and rebuilding theme-derived content in `on_theme_changed`.
+   time, opt-in component backgrounds that inherit down the tree
+   (`bg_color`), light/dark auto-detection at startup and live OS
+   appearance flips, pairing variants in a `ThemeDef`, app-specific custom
+   tokens, and rebuilding theme-derived content in `on_theme_changed`.
 7. **[The component library](07-components.md).** A narrative tour of
    the shipped toolbox — Window, List, the text inputs and views,
-   Popup, and the window conveniences — framed around *when and why*
-   you reach for each. Signatures stay in the rdoc.
+   ProgressBar, Popup, and the window conveniences — framed around
+   *when and why* you reach for each. Signatures stay in the rdoc.
 8. **[Testing a Tuile app](08-testing.md).** The testing approach:
    `FakeScreen`, asserting against the painted buffer, driving
    invalidation, and PTY-based end-to-end tests of runnable scripts.
-
-All eight chapters are currently **stubs** — the skeleton is in place so
-the numbering is stable; prose lands chapter by chapter.
+9. **[Styled text](09-styled-text.md).** A deep dive on
+   `Tuile::StyledString`, the span-based "text plus styling" value type
+   under everything Tuile draws: why spans instead of a `String` full of
+   escape codes, the style-aware algebra (slice/wrap/concat by display
+   column), minimal-diff rendering, and the strict-vs-lenient parser.