tuile 0.9.0 → 0.10.0

data/lib/tuile/screen.rb

@@ -1,25 +1,54 @@
 # frozen_string_literal: true
 
 module Tuile
-  # The TTY screen. There is exactly one screen per app.
+  # The process-singleton runtime: one {Screen} per app, reached through
+  # {Screen.instance}. It owns everything the UI needs to exist — the
+  # {#event_queue}, the UI lock, the invalidation set, the terminal IO, the
+  # back {#buffer}, the {#theme}/{#theme_def}, the {#focused} component, the
+  # global-shortcut registry, and the single {ScreenPane} under which *all*
+  # UI lives. Construct one with {Screen.new} (or {Screen.fake} in tests),
+  # tear it down with {Screen.close}.
   #
-  # A screen runs the event loop; call {#run_event_loop} to do that.
+  # ## The component tree
   #
-  # A screen holds the screen lock; any UI modifications must be called from
-  # the event queue.
+  # Everything on screen hangs off {#pane} (a {ScreenPane}): the tiled
+  # {#content} (set via {#content=}, filling the whole terminal and laying
+  # out its own children), the modal/overlay {#popups} stack (opened via
+  # {Component::Popup#open}, drawn on top of the content), and the bottom
+  # status bar. Popups are *not* sized from their content — each carries its
+  # own top-down {Component::Popup#size} — and they deliberately overdraw the
+  # content without clipping.
   #
-  # All UI lives under a single {ScreenPane} owned by the screen. Set tiled
-  # content via {#content=}; the pane fills the entire terminal and is
-  # responsible for laying out its children.
+  # ## Repaint model
   #
-  # Modal popups are supported too, via {Component::Popup#open}. They
-  # auto-size to their wrapped content and are drawn centered over the
-  # tiled content.
+  # Components never draw to the terminal directly. They call
+  # {Component#invalidate} to mark themselves dirty, and when they do paint
+  # they write styled cells into {#buffer}. Once the event loop drains its
+  # queue, {#repaint} walks the invalidated set in z-order, has each
+  # component paint into the buffer, then flushes the buffer's *minimal diff*
+  # (only cells that changed) to the terminal in one synchronized-output
+  # batch — which is what keeps repaint flicker-free and coalesces many
+  # invalidations into a single frame per tick. See the book (ch. 2) for the
+  # why.
   #
-  # The drawing procedure is very simple: when a window needs repaint, it
-  # invalidates itself, but won't draw immediately. After the keyboard press
-  # event processing is done in the event loop, {#repaint} is called which
-  # then repaints all invalidated windows. This prevents repeated paintings.
+  # ## Thread-safety
+  #
+  # **UI-thread-confined**, where "the UI thread" changes hands once: it is the
+  # loop's thread while {#run_event_loop} is in progress, and the thread that
+  # *created* the screen whenever no loop is running ({#state} `:idle`). So an
+  # app builds its tree on its own thread, hands ownership to the loop, and
+  # gets it back for teardown — the loop needn't run on the creating thread.
+  # *All* UI mutations — {#content=}, {#focused=}, {#theme=},
+  # {Component#invalidate}, `rect=`, … — obey it via {#check_locked}.
+  #
+  # A worker marshals back with `screen.event_queue.submit { … }`, which runs
+  # the block only while a loop is draining the queue — outside `:running` it
+  # silently never fires. Terminal resize, key/mouse input and OS color-scheme
+  # flips arrive as events on that same queue.
+  #
+  # The singleton slot survives subclassing (`FakeScreen < Screen`), so
+  # {FakeScreen} — which captures output in memory — is what
+  # {Screen.instance} returns under test.
   class Screen
     # Class variable (not class instance var) so the singleton survives
     # subclassing — `FakeScreen < Screen` and `Screen.instance` see the same slot.
@@ -33,8 +62,10 @@ module Tuile
       # Components being repainted right now. A component may invalidate its
       # children during its repaint phase; this prevents double-draw.
       @repainting = Set.new
-      # Until the event loop is run, we pretend we're in the UI thread.
-      @pretend_ui_lock = true
+      # The thread that owns the UI whenever no event loop is running — i.e.
+      # during :idle, at both ends of the screen's life. See {#check_locked}.
+      @ui_thread = Thread.current
+      @closed = false
       @color_scheme = detect_scheme
       @theme_def = ThemeDef.default
       @theme = @theme_def.for(@color_scheme)
@@ -57,6 +88,25 @@ module Tuile
     Shortcut = Data.define(:block, :over_popups, :hint)
     private_constant :Shortcut
 
+    # Keys {#register_global_shortcut} refuses because every editable widget
+    # needs them: the registry sits *above* the component tree, so binding one
+    # app-wide would silently break text entry everywhere — a
+    # {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}.
+    #
+    # Deliberately *not* reserved: `HOME`/`END`/`PAGE_UP`/`PAGE_DOWN`. They
+    # move within a widget rather than mutate its value, and binding them
+    # app-wide (scroll the log pane) is a real use case.
+    # @return [Array<String>]
+    EDITING_KEYS = [
+      Keys::ENTER, Keys::DELETE, *Keys::BACKSPACES,
+      Keys::UP_ARROW, Keys::DOWN_ARROW, Keys::LEFT_ARROW, Keys::RIGHT_ARROW,
+      Keys::CTRL_LEFT_ARROW, Keys::CTRL_RIGHT_ARROW
+    ].freeze
+
     # @return [ScreenPane] the structural root of the component tree.
     attr_reader :pane
 
@@ -100,6 +150,9 @@ module Tuile
     # @param content [Component]
     # @return [void]
     def content=(content)
+      # Not left to ScreenPane#content='s own checks: after #close there's no
+      # pane to forward to, and NoMethodError-for-nil is a poor error.
+      check_locked
       @pane.content = content
       layout
     end
@@ -140,19 +193,12 @@ module Tuile
     end
 
     # Replaces the theme and restyles the whole UI: fires
-    # {Component#on_theme_changed} across the attached tree (so the app can
-    # rebuild styled content whose colors were derived from the old theme),
-    # refreshes the status bar and invalidates every attached component so
-    # the next repaint uses the new colors. No-op when `new_theme` equals
-    # the current theme.
-    #
-    # This is a transient override: the next OS appearance flip re-picks
-    # from {#theme_def} and replaces it. To theme an app durably, assign
-    # {#theme_def=} instead.
-    #
-    # Note status-bar hints supplied by the host as preformatted strings
-    # (see {#register_global_shortcut}) have their colors baked in and are
-    # not restyled by this.
+    # {Component#on_theme_changed} across the attached tree, refreshes the
+    # status bar, 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. Preformatted status-bar hints (see
+    # {#register_global_shortcut}) have their colors baked in and aren't restyled.
     # @param new_theme [Theme]
     # @return [void]
     def theme=(new_theme)
@@ -174,15 +220,41 @@ module Tuile
     # @return [EventQueue] the event queue.
     attr_reader :event_queue
 
-    # Checks that the UI lock is held and the current code runs in the "UI
-    # thread".
+    # `:idle` covers *both* ends of the screen's life — before the first
+    # {#run_event_loop} and after it returns — and a screen may cycle
+    # `:idle` → `:running` → `:idle` repeatedly. `:closed` is terminal.
+    # @return [Symbol] `:idle` (no event loop running), `:running` (a
+    #   {#run_event_loop} is in progress) or `:closed` (after {#close}).
+    def state
+      return :closed if @closed
+
+      @event_queue.running? ? :running : :idle
+    end
+
+    # Raises unless the calling thread currently owns the UI (see the
+    # class-level threading contract).
+    #
+    #   screen.check_locked   # from a worker: raises; wrap the work in
+    #                         # screen.event_queue.submit { ... } instead
+    #
+    # @raise [Tuile::Error] if {#state} is `:closed`, or the calling thread
+    #   isn't the current owner.
     # @return [void]
     def check_locked
-      return if @pretend_ui_lock || @event_queue.locked?
-
-      raise Tuile::Error,
-            "UI lock not held: UI mutations must run on the event-loop thread; " \
-            "marshal via screen.event_queue.submit { ... }"
+      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)
+
+      # `submit` is the wrong remedy with no loop running — nothing would drain
+      # the queue, so the block silently never fires.
+      message = if @event_queue.running?
+                  "UI lock not held: UI mutations must run on the event-loop thread; " \
+                  "marshal via screen.event_queue.submit { ... }"
+                else
+                  "UI not owned by #{Thread.current}: no event loop is running, so UI mutations must " \
+                  "come from #{@ui_thread}, the thread that created this screen " \
+                  "(or start the event loop first)"
+                end
+      raise Tuile::Error, message
     end
 
     # Clears the TTY screen.
@@ -283,8 +355,13 @@ module Tuile
       # current screen contents.
     end
 
-    # Runs event loop – waits for keys and sends them to active window. The
-    # function exits when the 'ESC' or 'q' key is pressed.
+    # Runs the event loop on the calling thread, taking over stdin (raw mode,
+    # 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
@@ -293,23 +370,30 @@ module Tuile
     #   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).
+    # @raise [Tuile::Error] if the screen is already {#close}d.
     # @return [void]
     def run_event_loop(capture_mouse: true)
-      @pretend_ui_lock = false
-      $stdin.echo = false
-      print MouseEvent.start_tracking if capture_mouse
-      # Follow OS light/dark flips live: terminals supporting mode 2031
-      # push color-scheme reports that the key thread turns into
-      # {EventQueue::ColorSchemeEvent}s.
-      print TerminalBackground::NOTIFY_ON
-      $stdin.raw do
-        event_loop
+      raise Tuile::Error, "Screen is closed: cannot run the event loop" if @closed
+
+      # 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
+        # Follow OS light/dark flips live: terminals supporting mode 2031
+        # push color-scheme reports that the key thread turns into
+        # {EventQueue::ColorSchemeEvent}s.
+        print TerminalBackground::NOTIFY_ON
+        $stdin.raw do
+          event_loop
+        end
+      ensure
+        print TerminalBackground::NOTIFY_OFF
+        print MouseEvent.stop_tracking if capture_mouse
+        print TTY::Cursor.show
+        $stdin.echo = true
       end
-    ensure
-      print TerminalBackground::NOTIFY_OFF
-      print MouseEvent.stop_tracking if capture_mouse
-      print TTY::Cursor.show
-      $stdin.echo = true
     end
 
     # Advances focus to the next {Component#tab_stop?} in tree order, wrapping
@@ -323,31 +407,23 @@ module Tuile
     # @return [Boolean] true if focus moved.
     def focus_previous = cycle_focus(forward: false)
 
-    # Registers an app-level keyboard shortcut. When `key` arrives, the block
-    # is invoked on the event-loop thread (so it may freely mutate UI) before
-    # the key reaches any component. Re-registering the same key replaces the
-    # previous binding; use {#unregister_global_shortcut} to remove one.
-    #
-    # Only unprintable keys are accepted — control characters (Ctrl+letter,
-    # ESC, BACKSPACE, ENTER, …) and multi-character escape sequences (arrows,
-    # F-keys, …). Printable keys raise {ArgumentError}: they'd hijack typing
-    # into a {Component::TextField} and should be expressed as
-    # {Component#key_shortcut} instead, which the dispatcher suppresses while
-    # a text widget owns the hardware cursor. TAB and SHIFT_TAB are also
-    # rejected because {#handle_key} intercepts them for focus navigation
-    # before the global registry is consulted, so a binding on them would
-    # silently never fire.
+    # Registers an app-level keyboard shortcut: when `key` arrives, the block
+    # runs on the event-loop thread (free to mutate UI) before the key reaches
+    # any component. Re-registering a key replaces its binding.
     #
-    # Pass `hint:` to surface the shortcut in the status bar. It's a
-    # preformatted string the caller fully owns (so colors and the key label
-    # style stay consistent with whatever the host app uses elsewhere). The
-    # framework splices it in like any other status hint: in the tiled case,
-    # right after `q quit` and before the active window's own hint; while a
-    # popup is open, only hints from `over_popups: true` shortcuts are
-    # shown, and they're prepended before the popup's `q Close`.
+    # This registry is the *only* keyboard mechanism above the component tree,
+    # and nothing suppresses it — so it accepts only keys no widget can need.
+    # Three groups raise at registration rather than misbehaving at runtime:
     #
-    # Example — open a log popup with Ctrl+L from anywhere, even while a
-    # popup is already on screen:
+    # - **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
+    #   navigation before the registry is consulted, so a binding would never
+    #   fire.
+    # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
+    #   which every editable widget needs.
     #
     #   screen.register_global_shortcut(Keys::CTRL_L,
     #                                   over_popups: true,
@@ -355,16 +431,12 @@ module Tuile
     #     log_popup.open
     #   end
     #
-    # @param key [String] unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC},
-    #   {Keys::PAGE_UP}).
-    # @param over_popups [Boolean] when true, fires even while a modal popup
-    #   is open (pre-empting the popup's own key handling). When false
-    #   (default), the shortcut is suppressed while any popup is open and
-    #   the popup gets the key instead.
-    # @param hint [String, nil] preformatted status-bar hint (e.g.
-    #   `"^L #{screen.theme.hint("log")}"`). When nil (default) the shortcut
-    #   is silent in the status bar. The colors are baked into the string,
-    #   so a later {#theme=} does not restyle it — re-register if needed.
+    # @param key [String] unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC}).
+    # @param over_popups [Boolean] when true, fires even while a modal popup is
+    #   open (pre-empting the popup); when false (default), suppressed while any
+    #   popup is open so the popup gets the key.
+    # @param hint [String, nil] preformatted status-bar hint; nil (default) is
+    #   silent. Colors are baked in — re-register after a {#theme=} to recolor.
     # @yield invoked with no arguments when `key` is pressed.
     # @return [void]
     def register_global_shortcut(key, over_popups: false, hint: nil, &block)
@@ -374,13 +446,21 @@ module Tuile
       if Keys.printable?(key)
         raise ArgumentError,
               "global shortcut key must be unprintable; got #{key.inspect}. " \
-              "Use Component#key_shortcut for printable keys (it's suppressed " \
-              "while a text widget owns the cursor, so it won't hijack typing)."
+              "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
       if [Keys::TAB, Keys::SHIFT_TAB].include?(key)
         raise ArgumentError,
               "#{key == Keys::TAB ? "TAB" : "SHIFT_TAB"} is reserved for focus navigation"
       end
+      if EDITING_KEYS.include?(key)
+        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 " \
+              "TextArea/TextField gets first refusal there."
+      end
       raise ArgumentError, "hint must be a String or nil, got #{hint.inspect}" unless hint.nil? || hint.is_a?(String)
 
       @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups, hint: hint)
@@ -448,11 +528,31 @@ module Tuile
     # @return [FakeScreen]
     def self.fake = FakeScreen.new
 
+    # 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.
+    # @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
+    #   doesn't own the UI.
     # @return [void]
     def close
-      clear
-      @pane = nil
-      @@instance = nil # rubocop:disable Style/ClassVars
+      return if @closed
+
+      raise Tuile::Error, "Screen is running: stop the event loop before closing" if state == :running
+
+      check_locked
+      begin
+        @pane.detach_all
+      ensure
+        # A raising on_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
+        @closed = true
+        @@instance = nil # rubocop:disable Style/ClassVars
+      end
     end
 
     # @return [void]
@@ -473,7 +573,10 @@ module Tuile
     end
 
     # Repaints the screen; tries to be as effective as possible, by only
-    # considering invalidated windows.
+    # considering invalidated components and flushing just the changed cells
+    # 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.
     # @return [void]
     def repaint
       check_locked
@@ -528,11 +631,7 @@ module Tuile
         @repainting = repaint.to_set
         @invalidated.clear
 
-        # Components write into @buffer; overdraw is free and correct here
-        # because the buffer only diffs net-visible changes to the terminal.
         repaint.each(&:repaint)
-
-        # Repaint done, mark all components as up-to-date.
         @repainting.clear
       end
       return unless did_paint
@@ -618,9 +717,10 @@ module Tuile
       $stdout.flush
     end
 
-    # Recalculates positions of all windows, and repaints the scene.
-    # Automatically called whenever terminal size changes. Call when the app
-    # starts. {#size} provides correct size of the terminal.
+    # 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=}.
     # @return [void]
     def layout
       check_locked
@@ -635,17 +735,15 @@ module Tuile
     #
     # Dispatch order:
     #   1. Tab / Shift+Tab — reserved focus navigation, intercepted before
-    #      anything else so a focused {Component::TextField} (which would
-    #      otherwise swallow printable keys via cursor-owner suppression)
-    #      doesn't trap them.
+    #      anything else so a focused {Component::TextField} (which swallows
+    #      printable keys) can't trap them.
     #   2. App-level shortcuts from {#register_global_shortcut}. An entry
     #      registered with `over_popups: true` always fires; one with the
     #      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}, which captures a matching {#key_shortcut}
-    #      in the active scope, then delivers the key to {#focused} and bubbles
-    #      it up the focus chain.
+    #   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)

data/lib/tuile/screen_pane.rb

@@ -23,7 +23,9 @@ module Tuile
       # cascaded to the first focusable child.
       @popup_prior_focus = {}
       @status_bar = Component::Label.new
-      @status_bar.parent = self
+      # Added first and never removed, so it is always the last child — which is
+      # the anchor `add_popup` inserts against.
+      add_child(@status_bar)
     end
 
     # @return [Component, nil] the tiled content component.
@@ -37,10 +39,6 @@ module Tuile
 
     def focusable? = false
 
-    # Children for tree traversal: content first, popups in stacking order,
-    # status bar last.
-    def children = [*[@content].compact, *@popups, @status_bar]
-
     # Replaces the tiled content. Wipes focus first (the new tree starts
     # fresh), detaches the old content, then attaches the new one and
     # re-lays out.
@@ -51,10 +49,9 @@ module Tuile
       return if @content == content
 
       screen.focused = nil
-      old = @content
-      old&.parent = nil
+      remove_child(@content) unless @content.nil?
       @content = content
-      content.parent = self
+      add_child(content, at: 0) # the tiled layer paints beneath everything else
       layout
     end
 
@@ -63,6 +60,12 @@ module Tuile
     # 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.
+    #
+    # The *whole subtree* is invalidated, not just the popup 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]
     # @return [void]
     def add_popup(window)
@@ -71,12 +74,12 @@ module Tuile
 
       @popup_prior_focus[window] = screen.focused
       @popups << window
-      window.parent = self
+      add_child(window, at: @children.index(@status_bar))
       if window.modal?
         window.center
         screen.focused = window
       end
-      screen.invalidate(window)
+      window.on_tree { |c| screen.invalidate(c) }
     end
 
     # Removes a popup. If the popup held focus, focus shifts to the now-topmost
@@ -88,21 +91,35 @@ module Tuile
       raise Tuile::Error, "#{window} is not an open popup on this pane" unless @popups.delete(window)
 
       prior = @popup_prior_focus.delete(window)
-      # Detach first so the popup becomes its own root; then any prior
-      # pointing *inside* that popup is detectable via `p.root == window`.
-      window.parent = nil
-      # If any other popup recorded its prior focus inside the popup we're
-      # removing, forward it to *our* prior so chained closures still climb
-      # back to the original owner instead of stopping at a detached
-      # component.
-      @popup_prior_focus.transform_values! { |p| p && p.root == window ? prior : p }
-
       @removing_popup_prior = prior
-      on_child_removed(window)
+      remove_child(window)
+      # Runs after the detach, so a prior pointing *inside* the removed popup is
+      # detectable via `p.root == window`: forward it to *our* prior, so chained
+      # closures climb back to the original owner instead of stopping at a
+      # detached component.
+      @popup_prior_focus.transform_values! { |p| p && p.root == window ? prior : p }
     ensure
       @removing_popup_prior = nil
     end
 
+    # Unmounts everything: each child is detached — firing {Component#on_detached}
+    # down its subtree — and every slot is emptied. Terminal; the pane isn't
+    # reusable afterwards, and {Screen#close} is its only caller.
+    #
+    # Deliberately not named `close` ({Component::Popup#close} already means
+    # "remove *me* from the pane"), and deliberately not a generic
+    # `Component#remove_all_children`: a slot container calling that would empty
+    # `@children` while `#content` / `#footer` still pointed at detached
+    # 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
+      children.dup.each { detach_child(_1) }
+      @content = nil
+      @popups.clear
+      @popup_prior_focus.clear
+    end
+
     # @param window [Component]
     # @return [Boolean] true if this pane currently hosts the popup.
     def has_popup?(window) = @popups.include?(window) # rubocop:disable Naming/PredicatePrefix
@@ -140,34 +157,27 @@ module Tuile
     # @return [void]
     def repaint; end
 
-    # Dispatches a key in two phases, both scoped to the topmost *modal* popup
-    # (when one is open) or else the tiled {#content}. Non-modal overlays are
-    # never the scope: focus stays in the content beneath them, and the overlay
-    # is driven by app code (which forwards keys to it explicitly), so it
-    # doesn't appear in this path at all.
+    # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
+    # 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
+    # scope receives nothing, which is what keeps an open modal popup modal.
+    # Non-modal overlays are never the scope: focus stays in the content
+    # beneath them, and the overlay is driven by app code (which forwards keys
+    # to it explicitly), so it doesn't appear in this path at all.
     #
-    # 1. *Capture* — a {Component#key_shortcut} match anywhere in the scope
-    #    focuses that component and consumes the key. Suppressed while a
-    #    cursor-owner ({Screen#cursor_position}) is mid-edit, so typing into a
-    #    {Component::TextField} isn't hijacked by a sibling's shortcut.
-    # 2. *Delivery* — the key is handed to {Screen#focused} and bubbles up its
-    #    ancestor chain to the scope root; the first component to return true
-    #    wins. Focus that is nil or sits outside the scope receives nothing,
-    #    which is what keeps an open modal popup modal.
+    # Because an ancestor sees a key only after every descendant on the chain
+    # declined it, the scope root is the natural home for scope-wide fallbacks
+    # — a form's default button, or a layout's one-key jumps to its panes (a
+    # focused {Component::TextField} consumes the key first, so typing is never
+    # hijacked).
     # @param key [String]
     # @return [Boolean] true if the key was handled.
     def handle_key(key)
       scope = modal_popup || @content
       return false if scope.nil?
 
-      if screen.cursor_position.nil?
-        target = scope.find_shortcut_component(key)
-        unless target.nil?
-          screen.focused = target
-          return true
-        end
-      end
-
       bubble_key(key, scope)
     end