tuile 0.14.0 → 0.16.0

data/book/04-event-loop.md

@@ -188,28 +188,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 +226,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 +245,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.
 

data/book/05-focus.md

@@ -43,12 +43,12 @@ they're independent on purpose.
 target *at all*. It's `false` by default — a {Tuile::Component::Label} is
 decoration; clicking one shouldn't yank focus away from the window around
 it. Controls that accept input (a text field, a list, a button) override
-it to `true`. This gate is what makes click-to-focus sane: clicking lands
-focus on the component under the cursor *only if it's focusable*,
-otherwise the click is ignored for focus purposes. 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
+it to `true`. This gate is what makes click-to-focus sane: a press lands
+focus on the component under the pointer *only if it's focusable*,
+otherwise it is ignored for focus purposes. The router resolves a path
+down the tree — every component whose rectangle contains the point, outermost
+first — so "the component under the pointer" is really all of them, and focus
+settles on the deepest focusable one, before any handler runs. 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.
@@ -73,6 +73,24 @@ that scope in tree order and advances by one, wrapping around; Shift+Tab
 walks backward. This is what keeps Tab from escaping an open dialog — the
 scope is the dialog, so cycling stays inside it.
 
+There is a third gate, and it isn't a predicate you override:
+{Tuile::Component#visible?}. A hidden component — or any component under a
+hidden one — is skipped by Tab, by click-to-focus, and by the forwarding a
+container does, because it is skipped by the walk that collects candidates
+at all. You never write a `visible?` check yourself; chapter 7 covers what
+the flag is for.
+
+The rule to know here is what happens when you hide the thing that
+currently *has* focus. Focus does not stay there, and it does not become
+nothing either: it moves to the hidden component's parent, which forwards
+it on to the first field it can reach — exactly what happens when a
+component is removed from the tree. Nothing is stashed, so bringing the
+component back does not bring focus back with it. That is the same
+behaviour a browser and every desktop toolkit settle on, and the reason
+Tuile can't simply drop focus is worth knowing: with focus at nothing, keys
+reach nobody at all, so an unhandled `q` would fall through to the event
+loop and quit your app.
+
 ## The dispatch order
 
 When a key arrives, it's offered to the tree in a fixed order, and the
@@ -93,7 +111,7 @@ sees the key. These are for app-wide actions — "Ctrl+L opens the log,"
 
 ```ruby
 screen.register_global_shortcut(Tuile::Keys::CTRL_L,
-                                hint: "^L #{screen.theme.hint("log")}") do
+                                hint: "^L #{screen.theme.fg(:hint, "log")}") do
   log_popup.open
 end
 ```
@@ -110,15 +128,15 @@ left is yours: control keys, ESC, PgUp/PgDn, function keys. A shortcut can
 opt to fire even while a modal popup is open (`over_popups: true`); by
 default it's suppressed while a popup is up, so the popup stays modal.
 
-**3. `handle_key`, delivered to focus and bubbling up.** Everything else
-goes to the focused component's {Tuile::Component#handle_key}, and if that
+**3. `handle_key?`, delivered to focus and bubbling up.** Everything else
+goes to the focused component's {Tuile::Component#handle_key?}, and if that
 returns `false` (didn't handle it), the key bubbles up the ancestor chain —
 the focused component, then its parent, then *its* parent — until someone
 returns `true` or the scope root is reached. This is how a list handles
 arrow keys itself but lets an unhandled key rise to the window around it.
 
 A component only ever receives a key when it's on the focus chain, so
-`handle_key` implementations act on the key alone — they never need to
+`handle_key?` implementations act on the key alone — they never need to
 check their own `active?` state. And if focus is `nil`, or sits outside
 the current modal scope, delivery reaches no one: that's precisely what
 makes an open modal popup modal.
@@ -148,7 +166,7 @@ right shape. **Put the key on the ancestor that owns the region.**
 
 ```ruby
 class AppLayout < Tuile::Component::Layout::Absolute
-  def handle_key(key)
+  def handle_key?(key)
     case key
     when "1" then @files.focus; true
     when "2" then @log.focus; true
@@ -196,7 +214,7 @@ Ask a terminal to paste eight lines and, by default, it types them at your
 program: one byte at a time, with every line break converted to `\r`. That
 `\r` is byte-identical to the Enter you press with your finger. So a prompt
 that rebinds Enter to "submit" submits eight times, and no amount of
-cleverness in `handle_key` can tell the two apart — by the time the key
+cleverness in `handle_key?` can tell the two apart — by the time the key
 arrives, the information is gone.
 
 The fix has to happen one layer down, at the code that talks to the
@@ -206,9 +224,11 @@ private mode 2004), which asks the terminal to wrap pasted text in
 marker, reads the payload raw up to the terminator, and posts it as a
 single `PasteEvent` — which never enters the ladder at all:
 
-- no Tab traversal, no global shortcuts, no `handle_key`;
-- straight to {Tuile::Component#handle_paste}, delivered down the focus
-  chain and bubbling exactly like a key;
+- no Tab traversal, no global shortcuts, no `handle_key?`;
+- straight to {Tuile::Component#handle_paste} on the focused component —
+  and *only* it: unlike a key, a paste does not bubble to ancestors, because
+  the reasons a key does are all about scope-wide bindings and none of them
+  wants a clipboard;
 - the whole clipboard as one `String`, `\n`-normalized.
 
 The default `handle_paste` returns `false` and the text is dropped.
@@ -221,7 +241,7 @@ its own:
 class PromptTextArea < Tuile::Component::TextArea
   protected
 
-  def handle_text_input_key(key)
+  def handle_text_input_key?(key)
     return super unless key == Tuile::Keys::ENTER
 
     submit(text)   # a typed Enter, and only ever a typed Enter
@@ -253,10 +273,76 @@ disagree about whether a bracketed line break is `\r`, `\r\n` or `\n`, so
 Tuile settles on `\n` before the text reaches a component.
 
 `run_event_loop(bracketed_paste: false)` turns the mode off, the same way
-`capture_mouse: false` turns off mouse tracking. Then a paste is keystrokes
+`capture_mouse: false` turns off mouse tracking — the next section has that
+knob's other settings. Then a paste is keystrokes
 again, with the ambiguity that implies — reach for it only if a terminal
 mishandles the mode.
 
+## The mouse takes a different road
+
+A key goes to whoever has focus. A press goes to whoever is *under the
+pointer*, which is a different question with a different answer, so the
+mouse has its own dispatcher — {Tuile::Mouse::Router} — and its own
+handlers. Components no longer walk the tree for it at all:
+
+```ruby
+class Tile < Component
+  def handle_mouse_down?(event)          # claims the press, and is then grabbed
+    return false unless event.button == :left
+
+    flip
+    true
+  end
+end
+```
+
+The router resolves a path first: the topmost popup containing the point,
+else the tiled content (a modal popup eats everything outside itself), then
+down through the children whose rects contain it. A left press **focuses the
+innermost focusable on that path before any handler runs** — you never write
+click-to-focus, and you cannot forget it. Then `handle_mouse_down?` is
+offered to the innermost component and **bubbles outward until one answers
+`true`**, exactly as a key bubbles up the focus chain. A wheel notch travels
+the same road through `handle_mouse_scroll?`, which is why a `List` scrolled
+to its top answers `false` and lets the pane behind it scroll instead.
+
+Two things follow that are easy to miss. **Geometry is the router's job, not
+yours**: a widget that declared an `extent` (chapter 7) only sees presses
+inside it, so a press on a `Button`'s blank tail focuses the button and fires
+nothing — no hit test in your code. And **whoever claims a press is
+*grabbed***: until the button comes up, `handle_mouse_up` and
+`handle_mouse_drag` go to that component wherever the pointer travels,
+including well outside its own rect — which is what keeps a fast drag from
+escaping the widget that started it. There is no `grab_mouse` and no
+`release_mouse` to call: the claim *is* the request.
+
+Because a release can be lost — over ssh, over tmux — a widget **activates on
+the press**, never on a synthesized click, and the grab also ends on the next
+press or on any keystroke. Treat `handle_mouse_up` as press feedback and
+drag-ending, never as the thing that runs the action.
+
+How much of this the terminal ever sends is the `capture_mouse:` ladder, each
+rung a superset of the one before:
+
+```ruby
+screen.run_event_loop(capture_mouse: false)     # nothing; native select-to-copy
+screen.run_event_loop                           # == :clicks — presses, releases, the wheel
+screen.run_event_loop(capture_mouse: :drag)     # + motion while a button is held
+screen.run_event_loop(capture_mouse: :hover)    # + motion with none, and enter/exit
+```
+
+`:hover` adds `handle_mouse_move?` and the argument-less
+`handle_mouse_enter` / `handle_mouse_exit` pair, along with
+{Tuile::Screen#hovered}. Ask for it only if something uses it: a terminal
+reports up to ~84 moves a second. And keep whatever hover does *cosmetic* —
+no terminal reports the pointer leaving the window, so an exit may arrive
+very late, or never.
+
+The rung is one app-wide choice, made here and nowhere else — so a component
+that overrides a hover hook under a lower rung simply never hears from it, with
+nothing to warn you. The sampler's *Mouse* pane answers all seven handlers on
+one surface, and is why that app asks for `:hover`.
+
 ## Where the cursor comes in — and where it doesn't
 
 A component signals cursor ownership through
@@ -273,6 +359,47 @@ needed. With dispatch resting on nothing but "did you return `true`," the
 proxy is gone, and a component's decision to consume a key is the only
 declaration in the system.
 
+## A component that reacts to its own focus
+
+Two hooks tell a component about itself, and a component overrides them —
+nothing else calls them. {Tuile::Component#handle_focus} fires when it gains
+focus; {Tuile::Component#handle_blur} fires when it loses it. Both fire on that
+one component, never on the ancestors that light up and go dark with it.
+
+`handle_focus` is the forwarding hook. It's how a {Tuile::Component::Window}
+handed focus passes it to its content, and how a {Tuile::Component::Layout}
+skips ahead to the first tab stop underneath it — which is also why it fires
+on *every* assignment, even one that re-focuses what's already focused.
+
+`handle_blur` is the commit point. Nothing else in Tuile is one: Tab is
+unconditional, so a user leaving a half-finished field usually leaves by a
+key no component ever sees, and `on_enter` never fires. If your field wants
+to tidy up what was typed, this is where:
+
+```ruby
+class TrimmedField < Tuile::Component::TextField
+  protected def handle_blur = (self.text = text.strip)
+end
+```
+
+Both hooks fire on one component, so a *composed* widget — a
+{Tuile::Component::ComboBox}, whose inner field is what actually holds focus —
+gets the blur on the child, not on itself. When the question is "has focus left
+this whole widget", override `active=` instead and compare before and after;
+that's exactly what the combo box does to close its dropdown when you tab away.
+
+It is a notification, not a veto — focus has already moved by the time you
+hear about it, and a handler that tries to hold focus is picking a fight with
+the one key nothing can suppress. It also fires wherever focus is *dropped*,
+not only where a user moved it: when a popup closes, the component being
+blurred has usually been detached already, so an `invalidate` there does
+nothing; and `screen.close` blurs the focused component on its way out. Keep
+the handler cheap and it won't matter.
+
+The framework sends both hooks with `__send__`, so declare them public,
+protected or private as you like — the example above groups `handle_blur` under
+`protected`, which is where framework-invoked plumbing belongs.
+
 ## Writing a status line
 
 Chapter 1 pointed out that Tuile draws no status bar. This is the chapter
@@ -283,7 +410,7 @@ A status line is a `Label` in your layout. That's the whole idea:
 
 ```ruby
 status = Tuile::Component::Label.new
-status.text = "q #{screen.theme.hint("quit")}  Tab #{screen.theme.hint("Switch")}"
+status.text = "q #{screen.theme.fg(:hint, "quit")}  Tab #{screen.theme.fg(:hint, "Switch")}"
 
 root = Tuile::Component::Layout::Vertical.new
 root.add(main_ui, Tuile::Component::Layout::Expand[1])
@@ -296,10 +423,13 @@ is exactly this: Tab, Enter and Backspace work in both panes, so its row is
 a constant. Reaching for a focus callback there would be machinery computing
 a value that never changes.
 
-Two details about the text itself. `theme.hint(...)` styles the descriptive
-half of a `key what` pair so hints look consistent (chapter 6), and it
-**bakes the color in** — so a label built from it rebuilds itself from
-`on_theme_changed` to follow a light/dark flip. And keys registered with
+Two details about the text itself. The `:hint` above is one of *your*
+`custom` theme tokens, not one of Tuile's — the framework colors only the
+chrome it paints, and this row isn't its. Chapter 6 shows the four lines
+that define the pair; the shade to reach for is a grey dimmer than the
+terminal's own foreground, so the *key* is what pulls the eye. `theme.fg`
+also **bakes the color in**, so a label built from it rebuilds itself from
+its `on_theme_changed` slot to follow a light/dark flip. And keys registered with
 {Tuile::Screen#register_global_shortcut} don't advertise themselves: the
 registry runs actions, it doesn't describe them, so a `^K menu` in your row
 is text you write next to the registration.

data/book/06-theming.md

@@ -23,18 +23,31 @@ defaults for free.
 
 What Tuile *does* color is the small set of cues that signal
 interaction: the highlight behind the focused list row, the border of the
-active window, the resting "well" of a text field, the shortcut captions
-in a status line you write. Those are the accents, and they are exactly the tokens
+active window, the resting "well" of a text field, the scrollbar down a
+scrollable pane's edge. Those are the accents, and they are exactly the tokens
 a {Tuile::Theme} carries — `active_bg_color`, `active_border_color`,
-`input_bg_color`, `hint_color`. There is no global `bg` or `fg` token,
+`input_bg_color`, `scrollbar_color`, the three that mark a field
+invalid (`error_color` and the two error wells), and `placeholder_color` for
+the hint an empty field paints into itself. There is no global `bg` or `fg` token,
 and that absence is intentional: adding one would mean painting over the
 terminal's defaults everywhere, which is precisely the thing that makes a
 TUI look wrong on someone else's color scheme. The theme touches only
 what the framework must color to be legible, and leaves the rest to the
 terminal.
 
-So a {Tuile::Theme} is a frozen value type — a `Data.define` of four
-colors plus an app-extensible `custom` hash — and that's all. Two are
+Note what that list does *not* include: a color for secondary text. The
+shortcut captions in a status line are a good example — they want to be
+dimmer than the keys beside them, and Tuile has no opinion about how dim,
+because Tuile does not paint them. A status line is yours (the framework
+reserves no row for one), so its shades are yours too, and they go in
+`custom` — which the next section covers. The one token that *looks* like
+a secondary-text color is `placeholder_color`, and it isn't one: it is
+tuned to sit just above invisible, for the specific case of a hint the
+reader is welcome to miss, on the specific background of a field's own
+well.
+
+So a {Tuile::Theme} is a frozen value type — a `Data.define` of colors
+plus an app-extensible `custom` hash — and that's all. Two are
 built in: {Tuile::Theme::DARK}, the colors Tuile has always used, and
 {Tuile::Theme::LIGHT}, counterparts legible on a pale background.
 
@@ -66,15 +79,53 @@ terminal default is just the root of that chain, which is why an unset
 
 A widget with a background of its *own* keeps it. A text field paints its
 well across its whole rect, so dropping one into a tinted panel shows the
-field in its own well, not the panel tint — the explicit background wins
-over the inherited one, the terminal equivalent of a CSS element that sets
-its own `background`.
+field in its own well, not the panel tint — the terminal equivalent of a CSS
+element that sets its own `background`. That is a *default*, though, not a
+refusal: set `bg_color` on the field itself and it wins, because the chain
+asks three questions in order — what did the app set on this component, what
+background does this widget claim of its own, and what surrounds it.
+
+Which is also how you get a field that reads as plain text inside a tinted
+prompt. You *can* name the panel's colour again on the field — but there is a
+shorter way to say "I have no background of my own, use whatever is behind me":
+
+```ruby
+field.bg_color = Component::BG_INHERIT
+```
+
+That is CSS's `background: inherit`, and it is different from leaving
+`bg_color` unset: unset means "ask *my* default first", which for a field is
+its well. `BG_INHERIT` skips the well and goes straight to what surrounds it.
+
+It is the same mechanism Tuile uses internally. A
+{Tuile::Component::ComboBox} is one widget with one surface, built out of a
+{Tuile::Component::TextField} plus a `▾` — so the ComboBox paints the well and
+marks its inner field `BG_INHERIT`. Exactly one well per widget, which is what
+lets you tint the ComboBox and have the tint reach the cells the field draws.
+
+Backgrounds can differ by state. An input is brighter while it holds focus,
+and a flat `bg_color` replaces *both* shades — fine for a field, which shows a
+caret when focused, and a deliberate choice for something like a
+{Tuile::Component::Select}, which has no caret and nothing else to indicate
+focus with. Name the states when you want to keep the distinction:
+
+```ruby
+field.bg_color = grey                            # flat: focused or not
+field.bg_color = { normal: grey, active: blue }  # your own pair
+field.bg_color = { active: blue }                # keep the widget's own well,
+                                                 # override only the focus shade
+```
+
+The keys are a small closed set (`:normal`, `:active`) that Tuile defines —
+a state with no key simply isn't answered there, and the question falls
+through to the next level of the chain, which is what makes the third line
+above mean what it reads as.
 
 `bg_color` takes either a concrete {Tuile::Color} or a *live theme
 reference* — `Theme.ref(:panel_bg)` — that names one of your app's custom
 tokens and re-resolves it against the current theme on every paint. The
 reference is the ergonomic path: assign it once and the panel follows
-light and dark on its own, with no `on_theme_changed` handler. That works
+light and dark on its own, with no `handle_theme_changed` handler. That works
 precisely because a background — unlike the baked-in colors of your
 *content* (below) — is resolved *live* at paint, exactly like the
 framework's own accents; `bg_color` is a single value read late, so
@@ -115,14 +166,15 @@ colors. Done.
 When a component has a themed color in hand, it applies it in one of two
 ways, and which one depends on the text.
 
-For plain chrome — a border string, a status-bar hint — the theme's
+For plain chrome — a border string, a button caption — the theme's
 **rendering helpers** wrap the text in the token's SGR color and a reset:
-`theme.active_bg("[ Ok ]")`, `theme.hint("quit")`. The helper picks the
-right channel for the token's role (a `*_bg` token wraps as a background,
-a hint as a foreground) and passes the content through verbatim, so the
-string may already contain other escape sequences — which is how
-{Tuile::Component::Window} feeds its whole border row, cursor moves and
-all, through `active_border`.
+`theme.active_bg("[ Ok ]")`, `theme.active_border("┌──┐")`, and
+`theme.fg(:hint, "quit")` for one of your own `custom` tokens. The helper
+picks the right channel for the token's role (a `*_bg` token wraps as a
+background, a border as a foreground) and passes the content through
+verbatim, so the string may already contain other escape sequences — which
+is how {Tuile::Component::Window} feeds its whole border row, cursor moves
+and all, through `active_border`.
 
 But chrome text is flat. Content is not. A list row or a label may be a
 {Tuile::StyledString} with its own per-span colors, and wrapping that in
@@ -205,7 +257,7 @@ more round trip than you might expect. The mode-2031 report says only
 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
+{Tuile::Component}`#handle_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
@@ -305,7 +357,21 @@ one with `theme[:accent]`, which **fail-fasts**: a typo'd token raises
 `KeyError` rather than silently painting a default, so a missing color is
 a loud bug and not a mystery. And you render with the generic `fg` / `bg`
 helpers — `theme.fg(:accent, "NEW")` — the custom-token counterparts of
-the built-in `hint` / `active_bg` helpers.
+the built-in `active_border` / `active_bg` helpers.
+
+This is where a status line's shades belong, and it is worth doing even
+for a single token. The examples that ship with Tuile all carry one
+`hint` grey for the descriptive half of their `"q quit"` rows, paired
+dark and light so the row follows an appearance flip:
+
+```ruby
+APP_THEME = Tuile::ThemeDef.new(
+  dark:  Tuile::Theme::DARK.with(custom:  { hint: Tuile::Color::GREY54 }),
+  light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+)
+screen.theme_def = APP_THEME
+status.text = "q #{screen.theme.fg(:hint, "quit")}"
+```
 
 For an app with more than a couple of custom tokens, the tidier move is
 to **subclass** {Tuile::Theme} and give each token a named coloring
@@ -374,21 +440,35 @@ because only *you* know which of the string's colors came from the theme
 versus which are inherent to the data (a log line's level color, say,
 should *not* follow the theme).
 
-The hook for this is {Tuile::Component#on_theme_changed}, fired on every
+The hook for this is {Tuile::Component#handle_theme_changed}, fired on every
 attached component whenever the theme changes. Your handler does exactly
 one thing: **re-run the code that rendered the content**, so it rebuilds
 the StyledString against the now-current theme.
 
+There are two ways to consume it, matching how you built the component,
+and they are two different method names — the `=` tells them apart. If you
+assembled stock components, assign the `on_theme_changed=` **listener slot**:
+
 ```ruby
 label.on_theme_changed = -> { label.text = render_status_line }
 ```
 
-There are two ways to consume it, matching how you built the component.
-If you assembled stock components, assign the `on_theme_changed=` proc as
-above. If you subclassed, override the method — and call `super`, so an
-assigned listener still fires. Either way the rule is the same: the hook
-is where theme-derived content gets rebuilt, and the framework handles
-everything else.
+If you subclassed, override `handle_theme_changed`, the **override point**
+— and call `super`, so an assigned listener still fires:
+
+```ruby
+class StatusLabel < Tuile::Component::Label
+  protected def handle_theme_changed
+    super
+    self.text = render_status_line
+  end
+end
+```
+
+That pair is the house rule across the whole widget set, not a special
+case for theming. Either way the rule here is the same — the hook is where
+theme-derived content gets rebuilt, and the framework handles everything
+else.
 
 ---