thaum 0.1.0 → 0.2.0

data/lib/thaum/concerns/layout.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Concerns
+    module Layout
+      attr_reader :rect, :leaf_sigils, :subtree_leaves, :child_layouts, :subtree_children
+
+      # Override on any Layout node (including App) to specify a Tab traversal
+      # order for that subtree. Return an array of leaf Sigils. nil (default)
+      # means "use left-to-right leaf order."
+      def focus_order = nil
+
+      # Called by the run loop (or repartition) to assign geometry and walk the partition tree.
+      # Returns the flat list of leaf Sigils in render order.
+      def run_partition(rect:, collector: nil)
+        @rect = rect
+        collector ||= []
+        start = collector.size
+        @leaf_sigils     = collector
+        @child_layouts   = []
+        @subtree_children = []
+        # An Octagram may inset the rect its children partition into so its
+        # render hook (border, padding) survives. Plain Layout passes through.
+        @rect = inset_for_partition(rect)
+        partition
+        @rect = rect
+        @subtree_leaves = collector[start..] || []
+        collector
+      end
+
+      # Override on Octagram (or any Layout) to inset the rect that this
+      # node's children partition into. Defaults to identity.
+      def inset_for_partition(rect)
+        return rect unless respond_to?(:partition_inset)
+
+        inset = partition_inset || {}
+        Rect.new(
+          x:      rect.x + (inset[:left]   || 0),
+          y:      rect.y + (inset[:top]    || 0),
+          width:  [rect.width  - (inset[:left] || 0) - (inset[:right]  || 0), 0].max,
+          height: [rect.height - (inset[:top]  || 0) - (inset[:bottom] || 0), 0].max
+        )
+      end
+
+      # Re-run partition for this node's subtree using its current rect.
+      def repartition
+        return unless @rect
+
+        old_leaves    = @leaf_sigils || []
+        old_octagrams = collect_octagrams
+
+        new_leaves = []
+        run_partition(rect: @rect, collector: new_leaves)
+
+        new_octagrams = collect_octagrams
+
+        # Fire on_unmount for removed Sigils and Octagrams.
+        (old_leaves - new_leaves).each(&:on_unmount)
+        (old_octagrams - new_octagrams).each(&:on_unmount)
+
+        # Rewire handler parents across the (possibly restructured) subtree so
+        # newly-added Octagrams and Sigils see the right chain BEFORE on_mount.
+        # Only rewires when we can identify this node's role in the dispatch
+        # chain — App (root) or Octagram (its own handler scope).
+        app = thaum_app_ref || (is_a?(Octagram) ? @thaum_app : nil)
+        wire_handler_parents(handler_parent: self, app: app) if app
+
+        # Fire on_mount for newly-added Sigils and Octagrams.
+        (new_octagrams - old_octagrams).each do |o|
+          o.thaum_app = app if app
+          o.on_mount
+        end
+        (new_leaves - old_leaves).each do |s|
+          s.thaum_app = app if app
+          s.on_mount
+        end
+
+        @leaf_sigils = new_leaves
+
+        # Re-validate focus_order in this subtree after structural change.
+        validate_focus_order_tree
+      end
+
+      # Walk this subtree and collect every Octagram node (excluding self).
+      def collect_octagrams
+        result = []
+        (@subtree_children || []).each do |child|
+          if child.is_a?(Octagram)
+            result << child
+            result.concat(child.collect_octagrams)
+          elsif child.respond_to?(:collect_octagrams)
+            result.concat(child.collect_octagrams)
+          end
+        end
+        result
+      end
+
+      # Walk this Layout node and every descendant Layout, raising
+      # FocusOrderError if any defines a focus_order that does not exactly
+      # cover the focusable leaves in its subtree.
+      def validate_focus_order_tree
+        validate_focus_order_node
+        (@child_layouts || []).each(&:validate_focus_order_tree)
+      end
+
+      # Build the Tab traversal order for this subtree, recursively expanding
+      # any nested Layout that itself has focus_order. When no focus_order is
+      # defined at any level, this falls through to left-to-right leaf order.
+      def effective_focus_order
+        order = focus_order
+        return order if order
+
+        result = []
+        layout_subtree_in_order.each do |node|
+          if node.is_a?(Sigil)
+            result << node if node.focusable?
+          else
+            result.concat(node.effective_focus_order)
+          end
+        end
+        result
+      end
+
+      # The direct children of this Layout in declaration order — both Sigils
+      # and nested Layouts. Built during partition (see place_child).
+      def layout_subtree_in_order = @subtree_children || []
+
+      # Scope units for Tab cycling within THIS focus scope. A "scope" is the
+      # App or an Octagram. A unit is either a focusable Sigil (reached through
+      # plain Layouts only) or a nested Octagram (which appears as one unit and
+      # is itself a scope). Plain Layouts are transparent — their units are
+      # flattened into the parent scope.
+      def focus_scope_units
+        result = []
+        (@subtree_children || []).each do |child|
+          case child
+          when Sigil
+            result << child if child.focusable?
+          when Octagram
+            result << child if child.focusable_descendant?
+          else
+            result.concat(child.focus_scope_units) if child.respond_to?(:focus_scope_units)
+          end
+        end
+        result
+      end
+
+      # Recursively descend into this Octagram (or plain Layout) to find its
+      # first focusable leaf — used when Tab enters an Octagram unit.
+      def first_focusable_leaf
+        (@subtree_children || []).each do |child|
+          case child
+          when Sigil
+            return child if child.focusable?
+          else
+            leaf = child.first_focusable_leaf if child.respond_to?(:first_focusable_leaf)
+            return leaf if leaf
+          end
+        end
+        nil
+      end
+
+      # Mirror of first_focusable_leaf for Shift-Tab entry.
+      def last_focusable_leaf
+        (@subtree_children || []).reverse_each do |child|
+          case child
+          when Sigil
+            return child if child.focusable?
+          else
+            leaf = child.last_focusable_leaf if child.respond_to?(:last_focusable_leaf)
+            return leaf if leaf
+          end
+        end
+        nil
+      end
+
+      def focusable_descendant?
+        !first_focusable_leaf.nil?
+      end
+
+      # Walk the subtree top-down, wiring each leaf Sigil and each Octagram.
+      # Leaves and Octagrams get _handler_parent set to the innermost
+      # enclosing Octagram (or the App when there is none). Plain Layout
+      # nodes are transparent — their children inherit the outer parent.
+      def wire_handler_parents(handler_parent:, app:)
+        (@subtree_children || []).each do |child|
+          case child
+          when Sigil
+            child.handler_parent = handler_parent
+            child.thaum_app      = app
+          when Octagram
+            child.handler_parent = handler_parent
+            child.thaum_app      = app
+            child.wire_handler_parents(handler_parent: child, app: app)
+          else
+            child.wire_handler_parents(handler_parent:, app:) if child.respond_to?(:wire_handler_parents)
+          end
+        end
+      end
+
+      # Override to specify the layout. Must call horizontal/vertical.
+      def partition; end
+
+      private
+
+      def horizontal(&) = divide_axis(:cols, &)
+      def vertical(&)   = divide_axis(:rows, &)
+
+      def region(**opts, &child_block)
+        @divide_frame << { opts: opts, block: child_block }
+      end
+
+      def divide_axis(axis, &block)
+        parent_rect = @rect
+        saved_frame = @divide_frame
+        @divide_frame = []
+
+        block.call
+
+        specs = @divide_frame
+        @divide_frame = saved_frame
+
+        validate_axis_kwargs(axis: axis, specs: specs)
+
+        calc_rects(parent_rect: parent_rect, axis: axis, specs: specs).each_with_index do |child_rect, i|
+          @rect = child_rect
+          place_child(child: specs[i][:block].call, rect: child_rect)
+        end
+
+        @rect = parent_rect
+      end
+
+      def validate_axis_kwargs(axis:, specs:)
+        expected, forbidden = axis == :cols ? %i[width height] : %i[height width]
+        specs.each do |spec|
+          next unless spec[:opts].key?(forbidden)
+
+          direction = axis == :cols ? "horizontal" : "vertical"
+          raise LayoutError,
+                "region(#{forbidden}:) is invalid inside #{direction} — use #{expected}: instead"
+        end
+      end
+
+      def place_child(child:, rect:)
+        @subtree_children ||= []
+        if child.is_a?(Sigil)
+          child.rect = rect
+          @leaf_sigils << child
+          @subtree_children << child
+        elsif child.respond_to?(:run_partition)
+          @child_layouts << child
+          @subtree_children << child
+          child.run_partition(rect: rect, collector: @leaf_sigils)
+        end
+      end
+
+      def validate_focus_order_node
+        order = focus_order
+        return if order.nil?
+
+        unless order.is_a?(Array)
+          raise FocusOrderError,
+                "#{self.class}#focus_order must return an Array, got #{order.class}"
+        end
+
+        focusable = (@subtree_leaves || []).select(&:focusable?)
+        missing    = focusable - order
+        extras     = order - focusable
+        duplicates = order.tally.select { |_, c| c > 1 }.keys
+
+        return if missing.empty? && extras.empty? && duplicates.empty?
+
+        msg = "#{self.class}#focus_order is invalid:"
+        msg += " missing #{missing.map(&:class).join(', ')};" unless missing.empty?
+        msg += " unknown entries #{extras.map(&:class).join(', ')};" unless extras.empty?
+        msg += " duplicates #{duplicates.map(&:class).join(', ')};" unless duplicates.empty?
+        raise FocusOrderError, msg
+      end
+
+      def calc_rects(parent_rect:, axis:, specs:)
+        if axis == :cols
+          total       = parent_rect.width
+          fixed_total = specs.sum { |s| integer_size(val: s[:opts][:width], total: total) || 0 }
+          fill_count  = specs.count { |s| s[:opts][:width] == :fill }
+          fill_size   = fill_count.positive? ? (total - fixed_total) / fill_count : 0
+          leftover    = fill_count.positive? ? (total - fixed_total) % fill_count : 0
+
+          x = parent_rect.x
+          specs.each_with_index.map do |spec, i|
+            fill_index = specs[0..i].count { |s| s[:opts][:width] == :fill } - 1
+            last_fill  = fill_index >= 0 && fill_index == fill_count - 1
+
+            w = resolved_size(val: spec[:opts][:width], total: total, fill_size: fill_size,
+                              extra: last_fill ? leftover : 0)
+            w = apply_min_max(size: w, min: spec[:opts][:min], max: spec[:opts][:max])
+            r = Rect.new(x: x, y: parent_rect.y, width: w, height: parent_rect.height)
+            x += w
+            r
+          end
+        else
+          total       = parent_rect.height
+          fixed_total = specs.sum { |s| integer_size(val: s[:opts][:height], total: total) || 0 }
+          fill_count  = specs.count { |s| s[:opts][:height] == :fill }
+          fill_size   = fill_count.positive? ? (total - fixed_total) / fill_count : 0
+          leftover    = fill_count.positive? ? (total - fixed_total) % fill_count : 0
+
+          y = parent_rect.y
+          specs.each_with_index.map do |spec, i|
+            fill_index = specs[0..i].count { |s| s[:opts][:height] == :fill } - 1
+            last_fill  = fill_index >= 0 && fill_index == fill_count - 1
+
+            h = resolved_size(val: spec[:opts][:height], total: total, fill_size: fill_size,
+                              extra: last_fill ? leftover : 0)
+            h = apply_min_max(size: h, min: spec[:opts][:min], max: spec[:opts][:max])
+            r = Rect.new(x: parent_rect.x, y: y, width: parent_rect.width, height: h)
+            y += h
+            r
+          end
+        end
+      end
+
+      def integer_size(val:, total:)
+        return val             if val.is_a?(Integer)
+        return nil             if val == :fill
+        return val.to_i * total / 100 if val.is_a?(String) && val.end_with?("%")
+
+        nil
+      end
+
+      def resolved_size(val:, total:, fill_size:, extra:)
+        return val + 0                             if val.is_a?(Integer)
+        return fill_size + extra                   if val == :fill
+        return val.to_i * total / 100 if val.is_a?(String) && val.end_with?("%")
+
+        fill_size + extra # default to fill if unspecified
+      end
+
+      def apply_min_max(size:, min:, max:)
+        size = [size, min].max if min
+        size = [size, max].min if max
+        [size, 0].max
+      end
+
+      # Used by repartition to wire new sigils to the app.
+      # overridden in App
+      def thaum_app_ref = nil
+    end
+  end
+end

data/lib/thaum/concerns/modal.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Concerns
+    module Modal
+      # --- Modal ---
+
+      # Show a modal Sigil as an overlay above the layout tree. width/height
+      # are required; x/y are optional terminal-absolute coords — when nil
+      # the modal is centered on the current terminal size. Calling show_modal
+      # while a modal is already active fires on_blur + on_unmount on the
+      # outgoing modal and replaces it. The previously-focused Sigil (from
+      # before any modal was shown) is preserved so hide_modal can restore it.
+      def show_modal(sigil:, width:, height:, x: nil, y: nil)
+        replacing = !@modal_sigil.nil?
+        centered  = x.nil? && y.nil?
+
+        if replacing
+          Thaum.safe_invoke("#{@modal_sigil.class}#on_blur")    { @modal_sigil.on_blur }
+          Thaum.safe_invoke("#{@modal_sigil.class}#on_unmount") { @modal_sigil.on_unmount }
+          @modal_sigil.thaum_app      = nil
+          @modal_sigil.handler_parent = nil
+          @modal_sigil.rect = nil
+        elsif @focused_sigil
+          # First modal — save the underlying focused Sigil and fire its on_blur.
+          @previous_focus = @focused_sigil
+          Thaum.safe_invoke("#{@focused_sigil.class}#on_blur") { @focused_sigil.on_blur }
+          @focused_sigil = nil
+        end
+
+        rect = compute_modal_rect(width: width, height: height, x: x, y: y)
+
+        @modal_sigil      = sigil
+        @modal_rect       = rect
+        @modal_centered   = centered
+        @modal_decl_w     = width
+        @modal_decl_h     = height
+        sigil.thaum_app      = self
+        sigil.handler_parent = self
+        sigil.rect = rect
+
+        Thaum.safe_invoke("#{sigil.class}#on_mount") { sigil.on_mount }
+        Thaum.safe_invoke("#{sigil.class}#on_focus") { sigil.on_focus }
+
+        request_render
+        sigil
+      end
+
+      def hide_modal
+        sigil = @modal_sigil
+        return unless sigil
+
+        Thaum.safe_invoke("#{sigil.class}#on_blur")    { sigil.on_blur }
+        Thaum.safe_invoke("#{sigil.class}#on_unmount") { sigil.on_unmount }
+
+        @modal_sigil      = nil
+        @modal_rect       = nil
+        @modal_centered   = false
+        @modal_decl_w     = nil
+        @modal_decl_h     = nil
+        sigil.thaum_app      = nil
+        sigil.handler_parent = nil
+        sigil.rect = nil
+
+        restored = @previous_focus
+        @previous_focus = nil
+        if restored && focusable_and_mounted?(restored)
+          @focused_sigil = restored
+          Thaum.safe_invoke("#{restored.class}#on_focus") { restored.on_focus }
+        end
+
+        request_render
+        nil
+      end
+
+      def modal_active? = !@modal_sigil.nil?
+
+      # Called by the framework on ResizeEvent after the layout repartitions.
+      # Re-centers a default-centered modal on the new terminal dimensions.
+      # Modals with explicit x/y stay put.
+      def recompute_modal_rect
+        return unless @modal_sigil && @modal_centered
+
+        @modal_rect = compute_modal_rect(width: @modal_decl_w, height: @modal_decl_h, x: nil, y: nil)
+        @modal_sigil.rect = @modal_rect
+      end
+
+      private
+
+      # Compute the modal's terminal-absolute rect from declared size + optional
+      # x/y. When x/y are nil, centers on the App's current rect (set by
+      # run_partition to the terminal's dimensions). Overflow is allowed —
+      # the Buffer drops out-of-bounds cells at paint time.
+      def compute_modal_rect(width:, height:, x:, y:)
+        app_rect = @rect || Rect.new(x: 0, y: 0, width: 0, height: 0)
+        cx = x.nil? ? app_rect.x + ((app_rect.width  - width)  / 2) : x
+        cy = y.nil? ? app_rect.y + ((app_rect.height - height) / 2) : y
+        Rect.new(x: cx, y: cy, width: width, height: height)
+      end
+    end
+  end
+end

data/lib/thaum/concerns/tab_navigation.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Concerns
+    module TabNavigation
+      # Called by the framework before App#on_key sees a bubbled :tab.
+      # Shift-Tab moves focus backward; plain Tab moves forward. The App's
+      # on_key then runs with focus already updated (see spec — Tab pipeline).
+      #
+      # When the focused Sigil is inside an Octagram, cycling is SCOPED to
+      # that Octagram's focusable units first. Reaching the boundary bubbles
+      # to the parent scope (next outer Octagram, or the App), which treats
+      # the inner Octagram as a single unit. The App falls back to the flat
+      # focus_next/focus_prev path only when no Octagram boundaries are
+      # involved — preserving existing behavior for Octagram-free apps.
+      def handle_tab_cycle(event)
+        direction = event.shift? ? :prev : :next
+        sigil = @focused_sigil
+
+        if sigil && inside_octagram?(sigil)
+          target = scoped_tab_target(sigil: sigil, direction: direction)
+          focus(target) if target
+        else
+          direction == :next ? focus_next : focus_prev
+        end
+      end
+
+      private
+
+      # True when the Sigil's handler chain crosses at least one Octagram.
+      def inside_octagram?(sigil)
+        parent = sigil.handler_parent
+        while parent
+          return true if parent.is_a?(Octagram)
+
+          parent = parent.respond_to?(:handler_parent) ? parent.handler_parent : nil
+        end
+        false
+      end
+
+      # Walk scopes from innermost outward. At each scope, find the unit
+      # representing where we currently are (the sigil itself, or the inner
+      # Octagram unit we just bubbled out of). Step one unit in `direction`.
+      # If stepping would wrap past the scope boundary, bubble to the parent
+      # scope. App scope wraps within itself (the final fallback).
+      def scoped_tab_target(sigil:, direction:)
+        scope         = innermost_octagram_for(sigil)
+        current_unit  = sigil
+
+        loop do
+          units = scope.focus_scope_units
+          idx   = units.index(current_unit)
+          # Defensive: if current_unit isn't in this scope's units, treat as
+          # entering from before the first (next) or after the last (prev).
+          return resolve_unit(unit: units.first, direction: direction) if idx.nil? && !units.empty?
+
+          step      = direction == :next ? 1 : -1
+          new_idx   = idx + step
+          in_bounds = new_idx >= 0 && new_idx < units.size
+
+          if in_bounds
+            return resolve_unit(unit: units[new_idx], direction: direction)
+          elsif scope.equal?(self)
+            # At App scope — wrap.
+            wrapped = direction == :next ? units.first : units.last
+            return resolve_unit(unit: wrapped, direction: direction)
+          else
+            # Bubble to parent scope; the Octagram itself becomes the unit.
+            current_unit = scope
+            scope        = innermost_octagram_for(scope) || self
+          end
+        end
+      end
+
+      # Drill into a unit to get the focusable Sigil to focus. Plain Sigil →
+      # itself. Octagram → first (or last) focusable leaf.
+      def resolve_unit(unit:, direction:)
+        return unit if unit.is_a?(Sigil)
+        return nil  unless unit.respond_to?(:first_focusable_leaf)
+
+        direction == :next ? unit.first_focusable_leaf : unit.last_focusable_leaf
+      end
+
+      # Innermost enclosing Octagram in the handler chain, or nil if none
+      # (focused sigil is directly under App with no Octagram between).
+      def innermost_octagram_for(node)
+        parent = node.handler_parent
+        while parent
+          return parent if parent.is_a?(Octagram)
+
+          parent = parent.respond_to?(:handler_parent) ? parent.handler_parent : nil
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/thaum/dispatch.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Routes an event to the right handler.
+  #
+  # Two entry points share the same per-event-type case in {#invoke_handler}:
+  #
+  #   {.from_queue} — events popped off the main run-loop queue. Routes by
+  #                   target (modal vs focused Sigil vs App) and returns
+  #                   true when the caller should mark the app dirty.
+  #   {.from_child} — bubbled events from a Sigil's emit. Routes to the
+  #                   handler parent (next outer Octagram, or the App).
+  module Dispatch
+    module_function
+
+    # Route one event popped off the main queue. Sets the dirty flag for
+    # every routed event that does not opt out (TickEvent and unknown
+    # objects are the only opt-outs).
+    def from_queue(app:, event:)
+      if quit_shortcut?(event)
+        app.quit
+        return
+      end
+
+      modal = app.modal_sigil
+      auto_dirty =
+        case event
+        when KeyEvent   then route_key(app: app, modal: modal, event: event)
+        when PasteEvent then route_paste(app: app, modal: modal, event: event)
+        when MouseEvent then route_mouse(app: app, modal: modal, event: event)
+        when ResizeEvent
+          Thaum.safe_invoke("App#on_resize") { app.on_resize(event) }
+          true
+        when TickEvent
+          route_tick(app: app, modal: modal, event: event)
+          false
+        when Event
+          Thaum.safe_invoke("App#on_event") { app.on_event(event) }
+          true
+        else
+          false
+        end
+
+      app.request_render if auto_dirty
+    end
+
+    # Bubbled from a Sigil emit. Caller (App or Octagram) supplies its own
+    # safe_invoke label so the stderr trace identifies the handler.
+    def invoke_handler(target:, event:, label:)
+      Thaum.safe_invoke(label) do
+        case event
+        when KeyEvent   then target.on_key(event)
+        when MouseEvent then target.on_mouse(event)
+        when PasteEvent then target.on_paste(event)
+        else
+          target.on_event(event) if event.is_a?(Event)
+        end
+      end
+    end
+
+    def quit_shortcut?(event)
+      event.is_a?(KeyEvent) && event.ctrl? && event.key == "c"
+    end
+
+    def route_key(app:, modal:, event:)
+      return handle_modal_key(app: app, modal: modal, event: event) if modal
+
+      if (focused = app.focused_sigil)
+        Thaum.safe_invoke("#{focused.class}#on_key") { focused.on_key(event) }
+      else
+        app.handle_tab_cycle(event) if event.key == :tab
+        Thaum.safe_invoke("App#on_key") { app.on_key(event) }
+      end
+      true
+    end
+
+    def handle_modal_key(app:, modal:, event:)
+      # Plain Escape dismisses the modal — handler never sees it.
+      if event.key == :escape && !event.ctrl? && !event.alt? && !event.shift?
+        app.hide_modal
+        return true
+      end
+      # Tab / Shift-Tab are eaten while a modal is active.
+      return false if event.key == :tab
+
+      Thaum.safe_invoke("#{modal.class}#on_key") { modal.on_key(event) }
+      true
+    end
+
+    def route_paste(app:, modal:, event:)
+      target =
+        if modal
+          modal
+        elsif (focused = app.focused_sigil)
+          focused
+        else
+          app
+        end
+      label = target.equal?(app) ? "App#on_paste" : "#{target.class}#on_paste"
+      Thaum.safe_invoke(label) { target.on_paste(event) }
+      true
+    end
+
+    def route_mouse(app:, modal:, event:)
+      if modal
+        dispatch_modal_mouse(modal: modal, event: event, rect: app.modal_rect)
+      else
+        dispatch_mouse_event(app: app, event: event)
+      end
+      true
+    end
+
+    def route_tick(app:, modal:, event:)
+      Thaum.safe_invoke("App#on_tick") { app.on_tick(event) }
+      Tree.walk(app) do |node|
+        next unless node.is_a?(Sigil) || node.is_a?(Octagram)
+
+        Thaum.safe_invoke("#{node.class}#on_tick") { node.on_tick(event) }
+      end
+      # Modal Sigil ticks last, after the layout tree (per spec).
+      Thaum.safe_invoke("#{modal.class}#on_tick") { modal.on_tick(event) } if modal
+    end
+
+    # Hit-test by absolute coords, set canvas-relative x/y on the event, and
+    # dispatch to the hit Sigil's on_mouse. If no Sigil is hit, dispatch to
+    # the App's on_mouse with abs_x/abs_y unchanged. On :press, transfer
+    # focus to the hit Sigil if focusable.
+    def dispatch_mouse_event(app:, event:)
+      hit = HitTest.hit(app: app, abs_x: event.abs_x, abs_y: event.abs_y)
+      if hit
+        r = hit.rect
+        localized = event.with(x: event.abs_x - r.x, y: event.abs_y - r.y)
+        Thaum.safe_invoke("App#focus") { app.focus(hit) } if event.action == :press && hit.focusable?
+        Thaum.safe_invoke("#{hit.class}#on_mouse") { hit.on_mouse(localized) }
+      else
+        Thaum.safe_invoke("App#on_mouse") { app.on_mouse(event) }
+      end
+    end
+
+    # Route a MouseEvent to the modal Sigil, translating absolute coords to
+    # rect-relative. Out-of-bounds clicks are eaten.
+    def dispatch_modal_mouse(modal:, event:, rect:)
+      return unless rect && HitTest.point_in_rect?(x: event.abs_x, y: event.abs_y, rect: rect)
+
+      local = event.with(x: event.abs_x - rect.x, y: event.abs_y - rect.y)
+      Thaum.safe_invoke("#{modal.class}#on_mouse") { modal.on_mouse(local) }
+    end
+  end
+end