tuile 0.12.0 → 0.14.0

data/lib/tuile/screen.rb

@@ -14,10 +14,15 @@ module Tuile
   # 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.
+  # {Component::Popup#open}, drawn on top of the content). Popups are *not*
+  # sized from their content — each carries its own top-down
+  # {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`).
   #
   # ## Repaint model
   #
@@ -66,11 +71,14 @@ 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
       @theme_def = ThemeDef.default
       @theme = @theme_def.for(@color_scheme)
-      # Structural root of the component tree: holds tiled content, popup
-      # stack and status bar.
+      # Structural root of the component tree: holds tiled content and the
+      # popup stack.
       @pane = ScreenPane.new
       @on_error = ->(e) { raise e }
       # App-level keyboard shortcuts dispatched by {#handle_key} before keys
@@ -79,13 +87,13 @@ 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, whether it
-    # pre-empts open popups, and an optional preformatted status-bar hint.
+    # Entry in the global shortcut registry: the block to run, and whether it
+    # pre-empts open popups.
     # @api private
-    Shortcut = Data.define(:block, :over_popups, :hint)
+    Shortcut = Data.define(:block, :over_popups)
     private_constant :Shortcut
 
     # Keys {#register_global_shortcut} refuses because every editable widget
@@ -113,6 +121,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
@@ -178,6 +197,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
@@ -193,12 +232,10 @@ module Tuile
     end
 
     # Replaces the theme and restyles the whole UI: fires
-    # {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.
+    # {Component#on_theme_changed} across the attached tree and invalidates
+    # every attached component. No-op when `new_theme` equals the current theme.
+    # This is a *transient* override — the next OS appearance flip re-picks from
+    # {#theme_def}; assign {#theme_def=} for durable theming.
     # @param new_theme [Theme]
     # @return [void]
     def theme=(new_theme)
@@ -208,13 +245,15 @@ module Tuile
       return if @theme == new_theme
 
       @theme = new_theme
-      @pane&.on_tree(&:on_theme_changed)
-      refresh_status_bar
+      # `__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
 
-    # @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.
@@ -287,6 +326,7 @@ module Tuile
       end
 
       check_locked
+      previous = @focused
       if focused.nil?
         @focused = nil
         @pane.on_tree { _1.active = false }
@@ -303,50 +343,39 @@ module Tuile
         @pane.on_tree { _1.active = active.include?(_1) }
         @focused.on_focus
       end
-      refresh_status_bar
-    end
-
-    # Rebuild the status-bar text from the current focus and global-shortcut
-    # registry. Called from {#focused=} and whenever the global registry
-    # changes. Popups own their own "q Close" prefix in `#keyboard_hint`;
-    # for the tiled case Screen tacks on the global "q quit" instead.
-    # Global-shortcut hints get spliced in too — see {#global_shortcut_hints}
-    # for the over_popups filter rule.
-    # @api private
-    # @return [void]
-    def refresh_status_bar
-      top_popup = @pane.modal_popup
-      globals = global_shortcut_hints(popup_open: !top_popup.nil?)
-      @pane.status_bar.text = if top_popup.nil?
-                                ["q #{@theme.hint("quit")}", *globals,
-                                 active_window&.keyboard_hint].compact.reject(&:empty?).join("  ")
-                              else
-                                [*globals, top_popup.keyboard_hint].reject(&:empty?).join("  ")
-                              end
-    end
-    private :refresh_status_bar
-
-    # Status-bar hints from currently-registered global shortcuts.
-    # When a popup is open, only `over_popups: true` shortcuts contribute —
-    # the rest don't fire in that context, so showing them would be a lie.
-    # Insertion order is preserved (Hash iteration order).
-    # @api private
-    # @param popup_open [Boolean]
-    # @return [Array<String>]
-    def global_shortcut_hints(popup_open:)
-      @global_shortcuts.each_value.filter_map do |s|
-        next if s.hint.nil? || s.hint.empty?
-        next if popup_open && !s.over_popups
-
-        s.hint
-      end
+      @on_focus_changed&.call unless @focused.equal?(previous)
     end
-    private :global_shortcut_hints
 
-    # Internal — use {Component::Popup#open} instead. Adds the popup to
-    # {#pane}, centers and focuses it.
+    # Called after the focused component *changes* — including to and from
+    # `nil`, and including the focus repair that runs when a popup closes.
+    # Takes no arguments; read {#focused} (and walk its `parent` chain) for the
+    # new state.
+    #
+    # 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`).
+    #
+    #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
+    #
+    # **Edge-triggered**, like {Component#on_attached}: re-assigning the
+    # component that already has focus fires nothing, so a callback can be as
+    # expensive as rebuilding a hint string without a `did it really change?`
+    # guard of its own. That matters more than it looks — `ScreenPane#content=`
+    # clears focus on every content swap, which on a level-triggered hook would
+    # fire a nil→nil notification during assembly.
+    #
+    # It runs *after* the active-flag cascade and `on_focus`, so the tree is
+    # settled. Two things a callback must tolerate: {#focused} being `nil`, and
+    # firing during {#close} — teardown clears focus, exactly as it fires
+    # {Component#on_detached}. A raising callback propagates out of {#focused=}
+    # and leaves focus assigned; keep it trivial, as with the attach hooks.
+    # @return [Proc, nil]
+    attr_accessor :on_focus_changed
+
+    # 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
@@ -370,9 +399,16 @@ 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).
+    # @param bracketed_paste [Boolean] when true (default), enables DEC private
+    #   mode 2004 so pasted text arrives whole, as {Component#handle_paste},
+    #   instead of as one keystroke per character — which is the only way a
+    #   pasted line break can be told from a typed Enter. When false, a paste
+    #   streams in as keys again and a component that gives ENTER a meaning
+    #   fires it once per pasted line. Turn it off only for a terminal that
+    #   mishandles the mode.
     # @raise [Tuile::Error] if the screen is already {#close}d.
     # @return [void]
-    def run_event_loop(capture_mouse: true)
+    def run_event_loop(capture_mouse: true, bracketed_paste: true)
       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
@@ -381,6 +417,7 @@ module Tuile
       begin
         $stdin.echo = false
         print MouseEvent.start_tracking if capture_mouse
+        print Keys::BRACKETED_PASTE_ON if bracketed_paste
         # Follow OS light/dark flips live: terminals supporting mode 2031
         # push color-scheme reports that the key thread turns into
         # {EventQueue::ColorSchemeEvent}s.
@@ -390,6 +427,7 @@ module Tuile
         end
       ensure
         print TerminalBackground::NOTIFY_OFF
+        print Keys::BRACKETED_PASTE_OFF if bracketed_paste
         print MouseEvent.stop_tracking if capture_mouse
         print TTY::Cursor.show
         $stdin.echo = true
@@ -425,9 +463,7 @@ module Tuile
     # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
     #   which every editable widget needs.
     #
-    #   screen.register_global_shortcut(Keys::CTRL_L,
-    #                                   over_popups: true,
-    #                                   hint: "^L #{screen.theme.hint("log")}") do
+    #   screen.register_global_shortcut(Keys::CTRL_L, over_popups: true) do
     #     log_popup.open
     #   end
     #
@@ -435,11 +471,9 @@ module Tuile
     # @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)
+    def register_global_shortcut(key, over_popups: false, &block)
       raise ArgumentError, "block required" if block.nil?
       raise ArgumentError, "key must be a String, got #{key.inspect}" unless key.is_a?(String)
       raise ArgumentError, "key cannot be empty" if key.empty?
@@ -461,10 +495,7 @@ module Tuile
               "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)
-      refresh_status_bar
+      @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups)
     end
 
     # Removes a shortcut previously installed by {#register_global_shortcut}.
@@ -473,23 +504,14 @@ module Tuile
     # @return [void]
     def unregister_global_shortcut(key)
       @global_shortcuts.delete(key)
-      refresh_status_bar
     end
 
-    # @return [Component, nil] current active tiled component.
-    def active_window
-      check_locked
-      result = nil
-      @pane.content&.on_tree { result = _1 if _1.is_a?(Component::Window) && _1.active? }
-      result
-    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
@@ -512,10 +534,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)
@@ -561,15 +583,40 @@ 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
+    # went nowhere, e.g. a letter matching no menu mnemonic while a menu is
+    # open.
+    #
+    #   return true if activate_mnemonic(key)
+    #
+    #   screen.beep   # no match: the key is swallowed, say so
+    #   true
+    #
+    # Writes **immediately** rather than riding the next frame: a beep is not
+    # part of a frame, and the keystrokes worth beeping at are precisely the
+    # ones that invalidate nothing, so {#repaint} may never emit at all. Whether
+    # the user hears anything is the terminal's setting to make, so there is no
+    # Tuile-level enable/disable knob.
+    # @return [void]
+    def beep
+      check_locked
+      print(Ansi::BEL)
     end
 
     # Repaints the screen; tries to be as effective as possible, by only
@@ -602,10 +649,9 @@ module Tuile
 
         # Build the repaint list in z-order, leaning on the tree itself rather
         # than a depth sort. The pane's pre-order traversal already orders the
-        # tiled layer (content subtree + status bar) parent-before-child; the
-        # popups are the top layer and must paint last. The status bar is a
-        # *late* pane child yet sits under the popups, so a single pane.on_tree
-        # walk won't do — we collect the tiled layer first, then append popups.
+        # tiled layer (the content subtree) parent-before-child; the popups are
+        # the top layer and must paint last, so we collect the tiled layer first
+        # and append popups rather than taking a single pane.on_tree walk.
         popup_members = Set.new
         popups.each { |p| p.on_tree { popup_members << _1 } }
 
@@ -620,12 +666,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
@@ -650,25 +706,53 @@ 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
+    # 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
+
     # 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
@@ -770,6 +854,17 @@ module Tuile
     # @return [void]
     def handle_mouse(event) = @pane.handle_mouse(event)
 
+    # Delivers pasted text down the focus chain ({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.
+    # @param text [String]
+    # @return [Boolean] true if some component consumed it.
+    def handle_paste(text) = @pane.handle_paste(text)
+
     # @return [void]
     def event_loop
       @event_queue.run_loop do |event|
@@ -778,6 +873,8 @@ module Tuile
           key = event.key
           handled = handle_key(key)
           @event_queue.stop if !handled && ["q", Keys::ESC].include?(key)
+        when EventQueue::PasteEvent
+          handle_paste(event.text)
         when MouseEvent
           handle_mouse(event)
         when EventQueue::TTYSizeEvent
@@ -785,6 +882,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