tuile 0.15.0 → 0.16.0

data/lib/tuile/screen.rb

@@ -85,8 +85,9 @@ module Tuile
       # filter would take the whole tree with it.
       @pane = ScreenPane.new
       @pane.rect = Rect.new(0, 0, @size.width, @size.height)
+      @mouse_router = Mouse::Router.new(self)
       @on_error = ->(e) { raise e }
-      # App-level keyboard shortcuts dispatched by {#handle_key} before keys
+      # App-level keyboard shortcuts dispatched by {#handle_key?} before keys
       # reach the pane. See {#register_global_shortcut}.
       @global_shortcuts = {}
       # The back buffer components paint into. {#repaint} flushes its diff to
@@ -107,8 +108,8 @@ module Tuile
     # {Component::TextArea}'s newline, a caret move, a deletion. `ENTER` is the
     # trap worth naming: it is unprintable, so nothing else stops it, and
     # "bind Enter to submit" is the obvious wrong way to build a default
-    # button. The right way is a `handle_key` on the form itself, where a
-    # focused field still gets first refusal — see {ScreenPane#handle_key}.
+    # button. The right way is a `handle_key?` on the form itself, where a
+    # focused field still gets first refusal — see {ScreenPane#handle_key?}.
     #
     # Deliberately *not* reserved: `HOME`/`END`/`PAGE_UP`/`PAGE_DOWN`. They
     # move within a widget rather than mutate its value, and binding them
@@ -223,7 +224,7 @@ module Tuile
     # Kept current across OS appearance flips, a frame behind: the flip
     # report carries light/dark only, so the screen re-probes and this
     # updates when the reply lands. A changed color then fires
-    # {Component#on_theme_changed} across the tree exactly as a theme swap
+    # {Component#handle_theme_changed} across the tree exactly as a theme swap
     # does — a background-derived tint *is* a theme-derived color.
     # @return [Color, nil]
     attr_reader :background_color
@@ -243,7 +244,7 @@ module Tuile
     end
 
     # Replaces the theme and restyles the whole UI: fires
-    # {Component#on_theme_changed} across the attached tree and invalidates
+    # {Component#handle_theme_changed} across the attached tree and invalidates
     # every attached component. No-op when `new_theme` equals the current theme.
     # This is a *transient* override — the next OS appearance flip re-picks from
     # {#theme_def}; assign {#theme_def=} for durable theming.
@@ -256,9 +257,9 @@ module Tuile
       return if @theme == new_theme
 
       @theme = new_theme
-      # `__send__`, not `&:on_theme_changed`: the hook is protected, and an app
+      # `__send__`, not `&:handle_theme_changed`: the hook is protected, and an app
       # subclass may narrow it further (`D_hook_visibility`).
-      @pane&.on_tree { _1.__send__(:on_theme_changed) }
+      @pane&.walk_tree { _1.__send__(:handle_theme_changed) }
       needs_full_repaint
     end
 
@@ -272,7 +273,7 @@ module Tuile
     # @return [Locale]
     attr_reader :locale
 
-    # Replaces the locale: fires {Component#on_locale_changed} across the
+    # Replaces the locale: fires {Component#handle_locale_changed} across the
     # attached tree and invalidates every attached component. No-op when
     # `new_locale` equals the current one.
     #
@@ -293,7 +294,7 @@ module Tuile
       @locale = new_locale
       # `__send__` for the same reason `theme=` uses it: the hook is protected
       # (`D_hook_visibility`).
-      @pane&.on_tree { _1.__send__(:on_locale_changed) }
+      @pane&.walk_tree { _1.__send__(:handle_locale_changed) }
       needs_full_repaint
     end
 
@@ -327,7 +328,7 @@ module Tuile
     # @return [void]
     def check_locked
       raise Tuile::Error, "Screen is closed: no UI mutation is possible after Screen#close" if @closed
-      return if @event_queue.running? ? @event_queue.on_loop_thread? : Thread.current.equal?(@ui_thread)
+      return if @event_queue.running? ? @event_queue.in_loop_thread? : Thread.current.equal?(@ui_thread)
 
       # `submit` is the wrong remedy with no loop running — nothing would drain
       # the queue, so the block silently never fires.
@@ -371,9 +372,9 @@ module Tuile
     # whatever is painted over it and feed it every keystroke.
     #
     # Once the pointer and the active flags are settled, three notices fire in
-    # order: {Component#on_blur} on what lost focus, {Component#on_focus} on
+    # order: {Component#handle_blur} on what lost focus, {Component#handle_focus} on
     # what took it, then {#on_focus_changed}. The outer two are edge-triggered
-    # and `on_focus` is not — see there.
+    # and `handle_focus` is not — see there.
     # @param focused [Component, nil] the new component to be focused.
     def focused=(focused)
       unless focused.nil? || focused.is_a?(Component)
@@ -384,7 +385,7 @@ module Tuile
       previous = @focused
       if focused.nil?
         @focused = nil
-        @pane.on_tree { _1.active = false }
+        @pane.walk_tree { _1.active = false }
       else
         raise Tuile::Error, "#{focused} is not attached to this screen" if focused.root != @pane
         raise Tuile::Error, "#{focused} is hidden, or sits under a hidden ancestor" if hidden?(focused)
@@ -396,7 +397,7 @@ module Tuile
           active << cursor
           cursor = cursor.parent
         end
-        @pane.on_tree { _1.active = active.include?(_1) }
+        @pane.walk_tree { _1.active = active.include?(_1) }
       end
       fire_focus_hooks(previous, focused)
     end
@@ -412,17 +413,17 @@ module Tuile
     #
     #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
     #
-    # **Edge-triggered**, like {Component#on_attached}: re-assigning the
+    # **Edge-triggered**, like {Component#handle_attached}: re-assigning the
     # component that already has focus fires nothing, so a callback can be as
     # expensive as rebuilding a hint string without a `did it really change?`
     # guard of its own. That matters more than it looks — `ScreenPane#content=`
     # clears focus on every content swap, which on a level-triggered hook would
     # fire a nil→nil notification during assembly.
     #
-    # It runs *after* the active-flag cascade and `on_focus`, so the tree is
+    # It runs *after* the active-flag cascade and `handle_focus`, so the tree is
     # settled. Two things a callback must tolerate: {#focused} being `nil`, and
     # firing during {#close} — teardown clears focus, exactly as it fires
-    # {Component#on_detached}. A raising callback propagates out of {#focused=}
+    # {Component#handle_detached}. A raising callback propagates out of {#focused=}
     # and leaves focus assigned; keep it trivial, as with the attach hooks.
     # @return [Proc, nil]
     attr_accessor :on_focus_changed
@@ -440,20 +441,25 @@ module Tuile
     end
 
     # Runs the event loop on the calling thread, taking over stdin (raw mode,
-    # echo off): keys and mouse events are dispatched via {#handle_key} /
+    # echo off): keys and mouse events are dispatched via {#handle_key?} /
     # {#handle_mouse}, and the loop repaints once per drained tick. Returns
     # when `q` or ESC is pressed unhandled. Restores terminal state on exit.
     #
     # For the duration this thread owns the UI ({#state} is `:running`);
     # ownership reverts to the creating thread once it returns.
     #
-    # @param capture_mouse [Boolean] when true (default), enables xterm mouse
-    #   tracking so clicks and scroll wheel arrive as {MouseEvent}s and feed
-    #   {Component#handle_mouse}. When false, no tracking escape sequence is
-    #   written: the terminal keeps its native click handling, which is what
-    #   you want if the app benefits more from select-to-copy than from
-    #   click-to-focus. Components' `handle_mouse` is simply never invoked
-    #   from the loop in that mode (the terminal stops sending the bytes).
+    # @param capture_mouse [Boolean, Symbol] how much mouse tracking to ask the
+    #   terminal for — each level unlocking one tier of {Mouse}'s events, and
+    #   costing what that tier reports:
+    #
+    #   - `false` — none. The terminal keeps its native click handling, which is
+    #     what you want if the app benefits more from select-to-copy.
+    #   - `true` (default), `:clicks` — presses, releases and the wheel.
+    #   - `:drag` — plus motion while a button is held, as
+    #     {Component#handle_mouse_drag}.
+    #   - `:hover` — plus motion with no button, as
+    #     {Component#handle_mouse_move?} and the enter/exit hooks. ~84 reports a
+    #     second (`R_mouse_reporting`), so ask for it only if something uses it.
     # @param bracketed_paste [Boolean] when true (default), enables DEC private
     #   mode 2004 so pasted text arrives whole, as {Component#handle_paste},
     #   instead of as one keystroke per character — which is the only way a
@@ -462,16 +468,20 @@ module Tuile
     #   fires it once per pasted line. Turn it off only for a terminal that
     #   mishandles the mode.
     # @raise [Tuile::Error] if the screen is already {#close}d.
+    # @raise [ArgumentError] on an unknown `capture_mouse:` level.
     # @return [void]
     def run_event_loop(capture_mouse: true, bracketed_paste: true)
       raise Tuile::Error, "Screen is closed: cannot run the event loop" if @closed
 
+      level = Mouse.level(capture_mouse)
+
       # The guard above stays outside the begin: teardown for a setup that never
       # happened restores echo on a non-TTY stdin, and the ENOTTY masks the
       # real error.
       begin
         $stdin.echo = false
-        print MouseEvent.start_tracking if capture_mouse
+        @mouse_router.level = level
+        print Mouse.start_tracking(level) if level
         print Keys::BRACKETED_PASTE_ON if bracketed_paste
         # Follow OS light/dark flips live: terminals supporting mode 2031
         # push color-scheme reports that the key thread turns into
@@ -483,7 +493,9 @@ module Tuile
       ensure
         print TerminalBackground::NOTIFY_OFF
         print Keys::BRACKETED_PASTE_OFF if bracketed_paste
-        print MouseEvent.stop_tracking if capture_mouse
+        print Mouse.stop_tracking(level) if level
+        # Back to delivering everything a spec posts once no loop owns the wire.
+        @mouse_router.level = :hover
         print TTY::Cursor.show
         $stdin.echo = true
       end
@@ -510,9 +522,9 @@ module Tuile
     #
     # - **Printable keys** — they'd hijack typing into a
     #   {Component::TextField}. A scope-wide one-key binding belongs on the
-    #   scope root's own `handle_key`, where a focused field consumes it first
-    #   (see {ScreenPane#handle_key}).
-    # - **TAB / SHIFT_TAB** — {#handle_key} intercepts them for focus
+    #   scope root's own `handle_key?`, where a focused field consumes it first
+    #   (see {ScreenPane#handle_key?}).
+    # - **TAB / SHIFT_TAB** — {#handle_key?} intercepts them for focus
     #   navigation before the registry is consulted, so a binding would never
     #   fire.
     # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
@@ -535,7 +547,7 @@ module Tuile
       if Keys.printable?(key)
         raise ArgumentError,
               "global shortcut key must be unprintable; got #{key.inspect}. " \
-              "For a one-key binding, override handle_key on the scope root " \
+              "For a one-key binding, override handle_key? on the scope root " \
               "(your content layout, or the popup) — a focused text field then " \
               "consumes the key first, so typing isn't hijacked."
       end
@@ -547,7 +559,7 @@ module Tuile
         raise ArgumentError,
               "#{key.inspect} is reserved: every editable widget needs it, and this registry " \
               "sits above the component tree with nothing to suppress it. For a default " \
-              "button, handle ENTER in the form's own handle_key instead — a focused " \
+              "button, handle ENTER in the form's own handle_key? instead — a focused " \
               "TextArea/TextField gets first refusal there."
       end
       @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups)
@@ -586,7 +598,7 @@ module Tuile
     # @api private
     # @return [void]
     def needs_full_repaint
-      @pane&.on_tree { invalidate _1 }
+      @pane&.walk_tree { invalidate _1 }
     end
 
     # Internal — use {Component::Overlay#open?} instead.
@@ -607,7 +619,7 @@ module Tuile
 
     # Tears the screen down and vacates the singleton slot, moving {#state} to
     # the terminal `:closed`. Unmounts the tree first, so every component gets
-    # its {Component#on_detached}. Idempotent.
+    # its {Component#handle_detached}. Idempotent.
     # @raise [Tuile::Error] if an event loop is still running — stop it with
     #   `event_queue.stop` and let {#run_event_loop} return first, since closing
     #   under a live loop drops the pane it is still painting — or if the caller
@@ -622,11 +634,12 @@ module Tuile
       begin
         @pane.detach_all
       ensure
-        # A raising on_detached propagates — it's a bug to fix, not something the
+        # A raising handle_detached propagates — it's a bug to fix, not something the
         # framework guards — but teardown still has to finish, or one such bug
         # leaves a half-closed screen behind and every later example fails with it.
         clear
         @pane = nil
+        @mouse_router = nil
         @closed = true
         @@instance = nil # rubocop:disable Style/ClassVars
       end
@@ -682,6 +695,9 @@ module Tuile
     # @return [void]
     def repaint
       check_locked
+      # The one site that runs after every mutation, so a component hidden,
+      # detached or reparented while hovered gets its exit exactly once.
+      @mouse_router.sync_hover
       # This simple TUI framework doesn't support window clipping since tiled
       # windows are not expected to overlap. If there rarely is a popup, we
       # just repaint all windows in correct order — sure they will paint over
@@ -725,14 +741,14 @@ module Tuile
         # than a depth sort. The pane's pre-order traversal already orders the
         # tiled layer (the content subtree) parent-before-child; the popups are
         # the top layer and must paint last, so we collect the tiled layer first
-        # and append popups rather than taking a single pane.on_tree walk.
+        # and append popups rather than taking a single pane.walk_tree walk.
         popup_members = Set.new
-        popups.each { |p| p.on_tree { popup_members << _1 } }
+        popups.each { |p| p.walk_tree { popup_members << _1 } }
 
         # Tiled layer: invalidated non-popup components, in tree order.
         repaint = []
         tiled_invalidated = false
-        @pane.on_tree do |c|
+        @pane.walk_tree do |c|
           next if popup_members.include?(c)
           next unless @invalidated.include?(c)
 
@@ -753,8 +769,8 @@ module Tuile
         below_repainted = tiled_invalidated
         popups.each do |p|
           layer_invalidated = false
-          p.on_tree { |c| layer_invalidated ||= @invalidated.include?(c) }
-          p.on_tree { |c| repaint << c if below_repainted || @invalidated.include?(c) }
+          p.walk_tree { |c| layer_invalidated ||= @invalidated.include?(c) }
+          p.walk_tree { |c| repaint << c if below_repainted || @invalidated.include?(c) }
           below_repainted ||= layer_invalidated
         end
 
@@ -778,6 +794,28 @@ module Tuile
     # @return [Point, nil]
     def cursor_position = @focused&.cursor_position
 
+    # Routes one mouse event into the tree ({Mouse::Router}) — what the event
+    # loop does with every report the terminal sends, and how a spec drives the
+    # mouse:
+    #
+    #   screen.handle_mouse(Mouse::DownEvent.new(:left, 5, 2))
+    #
+    # @param event [Mouse::Event]
+    # @return [void]
+    def handle_mouse(event)
+      check_locked
+      @mouse_router.dispatch(event)
+    end
+
+    # @return [Component, nil] the innermost component the pointer is over, as
+    #   of the last move. Always nil below `capture_mouse: :hover`, and frozen
+    #   at its last value while a press is grabbed.
+    def hovered = @mouse_router&.hovered
+
+    # @return [Component, nil] the component holding the mouse grab — the one
+    #   whose {Component#handle_mouse_down?} claimed the press still held.
+    def grabbed = @mouse_router&.grabbed
+
     private
 
     # Whether `component` is out of the user's reach because it or an ancestor
@@ -786,7 +824,7 @@ module Tuile
     # Private, not a `Component#shown?`, for the reason `D_empty_ancestor`
     # declined a `Component#paintable?`: it reads as a component-level concept
     # and is really this class's question. A *walk* needs no such predicate —
-    # it prunes at the hidden subtree's root ({Component#on_shown_tree}).
+    # it prunes at the hidden subtree's root ({Component#walk_shown_tree}).
     # @param component [Component]
     # @return [Boolean]
     def hidden?(component)
@@ -805,10 +843,10 @@ module Tuile
     # @return [void]
     def fire_focus_hooks(previous, focused)
       unless focused.equal?(previous)
-        previous&.__send__(:on_blur)
+        previous&.__send__(:handle_blur)
         return unless @focused.equal?(focused)
       end
-      @focused&.__send__(:on_focus)
+      @focused&.__send__(:handle_focus)
       @on_focus_changed&.call unless @focused.equal?(previous)
     end
 
@@ -848,7 +886,7 @@ module Tuile
     # thread as an {EventQueue::BackgroundColorEvent}.
     # @param scheme [Symbol] `:dark` or `:light`.
     # @return [void]
-    def on_color_scheme(scheme)
+    def handle_color_scheme(scheme)
       @color_scheme = scheme
       self.theme = @theme_def.for(@color_scheme)
       print TerminalBackground::QUERY
@@ -861,11 +899,11 @@ module Tuile
     # would otherwise lose the color it gave us at startup, permanently.
     # @param color [Color]
     # @return [void]
-    def on_background_color(color)
+    def handle_background_color(color)
       return if @background_color == color
 
       @background_color = color
-      @pane&.on_tree { _1.__send__(:on_theme_changed) }
+      @pane&.walk_tree { _1.__send__(:handle_theme_changed) }
       needs_full_repaint
     end
 
@@ -882,7 +920,7 @@ module Tuile
       return false if scope.nil?
 
       stops = []
-      scope.on_shown_tree { |c| stops << c if c.tab_stop? }
+      scope.walk_shown_tree { |c| stops << c if c.tab_stop? }
       return false if stops.empty?
 
       idx = @focused.nil? ? nil : stops.index(@focused)
@@ -940,11 +978,14 @@ module Tuile
     #      default `over_popups: false` fires only when no modal popup is open
     #      (otherwise the modal popup receives the key normally). A non-modal
     #      overlay doesn't suppress global shortcuts.
-    #   3. {ScreenPane#handle_key} — delivery to {#focused}, bubbling up the
+    #   3. {ScreenPane#handle_key?} — delivery to {#focused}, bubbling up the
     #      focus chain to the scope root.
     # @param key [String]
     # @return [Boolean] true if the key was handled by some window.
-    def handle_key(key)
+    def handle_key?(key)
+      # A key is one of the grab's releases: a terminal loses a release over ssh
+      # and tmux, and a stuck grab would swallow every later drag.
+      @mouse_router.release_grab
       case key
       when Keys::TAB
         focus_next
@@ -958,25 +999,21 @@ module Tuile
           shortcut.block.call
           true
         else
-          @pane.handle_key(key)
+          @pane.handle_key?(key)
         end
       end
     end
 
-    # Finds target window and calls {Component::Window#handle_mouse}.
-    # @param event [MouseEvent]
-    # @return [void]
-    def handle_mouse(event) = @pane.handle_mouse(event)
-
     # Delivers pasted text to {#focused} ({ScreenPane#handle_paste}).
     #
     # Deliberately *not* the key ladder: a paste is not a keystroke, so it skips
     # Tab traversal and the global-shortcut registry entirely, goes straight to
     # delivery, and does not bubble to ancestors the way a key does. Unhandled
     # text is dropped — there is no fallback that replays it as keys, which
-    # would put back the very ambiguity mode 2004 exists to remove.
+    # would put back the very ambiguity mode 2004 exists to remove — and with no
+    # alternative delivery, no verdict to carry either.
     # @param text [String]
-    # @return [Boolean] true if the focused component consumed it.
+    # @return [void]
     def handle_paste(text) = @pane.handle_paste(text)
 
     # @return [void]
@@ -985,19 +1022,19 @@ module Tuile
         case event
         when EventQueue::KeyEvent
           key = event.key
-          handled = handle_key(key)
+          handled = handle_key?(key)
           @event_queue.stop if !handled && ["q", Keys::ESC].include?(key)
         when EventQueue::PasteEvent
           handle_paste(event.text)
-        when MouseEvent
+        when Mouse::Event
           handle_mouse(event)
         when EventQueue::TTYSizeEvent
           @size = event.size
           layout
         when EventQueue::ColorSchemeEvent
-          on_color_scheme(event.scheme)
+          handle_color_scheme(event.scheme)
         when EventQueue::BackgroundColorEvent
-          on_background_color(event.color)
+          handle_background_color(event.color)
         when EventQueue::EmptyQueueEvent
           repaint
         when Proc

data/lib/tuile/screen_pane.rb

@@ -8,7 +8,7 @@ module Tuile
   # {#content} and the {#popups} stack. Putting them under a single Component
   # parent gives focus traversal a real root, makes {Component#attached?} a
   # one-liner, and lets popup-focus repair fall out of the standard
-  # {Component#on_child_removed} hook.
+  # {Component#handle_child_removed} hook.
   #
   # The pane owns no chrome of its own — no status bar, no reserved row.
   # {#content} gets the full pane rect, and an app that wants a status line
@@ -79,7 +79,7 @@ module Tuile
         window.center
         screen.focused = window
       end
-      window.on_tree { |c| screen.invalidate(c) }
+      window.walk_tree { |c| screen.invalidate(c) }
     end
 
     # Removes a popup. If the popup held focus, focus shifts to the now-topmost
@@ -102,7 +102,7 @@ module Tuile
       @removing_popup_prior = nil
     end
 
-    # Unmounts everything: each child is detached — firing {Component#on_detached}
+    # Unmounts everything: each child is detached — firing {Component#handle_detached}
     # down its subtree — and every slot is emptied. Terminal; the pane isn't
     # reusable afterwards, and {Screen#close} is its only caller.
     #
@@ -113,7 +113,7 @@ module Tuile
     # components, which is the desync the tree API exists to prevent.
     # @return [void]
     def detach_all
-      screen.focused = nil # …so the focus repair in on_child_removed has nothing to do
+      screen.focused = nil # …so the focus repair in handle_child_removed has nothing to do
       children.dup.each { detach_child(_1) }
       @content = nil
       @popups.clear
@@ -157,7 +157,7 @@ module Tuile
     def repaint; end
 
     # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
-    # the first component whose `handle_key` returns true wins.
+    # the first component whose `handle_key?` returns true wins.
     #
     # Bubbling stops at the *scope* root: the topmost *modal* popup when one is
     # open, else the tiled {#content}. Focus that is nil or sits outside the
@@ -173,7 +173,7 @@ module Tuile
     # hijacked).
     # @param key [String]
     # @return [Boolean] true if the key was handled.
-    def handle_key(key)
+    def handle_key?(key)
       scope = modal_popup || @content
       return false if scope.nil?
 
@@ -182,38 +182,39 @@ module Tuile
 
     # Delivers pasted text to {Screen#focused} — and to nobody else.
     #
-    # Scoped exactly like {#handle_key} (focus that is nil or sits outside the
+    # Scoped exactly like {#handle_key?} (focus that is nil or sits outside the
     # modal scope receives nothing, which is what keeps a popup modal) but
     # **not bubbled**: an ancestor is never offered a paste its descendant
     # declined, and unhandled text is dropped. Why keys bubble and pastes
     # don't: `D_bracketed_paste`.
     # @param text [String]
-    # @return [Boolean] true if the focused component consumed it.
+    # @return [void]
     def handle_paste(text)
       scope = modal_popup || @content
-      return false if scope.nil?
+      return if scope.nil?
 
       chain = focus_chain(scope)
-      return false if chain.nil?
+      return if chain.nil?
 
       chain.first.handle_paste(text)
     end
 
-    # Mouse events check popups in reverse stacking order (topmost first), and
-    # fall through to content only when no popup is hit *and* no modal popup is
-    # open. This preserves modal click-blocking — an open modal eats clicks
-    # even outside its rect — while a non-modal overlay blocks nothing: clicks
-    # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
-    # content beneath.
-    #
-    # A left click also *dismisses* the open popups it landed outside of that
-    # asked for it ({Component::Overlay#close_on_outside_click?}). That is a
-    # second thing happening on a click, but not a second dispatch: the click is
-    # still delivered exactly once, down one chain, and a dismissed popup is
+    # Where {Mouse::Router} starts its walk for a pointer at `point`: the
+    # topmost popup containing it, else {#content} — unless a modal popup is
+    # open, which eats the event even outside its rect. A non-modal overlay
+    # blocks nothing: a point outside it reaches the content beneath.
+    # @api private
+    # @param point [Point]
+    # @return [Component, nil]
+    def mouse_root_at(point) = popup_at(point) || (@content if modal_popup.nil?)
+
+    # Runs the press delivery in the block, then *dismisses* the open popups a
+    # left press landed outside of that asked for it
+    # ({Component::Overlay#close_on_outside_click?}). A dismissed popup is
     # closed rather than told.
     #
     # "Outside" is measured against the {Component::Overlay#owner} chain, not
-    # against one rect and not against stacking order: the popup the click hit
+    # against one rect and not against stacking order: the popup the press hit
     # is kept, and so is every popup that one *belongs to*, transitively. That
     # is what stops a dialog being dismissed by a click on a dropdown its own
     # field opened, and a menu cascade being dismissed by a click on one of its
@@ -223,10 +224,10 @@ module Tuile
     #
     # Two halves of the ordering are load-bearing, and both are specced:
     #
-    # - **Snapshot before routing.** A popup the delivered click *opens* must
+    # - **Snapshot before the block.** A popup the delivered press *opens* must
     #   not be in the set (it would immediately dismiss itself — every
     #   {Component::Select} would be unopenable by mouse).
-    # - **Close after routing.** A widget toggling its own overlay from a click
+    # - **Close after the block.** A widget toggling its own overlay from a press
     #   on its face closes it during delivery, and {Component::Popup#close} is
     #   idempotent, so the dismissal no-ops. Close *first* and the widget sees
     #   a shut overlay and reopens it — a Select's dropdown could then never be
@@ -234,19 +235,19 @@ module Tuile
     #
     # The snapshot is a fresh array for a third reason: a handler may close
     # further popups, and `@popups` must not be mutated mid-iteration.
-    # @param event [MouseEvent]
+    # @api private
+    # @param point [Point]
+    # @param left [Boolean] whether the press was the left button; no other
+    #   button dismisses.
+    # @yield the press delivery.
     # @return [void]
-    def handle_mouse(event)
-      hit = @popups.reverse_each.find { _1.rect.contains?(event.point) }
-      dismissable = event.button == :left ? @popups - kept_by(hit) : []
-
-      clicked = hit || (@content if modal_popup.nil?)
-      clicked&.handle_mouse(event)
-
+    def dismissing_popups_outside(point, left:)
+      dismissable = left ? @popups - kept_by(popup_at(point)) : []
+      yield
       dismissable.each { _1.close if _1.close_on_outside_click? }
     end
 
-    # Focus repair when a child detaches. Default {Component#on_child_removed}
+    # Focus repair when a child detaches. Default {Component#handle_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
     # Instead, route focus to the first interactable widget in the now-topmost
     # modal popup; falling back to the focus snapshotted when this popup was opened
@@ -259,7 +260,7 @@ module Tuile
     # `q`/ESC still has somewhere to dispatch from.
     # @param child [Component]
     # @return [void]
-    def on_child_removed(child)
+    def handle_child_removed(child)
       return unless attached?
 
       f = screen.focused
@@ -301,6 +302,10 @@ module Tuile
       kept
     end
 
+    # @param point [Point]
+    # @return [Component::Overlay, nil] the topmost popup containing `point`.
+    def popup_at(point) = @popups.reverse_each.find { _1.rect.contains?(point) }
+
     # @param component [Component, nil]
     # @return [Component::Overlay, nil] `component` itself when it is an
     #   overlay, else the nearest overlay above it, else nil.
@@ -321,7 +326,7 @@ module Tuile
       chain = focus_chain(scope)
       return false if chain.nil?
 
-      chain.each { |c| return true if c.handle_key(key) }
+      chain.each { |c| return true if c.handle_key?(key) }
       false
     end
 
@@ -350,7 +355,7 @@ module Tuile
     def first_tab_stop_or_root(root)
       return nil if root.nil? || !root.visible?
 
-      root.on_shown_tree { |c| return c if c.tab_stop? }
+      root.walk_shown_tree { |c| return c if c.tab_stop? }
       root
     end
   end

data/lib/tuile/styled_string.rb

@@ -410,11 +410,11 @@ module Tuile
     #
     # `:rgi` credits width 2 only to [RGI](https://www.unicode.org/reports/tr51/)
     # sequences — the ones vendors actually ship a single glyph for — and *sums*
-    # the parts of anything else. That is the one setting never wrong in the
-    # dangerous direction: under-measuring lets a glyph overrun its cell, which
-    # shifts the rest of the row, desyncs the cursor and escapes the component's
-    # rect, while over-measuring leaves a blank column. `D_cluster_width` has the
-    # per-setting reasoning.
+    # the parts of anything else, erring only in the direction that cannot escape
+    # a component: {Buffer#flush} emits a dirty run contiguously, so a mis-measure
+    # of either sign shifts the rest of that run, but only an under-measure shifts
+    # it right, into a neighbour whose cells are clean and so never repainted.
+    # `D_cluster_width` has the per-setting reasoning.
     # @return [Symbol]
     EMOJI_WIDTH = :rgi