tuile 0.15.0 → 0.16.0

data/lib/tuile/component.rb

@@ -8,6 +8,29 @@ module Tuile
   # isn't {Screen#pane}) is never enqueued for repaint via {#invalidate}, and
   # any stale invalidation entries are filtered out at drain time. Subclasses
   # can paint freely in {#repaint} without re-asserting attachment.
+  #
+  # == Handlers and listener slots
+  #
+  # Two families, told apart by the `=`:
+  #
+  #   class Trimmed < Component::TextField
+  #     def handle_blur                  # handle_ — the override point
+  #       super
+  #       self.text = text.strip
+  #     end
+  #   end
+  #
+  #   label.on_theme_changed = -> { … }   # on_…= — the listener slot
+  #
+  # **What a handler returns is per hook**, declared in its own rdoc. Only the
+  # ones a dispatcher routes answer at all — {#handle_key?},
+  # {#handle_text_input_key?}, `MenuBar#handle_mnemonic?` — where `true` means "I
+  # took this, stop bubbling". The rest, {#handle_paste} included, return `void`.
+  #
+  # An override calls `super`, even where the base body is empty: that is what
+  # lets a hook grow an `on_foo=` slot without breaking you. The one carve-out is
+  # {#handle_child_removed}, whose base does real work and whose overrides
+  # replace it. `D_handler_naming` carries the argument.
   class Component
     extend Final
 
@@ -57,7 +80,7 @@ module Tuile
     # The three readers below report the geometry a parent *assigned*, as
     # shorthand for the matching {#rect} field. They are reports, not requests:
     # no container consults them when dividing space, and there is deliberately
-    # no writer — layout is top-down (`DECISIONS.md` `D_box_layouts`), so a
+    # no writer — layout is top-down (`design/decisions.md` `D_box_layouts`), so a
     # component says how big it *is*, never how big it wants to be.
 
     # @return [Size] `rect.size`.
@@ -92,7 +115,7 @@ module Tuile
     # It flows **downward only**: no container consults it when dividing space,
     # so {#rect} still means exactly what the parent assigned (`D_extent`). Three
     # things read it, all of them this component or the framework painting it:
-    # {#clear_outside_extent} blanks the dead tail, {#handle_mouse} hit-tests
+    # {#clear_outside_extent} blanks the dead tail, {Mouse::Router} hit-tests
     # against it so a click on that tail doesn't activate the widget, and a
     # dropdown anchors under it rather than under unused space.
     #
@@ -104,7 +127,7 @@ module Tuile
     def extent = nil
 
     # {#extent} placed at {#rect}'s top-left, for the consumers that need
-    # coordinates: `extent_rect.contains?(event.point)` in a {#handle_mouse}, and
+    # coordinates: `extent_rect.contains?(point)` in {Mouse::Router}, and
     # the anchor a dropdown hangs from. Total — an undeclared {#extent} yields
     # the whole {#rect}, so a generic caller never sees `nil`.
     # @return [Rect]
@@ -129,7 +152,7 @@ module Tuile
 
       prev_width = @rect.width
       @rect = new_rect
-      on_width_changed if prev_width != new_rect.width
+      handle_width_changed if prev_width != new_rect.width
       invalidate
     end
 
@@ -159,7 +182,7 @@ module Tuile
     #   showing it restores exactly the subtree that was showing before.
     # - **Focus never stays on what the user cannot see.** Hiding the subtree
     #   holding focus repairs it exactly as removing that subtree would (see
-    #   {#on_child_removed}), and does not hand it back on the way in.
+    #   {#handle_child_removed}), and does not hand it back on the way in.
     #
     # For "invisible but still occupying its space", use a
     # {Component::Slot} with no content (`D_slots`).
@@ -175,9 +198,9 @@ module Tuile
       @visible = value
       # `__send__` for the same reason `Screen#theme=` uses it: the hook is
       # protected (`D_hook_visibility`).
-      parent&.__send__(:on_child_visibility_changed, self)
+      parent&.__send__(:handle_child_visibility_changed, self)
       repair_focus_after_hiding unless value
-      on_tree { |c| screen.invalidate(c) } if attached?
+      walk_tree { |c| screen.invalidate(c) } if attached?
     end
 
     # @return [Screen] the screen which owns this component.
@@ -220,7 +243,7 @@ module Tuile
     # subtree so it repaints.
     #
     # A {Theme::Ref} is re-resolved against the theme each paint, so it tracks
-    # light/dark flips with no {#on_theme_changed} hook; a {Color} is fixed:
+    # light/dark flips with no {#handle_theme_changed} hook; a {Color} is fixed:
     #
     #   panel.bg_color = Theme.ref(:panel_bg)   # theme-tracked
     #   panel.bg_color = Color::GREY27          # fixed
@@ -255,7 +278,7 @@ module Tuile
       return if @bg_color == color
 
       @bg_color = color
-      on_tree { |c| screen.invalidate(c) } if attached?
+      walk_tree { |c| screen.invalidate(c) } if attached?
     end
 
     # Repaints the component. The default does the bookkeeping most components
@@ -273,6 +296,9 @@ module Tuile
     # skipping `super`.** The clear then covers only what is outside it, so the
     # cells it is about to repaint are not blanked first — blanking them would
     # mark them dirty and make {Buffer#flush} re-emit them (`D_progress_bar`).
+    # That saving is a *leaf*'s: a container's children paint its extent for it,
+    # so a cell among them that none covers still gets blanked — an extent
+    # narrows which cells are yours, never whether your gaps are wiped.
     #
     # **The children are re-invalidated whether or not they tile.** A container
     # that paints nothing of its own can only redraw its area *through* them, so
@@ -290,7 +316,10 @@ module Tuile
     def repaint
       return if rect.empty?
 
-      clear_outside_extent unless children.any? && children_tile_rect?
+      unless children.any? && children_tile_rect?
+        clear_outside_extent
+        clear_inside_extent if extent && children.any?
+      end
       invalidate_children
     end
 
@@ -299,56 +328,105 @@ module Tuile
     # it's on the focus chain — or when app code hands it one directly — so act
     # on the key alone and never gate on your own {#active?} state. See book ch5
     # for how a keystroke is routed to reach here.
+    #
+    # The `?` reads like `Set#add?`: calling it *delivers* the key and reports
+    # whether it was taken, so it is never a "would you handle this?" probe.
     # @param _key [String] a key.
     # @return [Boolean] true if the key was handled, false if not.
-    def handle_key(_key)
+    def handle_key?(_key)
       false
     end
 
     # Called when text is pasted while this component is {Screen#focused};
-    # override to accept it (the default reports every paste unhandled, and
-    # unhandled text is dropped). Unlike a key, a paste does **not** bubble —
-    # only the focused component is offered it, so an ancestor never sees one
-    # its descendant declined. The text arrives whole and `\n`-normalized, so
-    # `text.lines.size` is the paste's line count and a single mutation can
-    # absorb it:
+    # override to accept it. The default drops the text. It arrives whole and
+    # `\n`-normalized, so `text.lines.size` is the paste's line count and a
+    # single mutation can absorb it:
     #
     #   def handle_paste(text)
     #     self.caption = "[Pasted #{text.lines.size} lines]"
-    #     true
     #   end
     #
+    # **No verdict, unlike {#handle_key?}**: a paste reaches the focused component
+    # and stops, so one that declines has nowhere to hand it on to
+    # (`D_bracketed_paste`).
+    #
     # Reaching here means the terminal said "this came from the clipboard" —
     # {Component::AbstractStringField} inserts it at the caret, which is why a
     # subclass that rebinds ENTER to submit needs no paste handling of its own
     # to stop firing once per pasted line.
     # @param _text [String] the pasted text.
-    # @return [Boolean] true if the paste was consumed.
-    def handle_paste(_text)
-      false
-    end
+    # @return [void]
+    def handle_paste(_text); end
 
-    # Focuses this component when left-clicked (if {#focusable?}), then hands the
-    # event down to every child whose {#rect} contains the point — which is how a
-    # click descends the tiled tree to a leaf.
+    # Called when a mouse button goes down over this component; answer `true` to
+    # claim the press. The default claims nothing.
+    #
+    #   def handle_mouse_down?(event)
+    #     return false unless event.button == :left
+    #
+    #     @on_click&.call
+    #     true
+    #   end
     #
-    # A widget that resolves clicks *inside* its own rect — mapping a point to a
-    # row, or toggling an overlay — overrides this and does not call `super`.
-    # Such an override hit-tests {#extent_rect} rather than {#rect}, so a click
-    # on the tail it doesn't paint never activates it.
+    # {Mouse::Router} delivers it to the innermost component under the pointer
+    # and bubbles it up the ancestors until one answers `true`; the claimant
+    # then holds the *grab*, and the button's {#handle_mouse_drag} and
+    # {#handle_mouse_up} go to it alone. The press has already moved focus by
+    # the time it arrives, and it only arrives where {#extent_rect} contains the
+    # point, so an override needs neither `super` nor a hit test of its own.
+    #
+    # Activate here, on the press: Tuile synthesizes no click, because a release
+    # is losable over ssh and tmux (`D_mouse_dispatch`).
+    # @param _event [Mouse::DownEvent]
+    # @return [Boolean] whether this component claimed the press.
+    def handle_mouse_down?(_event) = false
+
+    # Called when the wheel turns over this component; answer `true` to consume
+    # the notch. Bubbles exactly as {#handle_mouse_down?} does, but grabs
+    # nothing — so a scroller already at its limit answers `false` and its
+    # ancestor scrolls instead.
+    # @param _event [Mouse::ScrollEvent]
+    # @return [Boolean] whether this component consumed the notch.
+    def handle_mouse_scroll?(_event) = false
+
+    # Called when the pointer moves over this component with nothing grabbed;
+    # answer `true` to consume the move. Bubbles as {#handle_mouse_down?} does.
+    # Arrives only under `run_event_loop(capture_mouse: :hover)`, at up to ~84
+    # events a second, which is why the default passes it on untouched.
+    # @param _event [Mouse::MoveEvent]
+    # @return [Boolean] whether this component consumed the move.
+    def handle_mouse_move?(_event) = false
+
+    # Called on the component that claimed a press when the button comes up,
+    # ending the grab. For press feedback and for ending a drag — never for
+    # activation: a release may never arrive, and any key or the next press
+    # ends the grab without it.
+    # @param _event [Mouse::UpEvent]
+    # @return [void]
+    def handle_mouse_up(_event); end
+
+    # Called on the component that claimed a press whenever the pointer moves
+    # while the button is held, wherever the pointer is. Needs
+    # `capture_mouse: :drag` or `:hover`.
+    # @param _event [Mouse::DragEvent] its point may lie outside {#rect}.
+    # @return [void]
+    def handle_mouse_drag(_event); end
+
+    # Called when the pointer comes over this component or any of its
+    # descendants — down the chain, root first, and after every
+    # {#handle_mouse_exit} the same move fires. Needs `capture_mouse: :hover`,
+    # and is suspended while a press is grabbed.
     #
-    # The walk stops at a hidden child, so a hidden component is never reached
-    # and an override needs no `visible?` check of its own.
-    # @param event [MouseEvent]
+    # **Never a commit point**: no terminal reports the pointer leaving the
+    # window, so the matching {#handle_mouse_exit} may arrive late or not at
+    # all. Anything done here must be cosmetic and survive that.
     # @return [void]
-    def handle_mouse(event)
-      screen.focused = self unless event.button != :left || active? || !focusable?
-      # Snapshot: a handler may add or remove siblings (a click that swaps a
-      # slot's occupant), and `each` over a mutating array skips an entry.
-      # A hidden child is skipped whatever its rect says — it keeps the rect it
-      # had, so in an Absolute the point still lands inside it.
-      children.dup.each { |c| c.handle_mouse(event) if c.visible? && c.rect.contains?(event.point) }
-    end
+    def handle_mouse_enter; end
+
+    # The other half of {#handle_mouse_enter}; also fires when this component is
+    # detached or hidden while hovered, innermost first.
+    # @return [void]
+    def handle_mouse_exit; end
 
     # @return [Boolean] true if the component is on the active chain — i.e. it
     #   is the focused component or an ancestor of it. Set by {Screen#focused=}.
@@ -415,61 +493,61 @@ module Tuile
     # @yieldparam component [Component]
     # @yieldreturn [void]
     # @return [void]
-    def on_tree(&block)
+    def walk_tree(&block)
       block.call(self)
-      children.each { _1.on_tree(&block) }
+      children.each { _1.walk_tree(&block) }
     end
 
-    # {#on_tree}, pruned: a hidden subtree is skipped whole, this component
+    # {#walk_tree}, pruned: a hidden subtree is skipped whole, this component
     # included when it is itself hidden (in which case nothing is yielded).
     #
     #   stops = []
-    #   scope.on_shown_tree { |c| stops << c if c.tab_stop? }
+    #   scope.walk_shown_tree { |c| stops << c if c.tab_stop? }
     #
-    # **Use this for anything asking "can the user reach it"**, {#on_tree} for
+    # **Use this for anything asking "can the user reach it"**, {#walk_tree} for
     # what the framework does *to* a component regardless — lifecycle, theme
     # fan-out, invalidation — which a hidden component still gets. Writing the
-    # first as `on_tree` plus a `visible?` test is the trap: that is this walk
+    # first as `walk_tree` plus a `visible?` test is the trap: that is this walk
     # with the ancestor case missing, so a field under a hidden panel is back
     # in the Tab cycle (`D_visibility`).
     # @yield [component]
     # @yieldparam component [Component]
     # @yieldreturn [void]
     # @return [void]
-    def on_shown_tree(&block)
+    def walk_shown_tree(&block)
       return unless visible?
 
       block.call(self)
-      children.each { _1.on_shown_tree(&block) }
+      children.each { _1.walk_shown_tree(&block) }
     end
 
     # Called when the component receives focus — on this component alone, never
-    # on the ancestors that light up with it. {#on_blur} is the other half.
+    # on the ancestors that light up with it. {#handle_blur} is the other half.
     #
-    # Unlike `on_blur` it is **not** edge-triggered: it fires on every
+    # Unlike `handle_blur` it is **not** edge-triggered: it fires on every
     # {Screen#focused=}, re-assigning the component that already has focus
     # included, which is what lets a container forward focus into its content
     # from here.
     # @return [void]
-    def on_focus; end
+    def handle_focus; end
 
-    # Optional zero-arg listener fired by the base {#on_theme_changed} — the
+    # Optional zero-arg listener fired by the base {#handle_theme_changed} — the
     # composition-style alternative to overriding the method, for apps that
     # assemble stock components rather than subclass:
     #
     #   label.on_theme_changed = -> { label.text = render_status_line }
     #
     # @return [Proc, nil]
-    attr_writer :on_theme_changed
+    attr_accessor :on_theme_changed
 
-    # Optional zero-arg listener fired by the base {#on_locale_changed} — the
+    # Optional zero-arg listener fired by the base {#handle_locale_changed} — the
     # composition-style alternative to overriding the method, for an app that
     # rendered a date or a number into a stock component:
     #
     #   label.on_locale_changed = -> { label.text = due_date.strftime(fmt) }
     #
     # @return [Proc, nil]
-    attr_writer :on_locale_changed
+    attr_accessor :on_locale_changed
 
     # Whether this component's tree is mounted on a UI, {ScreenPane} being the
     # root of every displayed tree.
@@ -496,9 +574,12 @@ module Tuile
     # passes the *hidden* child, which is still in `children` with `self` as
     # its parent: an override may repair focus however it likes, but must not
     # assume the child is gone. Removal bookkeeping belongs in the remover.
+    #
+    # The one hook whose base body does real work, so an override *replaces* it
+    # (as {Component::Slot} and {ScreenPane} do) instead of calling `super`.
     # @param child [Component] the just-detached, or just-hidden, child.
     # @return [void]
-    def on_child_removed(child)
+    def handle_child_removed(child)
       return unless attached?
 
       f = screen.focused
@@ -508,7 +589,7 @@ module Tuile
       until cursor.nil?
         if cursor == child
           screen.focused = self
-          return
+          break
         end
         cursor = cursor.parent
       end
@@ -574,7 +655,7 @@ module Tuile
       child.parent = self
     end
 
-    # Drops `child` and notifies {#on_child_removed}.
+    # Drops `child` and notifies {#handle_child_removed}.
     # @param child [Component]
     # @raise [ArgumentError] if `child` is not a child of this component.
     # @return [void]
@@ -583,16 +664,16 @@ module Tuile
     # pointer in the same call, which is what keeps them in agreement.
     def remove_child(child)
       detach_child(child)
-      on_child_removed(child)
+      handle_child_removed(child)
     end
 
     # Drops `child` *without* notifying — for a container swapping a named slot,
-    # which owes the {#on_child_removed} call once the new occupant is wired:
+    # which owes the {#handle_child_removed} call once the new occupant is wired:
     #
     #   detach_child(old)
     #   @content = new
     #   add_child(new, at: 0)
-    #   on_child_removed(old)   # focus repair cascades into the *new* content
+    #   handle_child_removed(old)   # focus repair cascades into the *new* content
     #
     # The child leaves {#children} before its pointer is cleared, so nothing
     # observes a child whose parent has disowned it while still listing it.
@@ -613,38 +694,38 @@ module Tuile
     # i.e. when {#attached?} flips to true — the place to acquire whatever is
     # supposed to live for exactly as long as the component is on screen:
     #
-    #   def on_attached
+    #   def handle_attached
     #     @ticker = screen.event_queue.tick_fps(10) { advance }
     #   end
     #
-    #   def on_detached
+    #   def handle_detached
     #     @ticker&.cancel
     #     @ticker = nil
     #   end
     #
-    # `on_attached` starts what `on_detached` stops; both must be cheap and
+    # `handle_attached` starts what `handle_detached` stops; both must be cheap and
     # idempotent, since a component moved between parents is genuinely detached
     # in between and gets both, in that order. Whatever you acquire here you
-    # must release in {#on_detached} — nothing else will. Not a destructor:
-    # process teardown does *not* fire {#on_detached}.
+    # must release in {#handle_detached} — nothing else will. Not a destructor:
+    # process teardown does *not* fire {#handle_detached}.
     #
     # {#invalidate} needs no guard: {#attached?} is already true here (and
-    # already false in {#on_detached}, where it no-ops). Do not read {#rect} —
+    # already false in {#handle_detached}, where it no-ops). Do not read {#rect} —
     # a parent assigns it *after* wiring, so it is still stale. Runs on the
     # thread that owns the UI.
     # @return [void]
-    def on_attached; end
+    def handle_attached; end
 
-    # Mirror of {#on_attached}, called once the tree has been unmounted — see
+    # Mirror of {#handle_attached}, called once the tree has been unmounted — see
     # there for the contract. Two things are still mid-flight when it runs, both
     # deliberate: {Screen#focused} may still point into this subtree (repair
     # happens after), and the ex-parent's own bookkeeping may not be finished.
     # So release resources here and don't inspect the tree around you.
     # @return [void]
-    def on_detached; end
+    def handle_detached; end
 
     # Rewires the parent pointer and, when that changes whether the component is
-    # {#attached?}, fires {#on_attached} / {#on_detached} across the whole
+    # {#attached?}, fires {#handle_attached} / {#handle_detached} across the whole
     # subtree. The sole firing site: `add_child` / `detach_child` are the only
     # callers, and they update {#children} *before* calling this, so a hook sees
     # a tree whose list and pointers already agree.
@@ -674,28 +755,31 @@ module Tuile
     #   current attachedness rather than on `parent.equal?(self)`: a child pulled
     #   out during a detach walk is *already* detached, so its own `parent=` saw
     #   no transition and stayed silent — a parentage check would skip it too and
-    #   it would never hear `on_detached` at all. The reverse case (pulled out
-    #   during an *attach* walk) gets `on_detached` from its own `parent=` and no
-    #   `on_attached`, which is why the hooks are required to be idempotent: an
-    #   unpaired detach releases nothing, whereas firing `on_attached` at a
+    #   it would never hear `handle_detached` at all. The reverse case (pulled out
+    #   during an *attach* walk) gets `handle_detached` from its own `parent=` and no
+    #   `handle_attached`, which is why the hooks are required to be idempotent: an
+    #   unpaired detach releases nothing, whereas firing `handle_attached` at a
     #   component that is no longer attached would start a ticker nothing stops.
     #
-    # @param attached [Boolean] true to fire {#on_attached}, false for {#on_detached}.
+    # @param attached [Boolean] true to fire {#handle_attached}, false for {#handle_detached}.
     # @return [void]
     def fire_lifecycle(attached)
       kids = children.dup
-      attached ? on_attached : on_detached
+      attached ? handle_attached : handle_detached
       kids.each { _1.fire_lifecycle(attached) if _1.attached? == attached }
     end
 
     # Called whenever the component width changes. Does nothing by default.
     # @return [void]
-    def on_width_changed; end
+    def handle_width_changed; end
 
     # Called on the parent after a direct child's {#visible=} flipped, so a
     # container that divides space can re-divide it:
     #
-    #   def on_child_visibility_changed(_child) = relayout
+    #   def handle_child_visibility_changed(_child)
+    #     super
+    #     relayout
+    #   end
     #
     # **A container with layout arithmetic owes this override**, or a hidden
     # child keeps its slot and its gap — the hole the flag exists to close.
@@ -703,27 +787,31 @@ module Tuile
     # arithmetic, and an app wanting the space back reads `visible?` there.
     #
     # Fires on the flip only, before the subtree is invalidated, never for a
-    # grandchild. {#visible=} repairs focus itself, so an override needs no
-    # `super`. Reached through `__send__`, so it may declare any visibility
-    # (`D_hook_visibility`).
+    # grandchild. {#visible=} repairs focus itself, so an override has nothing
+    # to inherit — it still calls `super`, per the class doc. Reached through
+    # `__send__`, so it may declare any visibility (`D_hook_visibility`).
     # @param _child [Component] the direct child whose flag changed.
     # @return [void]
-    def on_child_visibility_changed(_child); end
+    def handle_child_visibility_changed(_child); end
 
-    # Mirror of {#on_focus}: the component just lost focus, to another component
+    # Mirror of {#handle_focus}: the component just lost focus, to another component
     # or to nothing. The commit point a Tab-away still reaches — Tab is
     # unconditional, so {Component::TextField#on_enter} never fires for a user
     # who tabs out of a half-typed field:
     #
     #   class TrimmedField < Component::TextField
-    #     protected def on_blur = (self.text = text.strip)
+    #     protected def handle_blur
+    #       super
+    #       self.text = text.strip
+    #       false
+    #     end
     #   end
     #
     # Edge-triggered, and fired on the blurred component alone — never on the
     # ancestors leaving the active chain with it, so a composed widget asking
     # "did focus leave me *and* my children" overrides {#active=} instead
     # ({Component::ComboBox} closes its dropdown from there). Focus that merely
-    # *passes through* does blur: a container forwarding focus from {#on_focus}
+    # *passes through* does blur: a container forwarding focus from {#handle_focus}
     # is blurred by its own forward.
     #
     # A notification, not a veto — focus has already moved, and the active-flag
@@ -736,12 +824,12 @@ module Tuile
     # It fires wherever focus is *dropped*, not only where a user moved it, so
     # two paths reach it with the tree mid-flight: the popup-close repair blurs
     # an **already-detached** component, where {#invalidate} is the same silent
-    # no-op as in {#on_detached}, and {Screen#close} blurs on its way out. Keep
+    # no-op as in {#handle_detached}, and {Screen#close} blurs on its way out. Keep
     # it cheap; a raise propagates out of {Screen#focused=}. Protected because
     # the framework calls it and an app never does — {Screen} reaches it with
     # `__send__`, so an override may declare any visibility (`D_hook_visibility`).
     # @return [void]
-    def on_blur; end
+    def handle_blur; end
 
     # Called on every attached component (pre-order, popups included) when
     # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=} and on
@@ -759,7 +847,8 @@ module Tuile
     # {Screen}, not being a {Component}, fans it out through `__send__`, so an
     # override is free to declare any visibility (`D_hook_visibility`).
     # @return [void]
-    def on_theme_changed
+    #   is whatever the app's lambda happened to return.
+    def handle_theme_changed
       @on_theme_changed&.call
     end
 
@@ -777,7 +866,8 @@ module Tuile
     # fans it out through `__send__`, so an override may declare any visibility
     # (`D_hook_visibility`).
     # @return [void]
-    def on_locale_changed
+    #   is whatever the app's lambda happened to return.
+    def handle_locale_changed
       @on_locale_changed&.call
     end
 
@@ -840,6 +930,24 @@ module Tuile
       clear_background(below, bg) unless below.empty?
     end
 
+    # Blanks the {#extent} itself, for a *container* whose children don't cover
+    # it — a {Component::Layout::Box}'s `spacing` column, the slack past the last
+    # child, the span a child abandoned by going hidden or by a narrowing resize.
+    #
+    # In the *ambient* background, the same answer {#clear_outside_extent} gives
+    # the dead tail: a gap between two children is not this widget's ink, so an
+    # app's {#bg_color} tint covers it but a well of its own — a field's, a
+    # validation error's — must not bleed into it.
+    #
+    # Called by the default {#repaint} for a container only; a leaf paints its
+    # extent itself, and blanking that first is the re-emit `D_progress_bar`
+    # bought back. Override it to decline when you paint your own ink into a
+    # face cell no child covers.
+    # @return [void]
+    def clear_inside_extent
+      clear_background(extent_rect, ambient_bg_color)
+    end
+
     # The background this component paints when the app has set no {#bg_color} —
     # `nil` by default, meaning "I have no surface of my own; whatever is behind
     # me shows through". A widget that paints an opaque surface overrides it, and
@@ -856,7 +964,7 @@ module Tuile
     # the cheap form and allocates nothing on the paint path.
     #
     # Read the theme here rather than in an ivar: this runs at paint time, so a
-    # {Screen#theme=} restyles the widget with no {#on_theme_changed} hook.
+    # {Screen#theme=} restyles the widget with no {#handle_theme_changed} hook.
     # @return [Color, Theme::Ref, Hash, nil]
     def default_bg_color = nil
 
@@ -959,7 +1067,7 @@ module Tuile
     private
 
     # Hands focus out of the subtree just hidden, if it was in there, through
-    # the parent's {#on_child_removed} — see there for why hiding reuses the
+    # the parent's {#handle_child_removed} — see there for why hiding reuses the
     # removal repair instead of growing a second one.
     #
     # The parent is necessarily showing (focus was inside it a moment ago, and
@@ -970,7 +1078,7 @@ module Tuile
 
       cursor = screen.focused
       cursor = cursor.parent until cursor.nil? || cursor.equal?(self)
-      parent.on_child_removed(self) unless cursor.nil?
+      parent.handle_child_removed(self) unless cursor.nil?
     end
 
     # What surrounds this component — an app-set {#bg_color}, else whatever the

data/lib/tuile/event_queue.rb

@@ -109,7 +109,7 @@ module Tuile
     # event-handler error, instead of bypassing it.
     # @yield [event] called for each posted event.
     # @yieldparam event [Object] a posted event — typically a {KeyEvent},
-    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, a `Proc` from {#submit},
+    #   {Mouse::Event}, {TTYSizeEvent}, {EmptyQueueEvent}, a `Proc` from {#submit},
     #   or any object pushed via {#post}. {ErrorEvent}s are not yielded — they
     #   terminate the loop directly.
     # @yieldreturn [void]
@@ -147,7 +147,7 @@ module Tuile
     def running? = @run_lock.locked?
 
     # @return [Boolean] true if this thread is the one running {#run_loop}.
-    def on_loop_thread? = @run_lock.owned?
+    def in_loop_thread? = @run_lock.owned?
 
     # Stops ongoing {#run_loop}. The stop may not be immediate: {#run_loop} may
     # process a bunch of events before terminating.
@@ -175,7 +175,7 @@ module Tuile
     #
     # {Screen#event_loop} routes it to {Component#handle_paste} down the focus
     # chain. It never enters the key ladder: no Tab traversal, no global
-    # shortcut, no {Component#handle_key}.
+    # shortcut, no {Component#handle_key?}.
     #
     # @!attribute [r] text
     #   @return [String] the pasted text, `\n`-normalized by
@@ -363,7 +363,7 @@ module Tuile
           event = if key == Keys::PASTE_START
                     PasteEvent.new(Keys.read_paste)
                   else
-                    MouseEvent.parse(key) || ColorSchemeEvent.parse(key) ||
+                    Mouse.parse(key) || ColorSchemeEvent.parse(key) ||
                       BackgroundColorEvent.parse(key) || KeyEvent.new(key)
                   end
           post event

data/lib/tuile/fake_event_queue.rb

@@ -18,7 +18,7 @@ module Tuile
     # @return [Boolean] always false — {#run_loop} raises, so no loop ever runs.
     def running? = false
     # @return [Boolean] always true.
-    def on_loop_thread? = true
+    def in_loop_thread? = true
     # @return [void]
     def stop; end