tuile 0.7.0 → 0.8.0

data/lib/tuile/screen.rb

@@ -45,6 +45,10 @@ module Tuile
       # 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.
+      @buffer = Buffer.new(@size)
     end
 
     # Entry in the global shortcut registry: the block to run, whether it
@@ -56,6 +60,10 @@ module Tuile
     # @return [ScreenPane] the structural root of the component tree.
     attr_reader :pane
 
+    # @return [Buffer] the back buffer components paint into
+    #   ({Buffer#set_line} / {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).
     #
@@ -232,7 +240,7 @@ module Tuile
     # @api private
     # @return [void]
     def refresh_status_bar
-      top_popup = @pane.popups.last
+      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,
@@ -449,31 +457,16 @@ module Tuile
       @@instance&.close
     end
 
-    # Prints given strings. While {#repaint} is running, writes are
-    # accumulated into a frame buffer and flushed to the terminal as a
-    # single `$stdout.write` at the end of the cycle. This stops the
-    # emulator from rendering half-finished frames (e.g. a layout's
-    # clear-background pass before its children have re-painted), which
-    # was visible as a brief flicker when the auto-clear path triggers.
-    #
-    # Outside repaint, writes go straight to stdout. We deliberately
-    # don't raise on a "print outside repaint" — that would be a useful
-    # guardrail against components painting outside the repaint loop,
-    # but it'd force terminal-housekeeping writes (`Screen#clear`,
-    # mouse-tracking start/stop, cursor-show on teardown) to bypass
-    # this method entirely and write directly to `$stdout`. {FakeScreen}
-    # overrides `print` to capture every byte into its `@prints` array,
-    # and tests that exercise `run_event_loop` against a real {Screen}
-    # would otherwise leak escape sequences to the test runner's stdout.
-    # Keeping `print` as the single sink preserves that override seam.
+    # 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.
     # @param args [String] stuff to print.
     # @return [void]
     def print(*args)
-      if @frame_buffer
-        args.each { |s| @frame_buffer << s.to_s }
-      else
-        Kernel.print(*args)
-      end
+      Kernel.print(*args)
     end
 
     # Repaints the screen; tries to be as effective as possible, by only
@@ -489,64 +482,61 @@ module Tuile
       # simple and very fast in common cases.
 
       did_paint = false
-      @frame_buffer = +""
-      begin
-        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? }
-          break if @invalidated.empty?
-
-          did_paint = true
-          popups = @pane.popups
-
-          # Partition invalidated components into tiled vs popup-tree. Sorting
-          # by depth across the whole tree would interleave them: a tiled
-          # grandchild (depth 3) sorts after a popup's content (depth 2) and
-          # overdraws it.
-          popup_tree = Set.new
-          popups.each { |p| p.on_tree { popup_tree << _1 } }
-          tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(_1) }
-
-          # Within the tiled tree, paint parents before children.
-          tiled.sort_by!(&:depth)
-
-          repaint = if tiled.empty?
-                      # Only popups need repaint — paint just their invalidated
-                      # components in depth order.
-                      popup_invalidated.sort_by(&:depth)
-                    else
-                      # Tiled components may overdraw popups; repaint each open
-                      # popup's full subtree on top, in stacking order
-                      # (parent-before-child within each popup).
-                      tiled + popups.flat_map { |p| collect_subtree(p) }
-                    end
-
-          @repainting = repaint.to_set
-          @invalidated.clear
-
-          # Don't call {#clear} before repaint — causes flickering, and only
-          # needed when @content doesn't cover the entire screen.
-          repaint.each(&:repaint)
-
-          # Repaint done, mark all components as up-to-date.
-          @repainting.clear
+      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? }
+        break if @invalidated.empty?
+
+        did_paint = true
+        popups = @pane.popups
+
+        # 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.
+        popup_members = Set.new
+        popups.each { |p| p.on_tree { popup_members << _1 } }
+
+        # Tiled layer: invalidated non-popup components, in tree order.
+        repaint = []
+        tiled_invalidated = false
+        @pane.on_tree do |c|
+          next if popup_members.include?(c)
+          next unless @invalidated.include?(c)
+
+          repaint << c
+          tiled_invalidated = true
         end
-        position_cursor if did_paint
-        unless @frame_buffer.empty?
-          $stdout.write(@frame_buffer)
-          $stdout.flush
+
+        # 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.each do |p|
+          p.on_tree { |c| repaint << c if tiled_invalidated || @invalidated.include?(c) }
         end
-      ensure
-        # Always release the frame buffer, even on exception, so any
-        # subsequent {#print} call (e.g. teardown emits during crash unwind)
-        # reaches stdout instead of being swallowed by a stranded buffer.
-        # The partial frame we hold here is incoherent — discard it.
-        @frame_buffer = nil
+
+        @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
+
+      # Flush only the changed cells, then reposition the cursor — all inside
+      # one synchronized-output batch so the terminal composites it atomically.
+      emit("#{Ansi::SYNC_BEGIN}#{@buffer.flush}#{cursor_sequence}#{Ansi::SYNC_END}")
     end
 
     # Returns the absolute screen coordinates where the hardware cursor should
@@ -588,7 +578,7 @@ module Tuile
     # @return [Boolean] true if focus moved.
     def cycle_focus(forward:)
       check_locked
-      scope = @pane.popups.last || @pane.content
+      scope = @pane.modal_popup || @pane.content
       return false if scope.nil?
 
       stops = []
@@ -607,25 +597,22 @@ module Tuile
       true
     end
 
-    # Collects a component and all its descendants in tree order
-    # (parent before children).
-    # @param component [Component]
-    # @return [Array<Component>]
-    def collect_subtree(component)
-      result = []
-      component.on_tree { result << _1 }
-      result
+    # The escape sequence positioning the hardware cursor for the current focus
+    # state: hidden when nothing owns it, else moved to the focused component's
+    # {Component#cursor_position} and shown. Appended to each frame's flush.
+    # @return [String]
+    def cursor_sequence
+      pos = cursor_position
+      pos.nil? ? TTY::Cursor.hide : "#{TTY::Cursor.move_to(pos.x, pos.y)}#{TTY::Cursor.show}"
     end
 
-    # Hides or moves the hardware cursor based on the current focus state.
+    # Writes an assembled frame (escape string) to the terminal. The single
+    # sink for repaint output; {FakeScreen} overrides it to capture instead.
+    # @param str [String]
     # @return [void]
-    def position_cursor
-      pos = cursor_position
-      if pos.nil?
-        print TTY::Cursor.hide
-      else
-        print TTY::Cursor.move_to(pos.x, pos.y), TTY::Cursor.show
-      end
+    def emit(str)
+      $stdout.write(str)
+      $stdout.flush
     end
 
     # Recalculates positions of all windows, and repaints the scene.
@@ -634,6 +621,7 @@ module Tuile
     # @return [void]
     def layout
       check_locked
+      @buffer.resize(size) unless @buffer.size == size
       needs_full_repaint
       @pane.rect = Rect.new(0, 0, size.width, size.height)
       repaint
@@ -649,10 +637,12 @@ module Tuile
     #      doesn'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 popup is open
-    #      (otherwise the popup receives the key normally).
-    #   3. {ScreenPane#handle_key}, which routes to the topmost popup or
-    #      tiled content.
+    #      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.
     # @param key [String]
     # @return [Boolean] true if the key was handled by some window.
     def handle_key(key)
@@ -665,7 +655,7 @@ module Tuile
         true
       else
         shortcut = @global_shortcuts[key]
-        if !shortcut.nil? && (shortcut.over_popups || @pane.popups.empty?)
+        if !shortcut.nil? && (shortcut.over_popups || @pane.modal_popup.nil?)
           shortcut.block.call
           true
         else

data/lib/tuile/screen_pane.rb

@@ -28,8 +28,9 @@ module Tuile
 
     # @return [Component, nil] the tiled content component.
     attr_reader :content
-    # @return [Array<Component>] modal popups in stacking order; last is
-    #   topmost. The array must not be mutated by callers.
+    # @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.
     attr_reader :popups
     # @return [Component::Label] the bottom status bar.
     attr_reader :status_bar
@@ -57,7 +58,11 @@ module Tuile
       layout
     end
 
-    # Adds a popup, centers it, focuses it, and invalidates it for repaint.
+    # 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.
     # @param window [Component::Popup]
     # @return [void]
     def add_popup(window)
@@ -67,8 +72,10 @@ module Tuile
       @popup_prior_focus[window] = screen.focused
       @popups << window
       window.parent = self
-      window.center
-      screen.focused = window
+      if window.modal?
+        window.center
+        screen.focused = window
+      end
       screen.invalidate(window)
     end
 
@@ -100,6 +107,13 @@ 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
+    #   owner": the popup that scopes key dispatch, blocks mouse clicks, owns
+    #   the status bar, and confines Tab cycling. Non-modal 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.
     # @param new_rect [Rect]
     # @return [void]
@@ -109,13 +123,14 @@ module Tuile
     end
 
     # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Popups self-position via {Component::Popup#center}.
+    # (bottom row). Modal popups self-recenter via {Component::Popup#center};
+    # non-modal overlays keep the position their owner assigned.
     # @return [void]
     def layout
       return if rect.empty?
 
       @content.rect = Rect.new(rect.left, rect.top, rect.width, [rect.height - 1, 0].max) unless @content.nil?
-      @popups.each(&:center)
+      @popups.each { |p| p.center if p.modal? }
       @status_bar.rect = Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
     end
 
@@ -123,32 +138,55 @@ module Tuile
     # @return [void]
     def repaint; end
 
-    # Topmost popup is modal: it eats keys. Falls through to content only
-    # when no popup is open.
+    # 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.
+    #
+    # 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.
+    # @param key [String]
+    # @return [Boolean] true if the key was handled.
     def handle_key(key)
-      topmost = @popups.last
-      return topmost.handle_key(key) unless topmost.nil?
-      return @content.handle_key(key) unless @content.nil?
+      scope = modal_popup || @content
+      return false if scope.nil?
 
-      false
+      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
 
     # Mouse events check popups in reverse stacking order (topmost first), and
-    # fall through to content only when no popup is hit *and* there are no
-    # popups open. This preserves modal click-blocking: an open popup eats
-    # clicks even outside its rect.
+    # fall through to content only when no popup is hit *and* no modal popup is
+    # open. This preserves modal click-blocking — an open modal eats clicks
+    # even outside its rect — while a non-modal overlay blocks nothing: clicks
+    # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
+    # content beneath.
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
       clicked = @popups.reverse_each.find { _1.rect.contains?(event.point) }
-      clicked = @content if clicked.nil? && @popups.empty?
+      clicked = @content if clicked.nil? && modal_popup.nil?
       clicked&.handle_mouse(event)
     end
 
     # Focus repair when a child detaches. Default {Component#on_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
     # Instead, route focus to the first interactable widget in the now-topmost
-    # popup; falling back to the focus snapshotted when this popup was opened
+    # modal popup; falling back to the focus snapshotted when this popup was opened
     # (if still attached and still focusable); then to the first interactable
     # widget in {#content}; then to {#content} itself; then nil.
     #
@@ -167,7 +205,7 @@ module Tuile
       cursor = f
       while cursor
         if cursor == child
-          fallback = first_tab_stop_or_root(@popups.last)
+          fallback = first_tab_stop_or_root(modal_popup)
           if fallback.nil? && @removing_popup_prior&.attached? && @removing_popup_prior.focusable?
             fallback = @removing_popup_prior
           end
@@ -181,6 +219,29 @@ module Tuile
 
     private
 
+    # Delivers `key` to {Screen#focused} and bubbles it up the ancestor chain,
+    # stopping at (and including) `scope`. Delivers to no one — returning false
+    # — when focus is nil or sits outside `scope`; the latter is what makes an
+    # open popup modal, since focus is always inside it and content beneath
+    # never receives keys.
+    # @param key [String]
+    # @param scope [Component] the modal scope root (topmost popup or content).
+    # @return [Boolean] true if some component on the chain handled the key.
+    def bubble_key(key, scope)
+      chain = []
+      cursor = screen.focused
+      until cursor.nil?
+        chain << cursor
+        break if cursor.equal?(scope)
+
+        cursor = cursor.parent
+      end
+      return false unless chain.last.equal?(scope)
+
+      chain.each { |c| return true if c.handle_key(key) }
+      false
+    end
+
     # 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`.

data/lib/tuile/styled_string.rb

@@ -105,6 +105,45 @@ module Tuile
       # @param overrides [Hash{Symbol => Object}]
       # @return [Style]
       def merge(**overrides) = self.class.new(**to_h.merge(overrides))
+
+      # Minimal SGR escape that transitions a terminal already showing `self`
+      # into `other`: only the attributes that differ are emitted. Returns
+      # `""` when the styles are identical (nothing to do), and {Ansi::RESET}
+      # (`\e[0m`, one code) when `other` is the default style — shorter than
+      # turning each attribute off individually.
+      #
+      # Shared by {StyledString#to_ansi} (diffing span-to-span from the default
+      # style) and {Buffer}'s flush (diffing cell-to-cell against the style the
+      # terminal currently holds), so both emit identical minimal sequences.
+      # @param other [Style] the style to transition to.
+      # @return [String]
+      def sgr_to(other)
+        return "" if self == other
+        return Ansi::RESET if other.default?
+
+        codes = []
+        codes << (other.bold ? 1 : 22) if bold != other.bold
+        codes << (other.italic ? 3 : 23) if italic != other.italic
+        codes << (other.underline ? 4 : 24) if underline != other.underline
+        codes << (other.strikethrough ? 9 : 29) if strikethrough != other.strikethrough
+        codes.concat(color_codes(other.fg, target: :fg)) if fg != other.fg
+        codes.concat(color_codes(other.bg, target: :bg)) if bg != other.bg
+        return "" if codes.empty?
+
+        "\e[#{codes.join(";")}m"
+      end
+
+      private
+
+      # @param color [Color, nil]
+      # @param target [Symbol] either `:fg` or `:bg`.
+      # @return [Array<Integer>] SGR codes; `[39]` / `[49]` for the "default"
+      #   reset when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
+      def color_codes(color, target:)
+        return [target == :fg ? 39 : 49] if color.nil?
+
+        color.sgr_codes(target)
+      end
     end
 
     # A maximal run of text sharing a single {Style}. `text` is plain — it
@@ -586,7 +625,7 @@ module Tuile
       out = +""
       current = Style::DEFAULT
       @spans.each do |span|
-        out << sgr_diff(current, span.style)
+        out << current.sgr_to(span.style)
         out << span.text
         current = span.style
       end
@@ -611,35 +650,6 @@ module Tuile
       result
     end
 
-    # @param from [Style]
-    # @param to [Style]
-    # @return [String]
-    def sgr_diff(from, to)
-      return "" if from == to
-      return Ansi::RESET if to.default?
-
-      codes = []
-      codes << (to.bold ? 1 : 22) if from.bold != to.bold
-      codes << (to.italic ? 3 : 23) if from.italic != to.italic
-      codes << (to.underline ? 4 : 24) if from.underline != to.underline
-      codes << (to.strikethrough ? 9 : 29) if from.strikethrough != to.strikethrough
-      codes.concat(color_codes(to.fg, target: :fg)) if from.fg != to.fg
-      codes.concat(color_codes(to.bg, target: :bg)) if from.bg != to.bg
-      return "" if codes.empty?
-
-      "\e[#{codes.join(";")}m"
-    end
-
-    # @param color [Color, nil]
-    # @param target [Symbol] `:fg` or `:bg`.
-    # @return [Array<Integer>] SGR codes; `[39]` / `[49]` for the "default" reset
-    #   when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
-    def color_codes(color, target:)
-      return [target == :fg ? 39 : 49] if color.nil?
-
-      color.sgr_codes(target)
-    end
-
     # @param start_or_range [Integer, Range]
     # @param len [Integer, nil]
     # @param total [Integer] receiver's full display width.

data/lib/tuile/version.rb

@@ -2,5 +2,5 @@
 
 module Tuile
   # @return [String]
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end