tuile 0.13.0 → 0.15.0

data/lib/tuile/screen.rb

@@ -16,13 +16,13 @@ module Tuile
   # out its own children), the modal/overlay {#popups} stack (opened via
   # {Component::Popup#open}, drawn on top of the content). Popups are *not*
   # sized from their content — each carries its own top-down
-  # {Component::Popup#size} — and they deliberately overdraw the content
+  # {Component::Popup#declared_size} — and they deliberately overdraw the content
   # without clipping.
   #
   # Tuile draws no chrome of its own: there is no status bar and no reserved
   # row, so {#content} gets the whole terminal. An app that wants a status line
   # builds one into its own layout and drives it from {#on_focus_changed=}
-  # (`D-status-bar`).
+  # (`D_status_bar`).
   #
   # ## Repaint model
   #
@@ -71,12 +71,20 @@ module Tuile
       # during :idle, at both ends of the screen's life. See {#check_locked}.
       @ui_thread = Thread.current
       @closed = false
-      @color_scheme = detect_scheme
+      background = detect_background
+      @color_scheme = background.scheme
+      @background_color = background.color
+      @color_depth = detect_color_depth
+      @locale = detect_locale
       @theme_def = ThemeDef.default
       @theme = @theme_def.for(@color_scheme)
       # Structural root of the component tree: holds tiled content and the
-      # popup stack.
+      # popup stack. Sized here rather than waiting for the first {#layout},
+      # for the same reason {#size} is seeded from {EventQueue::TTYSizeEvent}:
+      # an empty pane rect is an *ancestor* empty rect, and {#repaint}'s drain
+      # filter would take the whole tree with it.
       @pane = ScreenPane.new
+      @pane.rect = Rect.new(0, 0, @size.width, @size.height)
       @on_error = ->(e) { raise e }
       # App-level keyboard shortcuts dispatched by {#handle_key} before keys
       # reach the pane. See {#register_global_shortcut}.
@@ -84,7 +92,7 @@ module Tuile
       # The back buffer components paint into. {#repaint} flushes its diff to
       # the terminal, so only changed cells are emitted (flicker-free on any
       # terminal). Sized to the current viewport; {#layout} resizes it.
-      @buffer = Buffer.new(@size)
+      @buffer = Buffer.new(@size, color_depth: @color_depth)
     end
 
     # Entry in the global shortcut registry: the block to run, and whether it
@@ -118,6 +126,17 @@ module Tuile
     # @return [Symbol] `:light` or `:dark`
     attr_reader :color_scheme
 
+    # How many colors this terminal can show ({ColorDepth::DEPTHS}), detected
+    # at construction. {Buffer#flush} degrades every color it emits to this,
+    # so an app may compute an RGB tint — say from {#background_color} — and
+    # paint with it, whatever the terminal turns out to understand.
+    #
+    # Deliberately read-only: detection runs once and the answer can't change
+    # mid-session. Override a terminal that reports itself wrong through
+    # {ColorDepth::OVERRIDE_ENV} instead.
+    # @return [Symbol]
+    attr_reader :color_depth
+
     # @return [Buffer] the back buffer components paint into
     #   ({Buffer#set_text} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader :buffer
@@ -149,6 +168,12 @@ module Tuile
       @@instance
     end
 
+    # Whether {.instance} would answer rather than raise — for code that must
+    # work with no screen in the process at all, which a detached component
+    # tree legitimately is (`Component#locale` is the one caller in the gem).
+    # @return [Boolean]
+    def self.instance? = !@@instance.nil?
+
     # @return [Component, nil] tiled content (forwarded to {ScreenPane}).
     def content = @pane.content
 
@@ -183,6 +208,26 @@ module Tuile
     # @return [ThemeDef]
     attr_reader :theme_def
 
+    # The terminal's own background, as it reported it — for deriving a
+    # color *from* the background rather than picking one against it. A pane
+    # tinted a few percent off it sits right on any terminal, where a fixed
+    # near-neutral only sits right near the one it was tuned on:
+    #
+    #   bg = screen.background_color
+    #   sidebar.bg_color =
+    #     bg ? Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }) : FALLBACK_TINT
+    #
+    # **Nil is the normal case, not an edge** — a terminal answering only
+    # `COLORFGBG`, or neither probe, reports no RGB at all. Keep a fallback.
+    #
+    # 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
+    # does — a background-derived tint *is* a theme-derived color.
+    # @return [Color, nil]
+    attr_reader :background_color
+
     # Replaces the theme definition and immediately applies the member
     # matching the current color scheme (via {#theme=}, so the whole UI
     # restyles — or nothing repaints if that member equals the current
@@ -211,12 +256,50 @@ module Tuile
       return if @theme == new_theme
 
       @theme = new_theme
-      @pane&.on_tree(&:on_theme_changed)
+      # `__send__`, not `&:on_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) }
+      needs_full_repaint
+    end
+
+    # The formatting conventions this session renders and parses by — date
+    # formats, the calendar, month and weekday names, the decimal separator.
+    # Detected once at construction from {Locale.system}; {Locale::ISO} when
+    # the environment says nothing.
+    #
+    # Read it at paint or parse time and never cache it in an ivar, for the
+    # same reason {#theme} says so: {#locale=} can replace it mid-session.
+    # @return [Locale]
+    attr_reader :locale
+
+    # Replaces the locale: fires {Component#on_locale_changed} across the
+    # attached tree and invalidates every attached component. No-op when
+    # `new_locale` equals the current one.
+    #
+    #   screen.locale = Locale::ISO.with(date_formats: ["%d.%m.%Y"])
+    #
+    # Note this can invalidate what a user has half-typed: a field's buffer
+    # reparses under the new grammar, and one that no longer parses reads as
+    # bad input.
+    # @param new_locale [Locale]
+    # @return [void]
+    # @raise [TypeError] unless `new_locale` is a {Locale}.
+    def locale=(new_locale)
+      raise TypeError, "expected Locale, got #{new_locale.inspect}" unless new_locale.is_a?(Locale)
+
+      check_locked
+      return if @locale == new_locale
+
+      @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) }
       needs_full_repaint
     end
 
-    # @return [Array<Component>] currently active popup components (forwarded
-    #   to {ScreenPane}). The array must not be modified!
+    # @return [Array<Component::Overlay>] the open overlay stack — both
+    #   {Component::Popup} modals and bare {Component::Overlay}s — in stacking
+    #   order (forwarded to {ScreenPane}). The array must not be modified!
     def popups = @pane.popups
 
     # @return [EventQueue] the event queue.
@@ -282,6 +365,15 @@ module Tuile
     # Sets the focused {Component}. Focused component receives keyboard events.
     # All focusable components live under {#pane}, so this is a single uniform
     # path (no separate popup-vs-content branches).
+    #
+    # A hidden target — or one under a hidden ancestor — raises, exactly as a
+    # detached one does: focusing it would park the hardware cursor inside
+    # 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
+    # what took it, then {#on_focus_changed}. The outer two are edge-triggered
+    # and `on_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)
@@ -295,6 +387,7 @@ module Tuile
         @pane.on_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)
 
         @focused = focused
         active = Set[focused]
@@ -304,9 +397,8 @@ module Tuile
           cursor = cursor.parent
         end
         @pane.on_tree { _1.active = active.include?(_1) }
-        @focused.on_focus
       end
-      @on_focus_changed&.call unless @focused.equal?(previous)
+      fire_focus_hooks(previous, focused)
     end
 
     # Called after the focused component *changes* — including to and from
@@ -316,7 +408,7 @@ module Tuile
     #
     # This is the hook an app drives its own status line from. Tuile owns no
     # status bar and reserves no row: build a {Component::Label} into your own
-    # layout and fill it here (`D-status-bar`).
+    # layout and fill it here (`D_status_bar`).
     #
     #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
     #
@@ -335,10 +427,10 @@ module Tuile
     # @return [Proc, nil]
     attr_accessor :on_focus_changed
 
-    # Internal — use {Component::Popup#open} instead. Adds the popup to
-    # {#pane}, centers and focuses it.
+    # Internal — use {Component::Overlay#open} instead. Adds the overlay to
+    # {#pane}; a {Component::Popup} is additionally centered and focused.
     # @api private
-    # @param window [Component::Popup]
+    # @param window [Component::Overlay] any overlay, modal or not.
     # @return [void]
     def add_popup(window)
       check_locked
@@ -469,12 +561,12 @@ module Tuile
       @global_shortcuts.delete(key)
     end
 
-    # Internal — use {Component::Popup#close} instead. Removes the popup
+    # Internal — use {Component::Overlay#close} instead. Removes the overlay
     # from {#pane}, repairs focus, and repaints the scene.
     #
-    # Does nothing if the window is not open on this screen.
+    # Does nothing if the overlay is not open on this screen.
     # @api private
-    # @param window [Component::Popup]
+    # @param window [Component::Overlay] any overlay, modal or not.
     # @return [void]
     def remove_popup(window)
       check_locked
@@ -497,10 +589,10 @@ module Tuile
       @pane&.on_tree { invalidate _1 }
     end
 
-    # Internal — use {Component::Popup#open?} instead.
+    # Internal — use {Component::Overlay#open?} instead.
     # @api private
-    # @param window [Component::Popup]
-    # @return [Boolean] true if this popup is currently mounted.
+    # @param window [Component::Overlay] any overlay, modal or not.
+    # @return [Boolean] true if this overlay is currently mounted.
     def has_popup?(window) # rubocop:disable Naming/PredicatePrefix
       check_locked
       @pane.has_popup?(window)
@@ -546,15 +638,20 @@ module Tuile
     end
 
     # Writes terminal-housekeeping escapes straight to stdout: {#clear},
-    # mouse-tracking start/stop, the color-scheme notify toggles, cursor-show
-    # on teardown. Component painting does *not* go through here anymore — it
-    # writes into {#buffer}, which {#repaint} diffs and {#emit}s. {FakeScreen}
-    # overrides this (and {#emit}) to capture into `@prints` instead of the
-    # test runner's stdout.
+    # mouse-tracking start/stop, the color-scheme notify toggles, the OSC 11
+    # background re-probe, cursor-show on teardown. Component painting does
+    # *not* go through here anymore — it writes into {#buffer}, which
+    # {#repaint} diffs and {#emit}s. {FakeScreen} overrides this (and
+    # {#emit}) to capture into `@prints` instead of the test runner's stdout.
+    #
+    # Flushed, like {#emit}: none of these escapes ends in a newline, and a
+    # buffered stdout would hold a *query* — one whose reply the app is
+    # waiting on — until the next frame went out.
     # @param args [String] stuff to print.
     # @return [void]
     def print(*args)
       Kernel.print(*args)
+      $stdout.flush
     end
 
     # Rings the terminal bell ({Ansi::BEL}) — the signal for a keystroke that
@@ -594,12 +691,31 @@ module Tuile
 
       did_paint = false
       until @invalidated.empty?
-        # Defensive filter: a component can become detached between enqueue
-        # and drain (popup close, sibling removed mid-event-handling, focus
-        # repair). Detached components have no place on the screen and must
-        # never paint, even though Component#invalidate already gates them
-        # out — this catches the case where attachment changed since.
-        @invalidated.delete_if { |c| !c.attached? }
+        # Defensive filter, two ways a queued component has no place on the
+        # screen by the time we drain it. It became *detached* since (popup
+        # close, sibling removed mid-event-handling, focus repair) — which
+        # Component#invalidate gates at enqueue, so this catches only a change
+        # since. Or it sits under an *empty rect*, its own or any ancestor's,
+        # which is how a subtree is collapsed.
+        #
+        # The self half is belt-and-braces — every #repaint opens with the same
+        # `return if rect.empty?`, and that stays: it is each component's own
+        # contract, local to the method an app subclass calls `super` on. The
+        # ancestor half is the one that does work no component can do for
+        # itself, so a container that forgets to zero its children leaves them
+        # inert rather than painting them at stale coordinates
+        # (`D_empty_ancestor`).
+        #
+        # {Component#visible?} rides the same walk, one more term in the same
+        # AND — a different question (geometry says *where*, the flag says
+        # *whether*) with the same answer for this frame (`D_visibility`).
+        @invalidated.delete_if do |c|
+          next true unless c.attached?
+
+          blocked = c
+          blocked = blocked.parent while blocked && !blocked.rect.empty? && blocked.visible?
+          !blocked.nil?
+        end
         break if @invalidated.empty?
 
         did_paint = true
@@ -624,12 +740,22 @@ module Tuile
           tiled_invalidated = true
         end
 
-        # Popups on top: the whole stack when a tiled repaint may have clobbered
-        # cells they share in the buffer, else just the invalidated popup
-        # components. Overdraw into the buffer is free (only net-visible cell
-        # changes reach the terminal), so reasserting the stack is cheap.
+        # Popups on top: a layer repaints whole whenever anything *beneath* it —
+        # the tiled tree, or a lower popup — repaints, else just its invalidated
+        # members. Layer-by-layer rather than one tiled_invalidated bool because
+        # the drain loops: a lower popup's repaint cascade re-invalidates
+        # children into the *next* iteration (its gap-clearing Layout wipes and
+        # re-queues a button, say), and that iteration has no tiled repaint —
+        # only the full re-assert of every layer above keeps the stacking order
+        # true across iterations (screen_spec pins it with two overlapping
+        # popups). Overdraw into the buffer is free (only net-visible cell
+        # changes reach the terminal), so reasserting layers is cheap.
+        below_repainted = tiled_invalidated
         popups.each do |p|
-          p.on_tree { |c| repaint << c if tiled_invalidated || @invalidated.include?(c) }
+          layer_invalidated = false
+          p.on_tree { |c| layer_invalidated ||= @invalidated.include?(c) }
+          p.on_tree { |c| repaint << c if below_repainted || @invalidated.include?(c) }
+          below_repainted ||= layer_invalidated
         end
 
         @repainting = repaint.to_set
@@ -654,25 +780,93 @@ module Tuile
 
     private
 
-    # Startup color scheme: `:light` when {TerminalBackground.detect}
-    # reports a light terminal background, `:dark` otherwise (including
-    # when detection is inconclusive). Runs in the constructor — the
-    # OSC 11 reply arrives on stdin, which is only safe to read before
-    # {EventQueue#start_key_thread} owns it. {FakeScreen} overrides this
-    # to pin `:dark`, keeping specs deterministic and off the test
-    # runner's TTY.
-    # @return [Symbol] `:dark` or `:light`.
-    def detect_scheme
-      TerminalBackground.detect == :light ? :light : :dark
+    # Whether `component` is out of the user's reach because it or an ancestor
+    # is {Component#visible? hidden}.
+    #
+    # 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}).
+    # @param component [Component]
+    # @return [Boolean]
+    def hidden?(component)
+      cursor = component
+      cursor = cursor.parent while cursor&.visible?
+      !cursor.nil?
+    end
+
+    # The tail of {#focused=}: blur, then focus, then the app notice.
+    #
+    # A hook may reassign {#focused}; that nested call has already run this whole
+    # sequence for the target it chose, so this one stops rather than announcing
+    # a focus that no longer holds.
+    # @param previous [Component, nil] what held focus before the assignment.
+    # @param focused [Component, nil] what the assignment asked for.
+    # @return [void]
+    def fire_focus_hooks(previous, focused)
+      unless focused.equal?(previous)
+        previous&.__send__(:on_blur)
+        return unless @focused.equal?(focused)
+      end
+      @focused&.__send__(:on_focus)
+      @on_focus_changed&.call unless @focused.equal?(previous)
+    end
+
+    # The startup background probe, seeding {#theme} and
+    # {#background_color}. Inconclusive detection means `:dark` with no
+    # color. Runs in the constructor — the OSC 11 reply arrives on stdin,
+    # which is only safe to read before {EventQueue#start_key_thread} owns
+    # it. {FakeScreen} overrides this to pin the result, keeping specs
+    # deterministic and off the test runner's TTY.
+    # @return [TerminalBackground::Result]
+    def detect_background
+      TerminalBackground.detect || TerminalBackground::Result.new(scheme: :dark, color: nil)
     end
 
+    # The startup color-depth probe, seeding {#color_depth}. Reads the
+    # environment only, so unlike {#detect_background} it has no timing
+    # constraint. {FakeScreen} overrides it to pin the result, keeping specs
+    # off whatever `COLORTERM` the test runner happens to carry.
+    # @return [Symbol]
+    def detect_color_depth = ColorDepth.detect
+
+    # The startup locale probe, seeding {#locale}. Shells out (see
+    # {Locale.system}), so unlike {#detect_background} it touches no terminal
+    # stream and has no timing constraint. {FakeScreen} overrides it to pin
+    # {Locale::ISO}, keeping specs off whatever `LC_TIME` the test runner
+    # happens to carry — and out of a subprocess per example.
+    # @return [Locale]
+    def detect_locale = Locale.system
+
     # An OS appearance flip arrived (mode-2031 report): remember the
-    # scheme and apply the matching member of {#theme_def}.
+    # scheme, apply the matching member of {#theme_def}, and re-probe for
+    # the new background RGB, which the report does not carry.
+    #
+    # The query goes out from *this* thread — the event-loop thread, which
+    # also owns {#emit} — so its bytes can never land inside a frame's
+    # synchronized-output batch. The reply comes back through the key
+    # thread as an {EventQueue::BackgroundColorEvent}.
     # @param scheme [Symbol] `:dark` or `:light`.
     # @return [void]
     def on_color_scheme(scheme)
       @color_scheme = scheme
       self.theme = @theme_def.for(@color_scheme)
+      print TerminalBackground::QUERY
+    end
+
+    # The re-probe answered: adopt the color and restyle, since an app's
+    # background-derived tints are now a scheme behind. Deliberately keeps
+    # the previous color until the reply lands rather than blanking it on
+    # the flip — a terminal that reports mode-2031 flips but not OSC 11
+    # would otherwise lose the color it gave us at startup, permanently.
+    # @param color [Color]
+    # @return [void]
+    def on_background_color(color)
+      return if @background_color == color
+
+      @background_color = color
+      @pane&.on_tree { _1.__send__(:on_theme_changed) }
+      needs_full_repaint
     end
 
     # Walks the current modal scope in pre-order, collects tab stops, and
@@ -688,7 +882,7 @@ module Tuile
       return false if scope.nil?
 
       stops = []
-      scope.on_tree { |c| stops << c if c.tab_stop? }
+      scope.on_shown_tree { |c| stops << c if c.tab_stop? }
       return false if stops.empty?
 
       idx = @focused.nil? ? nil : stops.index(@focused)
@@ -774,15 +968,15 @@ module Tuile
     # @return [void]
     def handle_mouse(event) = @pane.handle_mouse(event)
 
-    # Delivers pasted text down the focus chain ({ScreenPane#handle_paste}).
+    # 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 and goes
-    # straight to delivery. 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.
+    # 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.
     # @param text [String]
-    # @return [Boolean] true if some component consumed it.
+    # @return [Boolean] true if the focused component consumed it.
     def handle_paste(text) = @pane.handle_paste(text)
 
     # @return [void]
@@ -802,6 +996,8 @@ module Tuile
           layout
         when EventQueue::ColorSchemeEvent
           on_color_scheme(event.scheme)
+        when EventQueue::BackgroundColorEvent
+          on_background_color(event.color)
         when EventQueue::EmptyQueueEvent
           repaint
         when Proc

data/lib/tuile/screen_pane.rb

@@ -13,7 +13,7 @@ module Tuile
   # 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
   # builds one into its own layout and drives it from
-  # {Screen#on_focus_changed=} (`D-status-bar`).
+  # {Screen#on_focus_changed=} (`D_status_bar`).
   #
   # The pane is not a {Component::Layout}: popups deliberately overlap content
   # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
@@ -31,9 +31,10 @@ module Tuile
 
     # @return [Component, nil] the tiled content component.
     attr_reader :content
-    # @return [Array<Component>] overlay popups in stacking order; last is
-    #   topmost. Holds both modal popups and non-modal overlays
-    #   ({Component::Popup#modal?}). The array must not be mutated by callers.
+    # @return [Array<Component::Overlay>] the open overlays in stacking order;
+    #   last is topmost. Holds both {Component::Popup} modals and bare
+    #   {Component::Overlay}s ({Component::Overlay#modal?}). The array must not
+    #   be mutated by callers.
     attr_reader :popups
 
     def focusable? = false
@@ -54,21 +55,21 @@ module Tuile
       layout
     end
 
-    # Adds a popup and invalidates it for repaint. A modal popup is centered
-    # and grabs focus; a non-modal overlay ({Component::Popup#modal?} false) is
-    # left wherever the caller positions it and does *not* take focus, so the
-    # component that was focused keeps the cursor and keeps receiving keys —
-    # the overlay floats above the content, driven from app code.
+    # Adds an overlay and invalidates it for repaint. A {Component::Popup} is
+    # centered and grabs focus; a bare {Component::Overlay} is left wherever
+    # the caller positioned it and does *not* take focus, so the component that
+    # was focused keeps the cursor and keeps receiving keys — the overlay
+    # floats above the content, driven from app code.
     #
-    # The *whole subtree* is invalidated, not just the popup wrapper (which
+    # The *whole subtree* is invalidated, not just the overlay wrapper (which
     # paints nothing on its own): a reopened popup may land on cells that the
     # tiled content has since overpainted, and if its rect is unchanged from
     # last time its content components won't re-invalidate themselves — so
-    # without this the popup's contents would stay blank on reopen.
-    # @param window [Component::Popup]
+    # without this the overlay's contents would stay blank on reopen.
+    # @param window [Component::Overlay] any overlay, modal or not.
     # @return [void]
     def add_popup(window)
-      raise TypeError, "expected Popup, got #{window.inspect}" unless window.is_a? Component::Popup
+      raise TypeError, "expected Overlay, got #{window.inspect}" unless window.is_a? Component::Overlay
       raise ArgumentError, "#{window} already has a parent #{window.parent}" unless window.parent.nil?
 
       @popup_prior_focus[window] = screen.focused
@@ -123,11 +124,11 @@ module Tuile
     # @return [Boolean] true if this pane currently hosts the popup.
     def has_popup?(window) = @popups.include?(window) # rubocop:disable Naming/PredicatePrefix
 
-    # @return [Component::Popup, nil] the topmost *modal* popup, or nil when
-    #   only non-modal overlays (or no popups) are open. This is the "modal
+    # @return [Component::Popup, nil] the topmost modal overlay, or nil when
+    #   only bare {Component::Overlay}s (or none) are open. This is the "modal
     #   owner": the popup that scopes key dispatch, blocks mouse clicks, and
-    #   confines Tab cycling. Non-modal overlays are excluded — they float above
-    #   the content without capturing input.
+    #   confines Tab cycling. Bare overlays are excluded — they float above the
+    #   content without capturing input.
     def modal_popup = @popups.reverse_each.find(&:modal?)
 
     # Re-lays out children whenever the pane's own rect changes.
@@ -139,7 +140,7 @@ module Tuile
     end
 
     # Gives {#content} the whole pane rect — the pane reserves nothing for
-    # itself. Each popup re-resolves its {Component::Popup#size} against the new
+    # itself. Each popup re-resolves its {Component::Popup#declared_size} against the new
     # screen via {Component::Popup#reposition} — so a {Fraction} size tracks
     # resize — repositioning itself (modal popups recenter; non-modal overlays
     # keep the top-left their owner assigned).
@@ -179,11 +180,15 @@ module Tuile
       bubble_key(key, scope)
     end
 
-    # Delivers pasted text along the same focus chain {#handle_key} bubbles
-    # along, and with the same scoping — first {Component#handle_paste}
-    # returning true wins.
+    # Delivers pasted text to {Screen#focused} — and to nobody else.
+    #
+    # 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 text was consumed.
+    # @return [Boolean] true if the focused component consumed it.
     def handle_paste(text)
       scope = modal_popup || @content
       return false if scope.nil?
@@ -191,8 +196,7 @@ module Tuile
       chain = focus_chain(scope)
       return false if chain.nil?
 
-      chain.each { |c| return true if c.handle_paste(text) }
-      false
+      chain.first.handle_paste(text)
     end
 
     # Mouse events check popups in reverse stacking order (topmost first), and
@@ -203,12 +207,12 @@ module Tuile
     # content beneath.
     #
     # A left click also *dismisses* the open popups it landed outside of that
-    # asked for it ({Component::Popup#close_on_outside_click?}). That is a
+    # 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
     # closed rather than told.
     #
-    # "Outside" is measured against the {Component::Popup#owner} chain, not
+    # "Outside" is measured against the {Component::Overlay#owner} chain, not
     # against one rect and not against stacking order: the popup the click 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
@@ -278,29 +282,30 @@ module Tuile
 
     private
 
-    # The popups a click counts as landing *inside*: the one it hit, plus every
-    # popup that one belongs to, up the {Component::Popup#owner} chain. An owner
-    # is any component, so it is resolved to the popup enclosing it (a popup
-    # resolves to itself) — which keeps the relationship a live tree question
-    # rather than one frozen when the overlay opened. The `include?` guard makes
-    # a mis-wired cycle terminate instead of hanging the UI thread.
-    # @param hit [Component::Popup, nil] the popup the click landed in, if any.
-    # @return [Array<Component::Popup>]
+    # The overlays a click counts as landing *inside*: the one it hit, plus
+    # every overlay that one belongs to, up the {Component::Overlay#owner}
+    # chain. An owner is any component, so it is resolved to the overlay
+    # enclosing it (an overlay resolves to itself) — which keeps the
+    # relationship a live tree question rather than one frozen when the overlay
+    # opened. The `include?` guard makes a mis-wired cycle terminate instead of
+    # hanging the UI thread.
+    # @param hit [Component::Overlay, nil] the overlay the click landed in, if any.
+    # @return [Array<Component::Overlay>]
     def kept_by(hit)
       kept = []
-      popup = hit
-      while popup && !kept.include?(popup)
-        kept << popup
-        popup = enclosing_popup(popup.owner)
+      overlay = hit
+      while overlay && !kept.include?(overlay)
+        kept << overlay
+        overlay = enclosing_popup(overlay.owner)
       end
       kept
     end
 
     # @param component [Component, nil]
-    # @return [Component::Popup, nil] `component` itself when it is a popup,
-    #   else the nearest popup above it, else nil.
+    # @return [Component::Overlay, nil] `component` itself when it is an
+    #   overlay, else the nearest overlay above it, else nil.
     def enclosing_popup(component)
-      component = component.parent until component.nil? || component.is_a?(Component::Popup)
+      component = component.parent until component.nil? || component.is_a?(Component::Overlay)
       component
     end
 
@@ -338,13 +343,14 @@ module Tuile
 
     # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling
     # back to `root` itself when the subtree has no tab stops. Returns `nil`
-    # if `root` is `nil`.
+    # if `root` is `nil`, or if `root` is itself hidden — there is nothing in
+    # there to focus, so the caller falls through to its next candidate.
     # @param root [Component, nil]
     # @return [Component, nil]
     def first_tab_stop_or_root(root)
-      return nil if root.nil?
+      return nil if root.nil? || !root.visible?
 
-      root.on_tree { |c| return c if c.tab_stop? }
+      root.on_shown_tree { |c| return c if c.tab_stop? }
       root
     end
   end