tuile 0.16.0 → 0.17.0

data/lib/tuile/screen.rb

@@ -21,7 +21,7 @@ module Tuile
   #
   # 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=}
+  # builds one into its own layout and drives it from {#on_focus_changed}
   # (`D_status_bar`).
   #
   # ## Repaint model
@@ -55,15 +55,32 @@ module Tuile
   # {FakeScreen} — which captures output in memory — is what
   # {Screen.instance} returns under test.
   class Screen
+    extend Listeners::Declare
+
     # Class variable (not class instance var) so the singleton survives
     # subclassing — `FakeScreen < Screen` and `Screen.instance` see the same slot.
     @@instance = nil # rubocop:disable Style/ClassVars
 
+    # What {#on_focus_changed} fires.
+    #
+    # @!attribute [r] source
+    #   @return [Screen] the screen whose {#focused} changed; read {#focused}
+    #     for what it changed to.
+    FocusChangedEvent = Data.define(:source) { include Tuile::Event }
+
     def initialize
       @@instance = self # rubocop:disable Style/ClassVars
       @event_queue = EventQueue.new
       @size = EventQueue::TTYSizeEvent.create.size
       @invalidated = Set.new
+      # Whether some container may owe a {Component#relayout} — the O(1) gate
+      # that lets a no-op {#flush_layout} skip the walk; the containers' own
+      # flags are the queue.
+      @layout_pending = false
+      # A {#focused=} made inside a pass whose scroll and notice wait for the
+      # drain, and what was focused before the first such call.
+      @focus_deferred = false
+      @focus_deferred_from = nil
       # Components being repainted right now. A component may invalidate its
       # children during its repaint phase; this prevents double-draw.
       @repainting = Set.new
@@ -77,23 +94,26 @@ module Tuile
       @color_depth = detect_color_depth
       @locale = detect_locale
       @theme_def = ThemeDef.default
-      @theme = @theme_def.for(@color_scheme)
+      # The theme as assigned, derivation Procs and all; {#theme} is this
+      # resolved against {#background_color}, re-resolved when either changes.
+      @theme_source = @theme_def.for(@color_scheme)
+      @theme = @theme_source.resolve(@background_color)
       # Structural root of the component tree: holds tiled content and the
-      # popup stack. Sized here rather than waiting for the first {#layout},
+      # popup stack. Sized here rather than waiting for the first {#resize},
       # 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)
+      size_pane
       @mouse_router = Mouse::Router.new(self)
-      @on_error = ->(e) { raise e }
       # 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
       # the terminal, so only changed cells are emitted (flicker-free on any
-      # terminal). Sized to the current viewport; {#layout} resizes it.
+      # terminal). Sized to the current viewport; {#resize} resizes it.
       @buffer = Buffer.new(@size, color_depth: @color_depth)
+      @canvas = Canvas.new(@buffer)
     end
 
     # Entry in the global shortcut registry: the block to run, and whether it
@@ -142,25 +162,112 @@ module Tuile
     #   ({Buffer#set_text} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader :buffer
 
-    # Handler invoked when a {StandardError} escapes an event handler inside
-    # the event loop (e.g. a {Component::TextField}'s `on_change` raises).
+    # The untinted root canvas over {#buffer}, at the buffer's own origin,
+    # which {#canvas_for} derives every component's from. Nothing in `lib/`
+    # paints through it: a component paints onto the canvas it is *given*,
+    # never this one by name (`D_canvas`).
+    # @return [Canvas]
+    attr_reader :canvas
+
+    # The canvas `component` paints onto: one over {#buffer} carrying that
+    # component's resolved background, positioned where it sits on screen and
+    # bounded by what its ancestors allow — so it writes at `(0, 0)`, an
+    # inherited tint shows through and a scrolled-away row goes nowhere, with
+    # the component doing none of it. Summing the offsets is this method's job,
+    # which is what leaves every {Component#rect} parent-relative
+    # (`D_relative_rect`).
     #
-    # The default re-raises, so the exception propagates out of
-    # {#run_event_loop} and crashes the script with a stacktrace — unhandled
-    # exceptions are bugs and should be surfaced loudly.
+    #   label.repaint(screen.canvas_for(label))   # paint one component, as a spec does
     #
-    # Replace it when the host has somewhere visible to put errors, e.g. a
-    # {Component::LogWindow} wired to {Tuile.logger}:
+    # With `root:` it is positioned and bounded within that ancestor instead of
+    # the screen, so a subtree paints into a buffer of its own:
     #
-    #   screen.on_error = lambda do |e|
-    #     Tuile.logger.error("#{e.class}: #{e.message}\n#{e.backtrace&.join("\n")}")
-    #   end
+    #   screen.canvas_for(list, backend: Buffer.new(window.rect.size), root: window)
+    #
+    # The **sole converter** into backend coordinates: {#clip_for} answers in
+    # the component's own space and the one `moved_by` here puts it where
+    # {Canvas} keeps it, beside the origin (`D_clip`).
+    # @param component [Component]
+    # @param backend [Canvas::Backend] where the cells land; the screen's
+    #   {#buffer} unless given.
+    # @param root [Component, nil] `component` itself or one of its ancestors;
+    #   `nil` is the screen.
+    # @return [Canvas]
+    def canvas_for(component, backend: @buffer, root: nil)
+      # Built rather than derived from #canvas, since {Canvas#with} is
+      # block-only. __send__ because Component#bg is protected: the
+      # framework paints with it, an app never asks (`D_bg_surface`).
+      origin = component.to_screen(Point::ZERO)
+      unless root.nil?
+        base = root.to_screen(Point::ZERO)
+        origin = Point.new(origin.x - base.x, origin.y - base.y)
+      end
+      Canvas.new(backend, bg_color: component.__send__(:bg).effective,
+                          origin:,
+                          clip: clip_for(component, root:).moved_by(origin))
+    end
+
+    # The cells `component` may write, in **its own** coordinates: its
+    # {Component#local_rect} intersected with every ancestor's, each folded in
+    # as the walk climbs.
+    #
+    # Every component is bounded, and a component cannot widen its own bounds —
+    # which is why this lives here rather than as a hook on {Component}. A
+    # container that wants to allow its children *less* than its own box has no
+    # way to say so yet; `clip_rect_for(child)` is the shape that would, and it
+    # is deferred with no caller (`D_clip`).
+    #
+    # Resolved per call and never cached, like the origin it rides beside: an
+    # ancestor may scroll between two frames. {#clipped?} skips the fold
+    # entirely in the common case, which is what keeps that affordable.
+    # @param component [Component]
+    # @param root [Component, nil] the last ancestor folded in — `component`
+    #   itself or one of its ancestors; `nil` folds in every one.
+    # @return [Rect] never `nil`; {Rect#empty? empty} exactly when the component
+    #   can show nothing — scrolled clean out of its viewport, collapsed, or
+    #   under an ancestor allowing no cell. The own rect being folded in, that
+    #   one predicate answers *is any of this visible*.
+    def clip_for(component, root: nil)
+      return component.local_rect unless clipped?(component, root)
+
+      clip = component.local_rect
+      x = 0
+      y = 0
+      node = component
+      while !node.equal?(root) && (up = node.parent)
+        # Intersection only ever shrinks, so the rest of the chain cannot change
+        # an empty answer. Worth the test: a scroller's off-screen children land
+        # here on every scroll, one per row it is not showing (`D_clip`).
+        return clip if clip.empty?
+
+        x -= node.rect.left
+        y -= node.rect.top
+        clip = clip.intersect(up.local_rect.moved_by(Point.new(x, y)))
+        node = up
+      end
+      clip
+    end
+
+    # @!method on_error
+    #   Fired with an {EventQueue::ErrorEvent} when a {StandardError} escapes an
+    #   event handler inside the event loop (e.g. a {Component::TextField}'s
+    #   `on_value_change` listener raises). The one slot whose event carries no
+    #   `source`: its listener wants `error`.
+    #
+    #   **Empty means re-raise**, so the exception propagates out of
+    #   {#run_event_loop} and crashes the script with a stacktrace — unhandled
+    #   exceptions are bugs and should be surfaced loudly. Registering anything
+    #   at all takes that over:
+    #
+    #     screen.on_error do |e|
+    #       Tuile.logger.error("#{e.error.class}: #{e.error.message}")
+    #     end
     #
-    # The handler runs on the event-loop thread with the UI lock held.
-    # Returning normally keeps the loop alive; raising from within the handler
-    # tears the loop down and propagates out of {#run_event_loop}.
-    # @return [Proc] one-arg callable receiving the {StandardError} instance.
-    attr_accessor :on_error
+    #   A listener runs on the event-loop thread with the UI lock held.
+    #   Returning normally keeps the loop alive; raising tears the loop down and
+    #   propagates out of {#run_event_loop}.
+    #   @return [Listeners]
+    listener :on_error
 
     # @return [Screen] the singleton instance.
     def self.instance
@@ -185,7 +292,7 @@ module Tuile
       # pane to forward to, and NoMethodError-for-nil is a poor error.
       check_locked
       @pane.content = content
-      layout
+      resize
     end
 
     # @return [Size] current screen size.
@@ -197,6 +304,9 @@ module Tuile
     # dark). While the event loop runs, terminals supporting mode 2031
     # push OS appearance changes ({EventQueue::ColorSchemeEvent}) and the
     # screen re-picks from {#theme_def}.
+    #
+    # Always resolved ({Theme#resolve}): a derived token is recomputed from
+    # {#background_color} whenever that changes, so no token here is a Proc.
     # @return [Theme]
     attr_reader :theme
 
@@ -212,20 +322,21 @@ module Tuile
     # 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:
+    # near-neutral only sits right near the one it was tuned on. Declare such
+    # a color as a derived theme token (see {Theme}) and point a slot at it:
     #
-    #   bg = screen.background_color
-    #   sidebar.bg_color =
-    #     bg ? Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }) : FALLBACK_TINT
+    #   pane_bg: ->(bg) { bg ? Color.rgb(*bg.rgb.map { (_1 + 10).clamp(0, 255) }) : FALLBACK_TINT }
+    #   sidebar.bg_color = Theme.ref(:pane_bg)
     #
     # **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#handle_theme_changed} across the tree exactly as a theme swap
-    # does — a background-derived tint *is* a theme-derived color.
+    # updates when the reply lands. A changed color re-resolves {#theme} and
+    # then fires {Component#handle_theme_changed} across the tree once, as a
+    # theme swap does — even when no token is derived, since a component may
+    # read this directly.
     # @return [Color, nil]
     attr_reader :background_color
 
@@ -245,22 +356,22 @@ module Tuile
 
     # Replaces the theme and restyles the whole UI: fires
     # {Component#handle_theme_changed} across the attached tree and invalidates
-    # every attached component. No-op when `new_theme` equals the current theme.
+    # every attached component. No-op when `new_theme`, resolved, equals the
+    # current theme. A derived token keeps following {#background_color}.
     # This is a *transient* override — the next OS appearance flip re-picks from
     # {#theme_def}; assign {#theme_def=} for durable theming.
-    # @param new_theme [Theme]
+    # @param new_theme [Theme] resolved or not.
     # @return [void]
     def theme=(new_theme)
       raise TypeError, "expected Theme, got #{new_theme.inspect}" unless new_theme.is_a?(Theme)
 
       check_locked
-      return if @theme == new_theme
+      @theme_source = new_theme
+      resolved = new_theme.resolve(@background_color)
+      return if @theme == resolved
 
-      @theme = new_theme
-      # `__send__`, not `&:handle_theme_changed`: the hook is protected, and an app
-      # subclass may narrow it further (`D_hook_visibility`).
-      @pane&.walk_tree { _1.__send__(:handle_theme_changed) }
-      needs_full_repaint
+      @theme = resolved
+      restyle
     end
 
     # The formatting conventions this session renders and parses by — date
@@ -323,6 +434,10 @@ module Tuile
     #   screen.check_locked   # from a worker: raises; wrap the work in
     #                         # screen.event_queue.submit { ... } instead
     #
+    # Both halves of the test below are load-bearing — is a loop running
+    # *anywhere*, and is it mine: the loop need not run on the thread that
+    # created the screen, and the gem's own specs rely on that.
+    #
     # @raise [Tuile::Error] if {#state} is `:closed`, or the calling thread
     #   isn't the current owner.
     # @return [void]
@@ -360,6 +475,66 @@ module Tuile
       @invalidated << component unless @repainting.include? component
     end
 
+    # Marks a container as owing a {Component#relayout}, run by the next
+    # {#flush_layout}.
+    # @param component [Component]
+    # @return [void]
+    def invalidate_layout(component)
+      check_locked
+      raise TypeError, "expected Component, got #{component.inspect}" unless component.is_a? Component
+
+      @layout_pending = true
+    end
+
+    # Runs every pending {Component#relayout}, so rects are current again.
+    #
+    #   form.add(field)
+    #   screen.flush_layout
+    #   field.rect        # assigned, rather than whatever it had before
+    #
+    # The loop calls this after every event ({#dispatch}), which is enough for
+    # app code that mutates in one handler and reads in the next. Call it by
+    # hand only to read a rect in the *same* turn that dirtied it — that is what
+    # Swing's `validate()` and Tk's `update idletasks` are for.
+    #
+    # == Implementation details
+    #
+    # {LayoutPass.drain} over the pane, the same fixpoint a detached tree's
+    # {Component#flush_layout} runs. Then two follow-ups the pane's tree owes
+    # once it has settled: the pane places anchored popups before the content
+    # they hang from, so a moved anchor re-marks it and the drain runs again
+    # ({ScreenPane#remark_moved_anchors}); and the half of a {#focused=} that was
+    # deferred because it happened inside a pass — see there.
+    # @raise [Tuile::Error] when the tree has not settled after
+    #   {LayoutPass::MAX_ROUNDS} rounds — a relayout feeding its own input — or
+    #   when called from inside a {Component#relayout}, where the running pass
+    #   has not yet assigned the rects a nested drain would read.
+    # @return [void]
+    def flush_layout
+      check_locked
+      LayoutPass.refuse_nested
+      return if @pane.nil?
+
+      rounds = 0
+      loop do
+        if @layout_pending
+          rounds = LayoutPass.drain(@pane, rounds)
+          # Only once the drain returns: a raise leaves the gate open, so the
+          # next settle reports the same cycle rather than skipping the walk.
+          @layout_pending = false
+        end
+        # One round shared with the drain: an anchor chain that never settles
+        # hits the same cap.
+        next if @pane.__send__(:remark_moved_anchors)
+        break unless @focus_deferred
+
+        # Last, so the scroll sees popups at their final place; and looped, so
+        # what an on_focus_changed callback marks is settled before we return.
+        @focus_deferred = false
+        follow_up_focus(@focus_deferred_from)
+      end
+    end
+
     # @return [Component, nil] currently focused component.
     attr_reader :focused
 
@@ -371,10 +546,25 @@ module Tuile
     # 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#handle_blur} on what lost focus, {Component#handle_focus} on
-    # what took it, then {#on_focus_changed}. The outer two are edge-triggered
-    # and `handle_focus` is not — see there.
+    # Once the pointer and the active flags are settled, four steps run in
+    # order: {Component#handle_blur} on what lost focus, {Component#handle_focus}
+    # on what took it, that component's {Component#scroll_to_visible} so a
+    # scroller shows what Tab just reached, then {#on_focus_changed}, which
+    # therefore reads settled geometry. The outer two are edge-triggered and the
+    # middle two are not — see `handle_focus`.
+    #
+    # **Inside a {Component#relayout} the last two wait for the layout** — a
+    # focus repair from a child hidden there, a menu closed from
+    # {Component#handle_rect_changed}. The pass has not placed its children yet,
+    # and a scroll decided now is latched, so {#flush_layout} runs them once the
+    # tree has settled: the final target is scrolled into view, and
+    # {#on_focus_changed} fires once if focus ended somewhere other than where
+    # the pass found it.
+    #
+    # A target whose {#clip_for} is still empty after that request — a stale
+    # {Component::Scroller#content_rows}, say — logs a warning to
+    # {Tuile.logger} rather than raising: a terminal shrunk to nothing causes it
+    # legitimately.
     # @param focused [Component, nil] the new component to be focused.
     def focused=(focused)
       unless focused.nil? || focused.is_a?(Component)
@@ -382,13 +572,21 @@ module Tuile
       end
 
       check_locked
+      # For the scroll-into-view request, whose answer is *latched* into a
+      # scroller's scroll_top_row and so is not re-derived by any later pass.
+      # Nil scrolls nothing, and skipping it there keeps {#close}'s teardown
+      # from tripping over a layout that never settles; inside a pass the
+      # request waits for the drain instead (#fire_focus_hooks).
+      flush_layout unless focused.nil? || LayoutPass.running?
       previous = @focused
       if focused.nil?
         @focused = nil
         @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)
+        unless ComponentUtil.effectively_visible?(focused)
+          raise Tuile::Error, "#{focused} is hidden, or sits under a hidden ancestor"
+        end
 
         @focused = focused
         active = Set[focused]
@@ -411,7 +609,7 @@ module Tuile
     # status bar and reserves no row: build a {Component::Label} into your own
     # layout and fill it here (`D_status_bar`).
     #
-    #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
+    #   screen.on_focus_changed { bar.text = hint_for(screen.focused) }
     #
     # **Edge-triggered**, like {Component#handle_attached}: re-assigning the
     # component that already has focus fires nothing, so a callback can be as
@@ -420,22 +618,27 @@ module Tuile
     # 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 `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
+    # It runs *after* the active-flag cascade, `handle_focus` and
+    # {Component#scroll_to_visible}, 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#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
+    # @!method on_focus_changed
+    #   Fired with a {FocusChangedEvent} after {#focused} changes.
+    #   @return [Listeners]
+    listener :on_focus_changed
 
     # Internal — use {Component::Overlay#open} instead. Adds the overlay to
-    # {#pane}; a {Component::Popup} is additionally centered and focused.
+    # {#pane} at `placement`; a {Component::Popup} is additionally focused.
     # @api private
     # @param window [Component::Overlay] any overlay, modal or not.
+    # @param placement [Component::Overlay::Placement, nil] where it wants to
+    #   be; `nil` takes the overlay's default.
     # @return [void]
-    def add_popup(window)
+    def add_popup(window, placement = nil)
       check_locked
-      @pane.add_popup(window)
+      @pane.add_popup(window, placement)
       # No need to fully repaint the scene: a popup simply paints over the
       # current screen contents.
     end
@@ -614,8 +817,12 @@ module Tuile
     # redraws, so that test TTY is not painted over. {FakeScreen#initialize}
     # self-installs as the singleton, so subsequent {Screen.instance} calls
     # return the same object.
+    #
+    #   before { Screen.fake(width: 40, height: 12) }   # a narrow, short terminal
+    # @param width [Integer] the terminal's columns.
+    # @param height [Integer] the terminal's rows.
     # @return [FakeScreen]
-    def self.fake = FakeScreen.new
+    def self.fake(width: 160, height: 50) = FakeScreen.new(width: width, height: height)
 
     # Tears the screen down and vacates the singleton slot, moving {#state} to
     # the terminal `:closed`. Unmounts the tree first, so every component gets
@@ -692,9 +899,14 @@ module Tuile
     # of {#buffer}. Called once per event-loop tick (on {EventQueue::EmptyQueueEvent});
     # components should {Component#invalidate} and let the loop coalesce rather
     # than call this directly.
+    #
+    # Settles the layout first: painting is the heaviest reader of rects there
+    # is, and a pending {#flush_layout} would have it paint children where they
+    # no longer are.
     # @return [void]
     def repaint
       check_locked
+      flush_layout
       # 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
@@ -777,7 +989,7 @@ module Tuile
         @repainting = repaint.to_set
         @invalidated.clear
 
-        repaint.each(&:repaint)
+        repaint.each { _1.repaint(canvas_for(_1)) }
         @repainting.clear
       end
       return unless did_paint
@@ -787,12 +999,27 @@ module Tuile
       emit("#{Ansi::SYNC_BEGIN}#{@buffer.flush}#{cursor_sequence}#{Ansi::SYNC_END}")
     end
 
-    # Returns the absolute screen coordinates where the hardware cursor should
-    # sit, or nil if it should be hidden. Only the {#focused} component owns
-    # the cursor: there can be multiple active components (the focus path),
-    # but only one focused.
+    # Where the hardware cursor should sit in **screen** coordinates, or nil if
+    # it should be hidden. Only the {#focused} component owns the cursor: there
+    # can be multiple active components (the focus path), but only one focused.
+    #
+    # A component answers {Component#cursor_position} in its own coordinates and
+    # this converts — the same split as painting, so a caret is a column and a
+    # row and nothing more (`D_relative_rect`).
+    #
+    # A caret an ancestor clips away is **hidden**, not parked at a coordinate
+    # nobody can see: the cursor is the one thing on screen that no clip can
+    # reach, since the terminal draws it itself (`D_clip`).
     # @return [Point, nil]
-    def cursor_position = @focused&.cursor_position
+    def cursor_position
+      focused = @focused
+      local = focused&.cursor_position
+      return nil if local.nil?
+
+      return nil unless clip_for(focused).contains?(local)
+
+      focused.to_screen(local)
+    end
 
     # 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
@@ -818,22 +1045,48 @@ module Tuile
 
     private
 
-    # Whether `component` is out of the user's reach because it or an ancestor
-    # is {Component#visible? hidden}.
+    # Gives the pane the whole screen — the one rect no parent's pass assigns,
+    # so the screen places it itself.
+    # @return [void]
+    def size_pane
+      LayoutPass.run(self) { @pane.__send__(:rect=, Rect.new(0, 0, @size.width, @size.height)) }
+    end
+
+    # Whether anything on `component`'s ancestor chain actually cuts it — the
+    # test that lets {#clip_for} answer {Component#local_rect} outright.
+    #
+    # If every node sits inside the box its parent gave it, then by induction
+    # every ancestor's box contains `component`'s rect, the fold can remove
+    # nothing, and the answer is its own `local_rect` — which still bounds the
+    # component, so the short-circuit gives up no part of the guarantee.
     #
-    # 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#walk_shown_tree}).
+    # **Allocation-free on purpose, and that is the whole optimization.**
+    # `local_rect`, `moved_by` and `intersect` each build a `Rect`; comparing
+    # `node.rect` against the ancestor's stored *dimensions* builds nothing.
+    # Spelled the obvious way, `up.local_rect.contains_rect?(node.rect)`, it
+    # reads better and measures as no gain at all (`D_clip`).
     # @param component [Component]
+    # @param root [Component, nil] see {#clip_for}.
     # @return [Boolean]
-    def hidden?(component)
-      cursor = component
-      cursor = cursor.parent while cursor&.visible?
-      !cursor.nil?
+    def clipped?(component, root)
+      node = component
+      while !node.equal?(root) && (up = node.parent)
+        r = node.rect
+        # An empty rect covers no cells, so it is trivially inside — matching
+        # {Rect#contains_rect?}, whose place this takes.
+        unless r.empty? || (r.left >= 0 && r.top >= 0 &&
+                            r.left + r.width <= up.rect.width &&
+                            r.top + r.height <= up.rect.height)
+          return true
+        end
+
+        node = up
+      end
+      false
     end
 
-    # The tail of {#focused=}: blur, then focus, then the app notice.
+    # The tail of {#focused=}: blur, then focus, then the scroll-into-view
+    # request, 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
@@ -842,12 +1095,44 @@ module Tuile
     # @param focused [Component, nil] what the assignment asked for.
     # @return [void]
     def fire_focus_hooks(previous, focused)
+      deferred = LayoutPass.running?
+      # Recorded before the hooks, which may reassign focus themselves: the
+      # first deferral in a drain keeps its `previous`, so the one notice fired
+      # later compares against where focus stood before any of them.
+      if deferred && !@focus_deferred
+        @focus_deferred = true
+        @focus_deferred_from = previous
+      end
       unless focused.equal?(previous)
         previous&.__send__(:handle_blur)
         return unless @focused.equal?(focused)
       end
       @focused&.__send__(:handle_focus)
-      @on_focus_changed&.call unless @focused.equal?(previous)
+      follow_up_focus(previous) unless deferred
+    end
+
+    # The geometry half of {#focused=}: scroll the target into view, warn if it
+    # still shows nothing, then fire the notice.
+    # @param previous [Component, nil] what was focused before the change.
+    # @return [void]
+    def follow_up_focus(previous)
+      # Level-triggered like `handle_focus`, not edge-triggered like the notice
+      # below: re-focusing what already has focus is how an app says "bring it
+      # back into view", and an already-satisfied request scrolls by zero.
+      @focused&.scroll_to_visible
+      warn_if_unseen(@focused) unless @focused.nil?
+      on_focus_changed.fire(FocusChangedEvent.new(source: self)) unless @focused.equal?(previous)
+    end
+
+    # Unguarded on purpose: a container forwarding focus re-enters {#focused=},
+    # so a target may be reported twice.
+    # @param component [Component]
+    # @return [void]
+    def warn_if_unseen(component)
+      return unless clip_for(component).empty?
+
+      Tuile.logger.warn("Screen: focused #{component} shows nothing, even after scroll_to_visible " \
+                        "(a stale Scroller#content_rows? Fixed[0] meant as visible = false?)")
     end
 
     # The startup background probe, seeding {#theme} and
@@ -892,17 +1177,28 @@ module Tuile
       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.
+    # The re-probe answered: adopt the color, re-derive the theme from it 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 handle_background_color(color)
       return if @background_color == color
 
       @background_color = color
+      @theme = @theme_source.resolve(color)
+      restyle
+    end
+
+    # Fires {Component#handle_theme_changed} across the attached tree and
+    # repaints everything, after {#theme} or {#background_color} changed.
+    # @return [void]
+    def restyle
+      # `__send__`, not `&:handle_theme_changed`: the hook is protected, and an app
+      # subclass may narrow it further (`D_hook_visibility`).
       @pane&.walk_tree { _1.__send__(:handle_theme_changed) }
       needs_full_repaint
     end
@@ -916,7 +1212,7 @@ module Tuile
     # @return [Boolean] true if focus moved.
     def cycle_focus(forward:)
       check_locked
-      scope = @pane.modal_popup || @pane.content
+      scope = @pane.key_scope
       return false if scope.nil?
 
       stops = []
@@ -956,13 +1252,14 @@ module Tuile
     # Resizes {#buffer} and {#pane} to the current {#size}, invalidates the
     # whole tree and repaints. Run whenever the terminal size changes (the
     # {EventQueue::TTYSizeEvent} path) and once at startup via the first
-    # {#content=}.
+    # {#content=}. Not layout in the {Component#relayout} sense: assigning the
+    # pane a rect only *marks* it, and the {#repaint} below settles the pass.
     # @return [void]
-    def layout
+    def resize
       check_locked
       @buffer.resize(size) unless @buffer.size == size
       needs_full_repaint
-      @pane.rect = Rect.new(0, 0, size.width, size.height)
+      size_pane
       repaint
     end
 
@@ -1016,21 +1313,36 @@ module Tuile
     # @return [void]
     def handle_paste(text) = @pane.handle_paste(text)
 
-    # @return [void]
-    def event_loop
-      @event_queue.run_loop do |event|
+    # Routes one event to its handler, then {#settle}s.
+    #
+    # The single seam every event passes through, which is why {FakeScreen}'s
+    # gesture helpers drive it rather than calling {#handle_mouse} themselves: a
+    # spec's `click` then reaches components exactly as the loop's own report
+    # does, settle included.
+    #
+    # The `rescue` stays in {#event_loop}: only a *loop* has an `on_error` slot
+    # to divert into, and a spec driving one event wants the raise.
+    # @param event [Object] a {EventQueue::KeyEvent}, {Mouse::Event},
+    #   {EventQueue::PasteEvent}, {EventQueue::TTYSizeEvent},
+    #   {EventQueue::ColorSchemeEvent}, {EventQueue::BackgroundColorEvent},
+    #   {EventQueue::EmptyQueueEvent}, or a `Proc` from {EventQueue#submit}.
+    # @return [Object] what the handler returned — a paste's is the Boolean
+    #   {ScreenPane#handle_paste} answers with; most are unspecified.
+    def dispatch(event)
+      result =
         case event
         when EventQueue::KeyEvent
           key = event.key
           handled = handle_key?(key)
           @event_queue.stop if !handled && ["q", Keys::ESC].include?(key)
+          handled
         when EventQueue::PasteEvent
           handle_paste(event.text)
         when Mouse::Event
           handle_mouse(event)
         when EventQueue::TTYSizeEvent
           @size = event.size
-          layout
+          resize
         when EventQueue::ColorSchemeEvent
           handle_color_scheme(event.scheme)
         when EventQueue::BackgroundColorEvent
@@ -1040,8 +1352,31 @@ module Tuile
         when Proc
           event.call
         end
+      settle
+      result
+    end
+
+    # Brings deferred work up to date, once per {#dispatch}ed event.
+    #
+    # The sequence point between "a handler mutated the tree" and "the next
+    # event reads it": whatever a handler *marks*, this is where it is *done*,
+    # so a queued mouse press never routes against what the key before it left
+    # half-finished.
+    # @return [void]
+    def settle
+      flush_layout
+    end
+
+    # @return [void]
+    def event_loop
+      @event_queue.run_loop do |event|
+        dispatch(event)
       rescue StandardError => e
-        @on_error.call(e)
+        # Empty means re-raise: the generic fire cannot know that, so the one
+        # slot with an executable empty branch carries it here.
+        raise e if on_error.empty?
+
+        on_error.fire(EventQueue::ErrorEvent.new(error: e))
       end
     end
   end