thaum 0.1.0 → 0.2.1

data/lib/thaum/key_event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Thaum
+  KeyEvent = Event.define(:key, :ctrl, :alt, :shift) do
+    def initialize(key:, ctrl: false, alt: false, shift: false)
+      super
+    end
+
+    def ctrl?  = ctrl
+    def alt?   = alt
+    def shift? = shift
+  end
+end

data/lib/thaum/keys.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Keys
+    # Control Sequence Introducer (CSI) sequences: \e[ + final byte
+    # e.g. up arrow → \e[A
+    CSI = {
+      Seq::CSI_UP[-1] => :up,
+      Seq::CSI_DOWN[-1] => :down,
+      Seq::CSI_RIGHT[-1] => :right,
+      Seq::CSI_LEFT[-1] => :left,
+      Seq::CSI_HOME[-1] => :home,
+      Seq::CSI_END[-1] => :end
+    }.freeze
+
+    # Control Sequence Introducer (CSI) tilde sequences: \e[ + number + ~
+    # e.g. delete → \e[3~  (the number identifies the key, ~ is always the final byte)
+    TILDE = {
+      Seq::TILDE_HOME[2..-2].to_i => :home,
+      Seq::TILDE_INSERT[2..-2].to_i => :insert,
+      Seq::TILDE_DELETE[2..-2].to_i => :delete,
+      Seq::TILDE_END[2..-2].to_i => :end,
+      Seq::TILDE_PAGE_UP[2..-2].to_i => :page_up,
+      Seq::TILDE_PAGE_DOWN[2..-2].to_i => :page_down,
+      Seq::TILDE_F1[2..-2].to_i => :f1,
+      Seq::TILDE_F2[2..-2].to_i => :f2,
+      Seq::TILDE_F3[2..-2].to_i => :f3,
+      Seq::TILDE_F4[2..-2].to_i => :f4,
+      Seq::TILDE_F5[2..-2].to_i => :f5,
+      Seq::TILDE_F6[2..-2].to_i => :f6,
+      Seq::TILDE_F7[2..-2].to_i => :f7,
+      Seq::TILDE_F8[2..-2].to_i => :f8,
+      Seq::TILDE_F9[2..-2].to_i => :f9,
+      Seq::TILDE_F10[2..-2].to_i => :f10,
+      Seq::TILDE_F11[2..-2].to_i => :f11,
+      Seq::TILDE_F12[2..-2].to_i => :f12
+    }.freeze
+
+    # Single Shift 3 (SS3) sequences: \eO + final byte
+    # Older VT100 encoding for function and arrow keys; many terminals still emit
+    # these for F1-F4 and arrows in application cursor mode.
+    SS3 = {
+      Seq::SS3_F1[-1] => :f1,
+      Seq::SS3_F2[-1] => :f2,
+      Seq::SS3_F3[-1] => :f3,
+      Seq::SS3_F4[-1] => :f4,
+      Seq::SS3_HOME[-1] => :home,
+      Seq::SS3_END[-1] => :end,
+      Seq::SS3_UP[-1] => :up,
+      Seq::SS3_DOWN[-1] => :down,
+      Seq::SS3_RIGHT[-1] => :right,
+      Seq::SS3_LEFT[-1] => :left
+    }.freeze
+  end
+end

data/lib/thaum/layout.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Thaum
+  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

data/lib/thaum/minitest.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Optional Minitest integration for Thaum snapshot testing.
+#
+#   require "thaum/minitest"
+#
+# Adds assert_snapshot to every Minitest::Test. Snapshots are stored under
+# test/snapshots/<name>.txt (plain text) or .ans (ANSI). On the first run
+# the fixture is written and the assertion passes; subsequent runs compare
+# byte-for-byte. Setting UPDATE_SNAPSHOTS=1 rewrites the fixture in place.
+
+require "fileutils"
+require "minitest/assertions"
+
+module Thaum
+  module SnapshotMatcher
+    SNAPSHOT_ROOT_CANDIDATES = %w[test/snapshots spec/snapshots].freeze
+    ANSI_INDICATOR = "\e["
+
+    def assert_snapshot(actual:, name:)
+      path = Snapshot.path_for(name: name, actual: actual)
+      Snapshot.compare(test: self, actual: actual, path: path, name: name)
+    end
+
+    module_function
+
+    def update_mode? = ENV["UPDATE_SNAPSHOTS"] == "1"
+  end
+
+  # Internal helpers — not part of the public API.
+  module Snapshot
+    module_function
+
+    def path_for(name:, actual:)
+      ext  = actual.include?(SnapshotMatcher::ANSI_INDICATOR) ? "ans" : "txt"
+      root = SnapshotMatcher::SNAPSHOT_ROOT_CANDIDATES.find { |d| Dir.exist?(d) } || "test/snapshots"
+      File.join(root, "#{name}.#{ext}")
+    end
+
+    def compare(test:, actual:, path:, name:)
+      missing = !File.exist?(path)
+      if missing || SnapshotMatcher.update_mode?
+        write(path: path, actual: actual)
+        warn "[Thaum] wrote new snapshot #{name} (#{path})" if missing
+        test.assert(true)
+        return
+      end
+
+      expected = File.read(path)
+      test.assert_equal(
+        expected, actual,
+        "Snapshot \"#{name}\" mismatch (#{path}). " \
+        "Run with UPDATE_SNAPSHOTS=1 to rewrite if the new output is correct."
+      )
+    end
+
+    def write(path:, actual:)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, actual)
+    end
+  end
+end
+
+Minitest::Test.include(Thaum::SnapshotMatcher) if defined?(Minitest::Test)

data/lib/thaum/octagram.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Thaum
+  # A composite container — a distributable component that owns both
+  # layout (Layout DSL) and behavior (Sigil-like handlers). Sits between
+  # its child Sigils and the App in the dispatch chain: when a focused
+  # child Sigil emits, the innermost enclosing Octagram's handler runs
+  # first, and propagates upward only if it calls emit.
+  #
+  # See DECISIONS.md (2026-06-02) for the naming rationale.
+  module Octagram
+    include Layout
+
+    attr_accessor :thaum_app, :handler_parent
+
+    # Marker so the framework's tree-walks can distinguish Octagrams
+    # from plain Layouts (which don't participate in event dispatch).
+    def octagram? = true
+
+    # Optional background — drawn before the Octagram's child sigils.
+    # Override to paint a frame, border, or fill behind the children.
+    def render(canvas:, theme:); end
+
+    # Override to inset the rect the Octagram's children partition into,
+    # so the render hook above is not overwritten by child rendering.
+    # Return a Hash with any of :top, :bottom, :left, :right keys (each
+    # an Integer; missing keys default to 0). For a 1-cell border on all
+    # sides, return { top: 1, bottom: 1, left: 1, right: 1 }.
+    def partition_inset = nil
+
+    # Handlers — same shape as Sigil. Defaults propagate to the handler
+    # parent (the next outer Octagram, or the App).
+    def on_key(event)   = emit(event)
+    def on_mouse(event) = emit(event)
+    def on_paste(event) = emit(event)
+    def on_event(event) = emit(event)
+
+    # Lifecycle — overridable.
+    def on_mount;             end
+    def on_unmount;           end
+    def on_update(context);   end
+    def on_tick(event);       end
+
+    # Propagate an event to this Octagram's handler parent. Mirrors
+    # Sigil#emit: drops framework-internal events and respects the
+    # emit-from-on_update guard.
+    def emit(event)
+      app = @thaum_app or return
+      raise Thaum::EmitFromUpdateError, "emit called from on_update" if app.in_on_update
+
+      if event.is_a?(Thaum::TickEvent) || event.is_a?(Thaum::ResizeEvent)
+        warn "[Thaum] dropping #{event.class} from #{self.class}: " \
+             "framework-internal events cannot be emitted from Sigils or Actions"
+        return
+      end
+
+      (@handler_parent || app).dispatch_from_child(event)
+    end
+
+    # Called by a child Sigil (or nested Octagram) when it emits.
+    def dispatch_from_child(event)
+      Dispatch.invoke_handler(target: self, event: event, label: "#{self.class}##{handler_name_for(event)}")
+    end
+
+    private
+
+    def handler_name_for(event)
+      case event
+      when KeyEvent   then "on_key"
+      when MouseEvent then "on_mouse"
+      when PasteEvent then "on_paste"
+      else                 "on_event"
+      end
+    end
+  end
+end

data/lib/thaum/painter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Paints the App + modal tree into a fresh Buffer and hands it to the
+  # Renderer. Called once per dirty frame from the run loop.
+  module Painter
+    module_function
+
+    def paint(app:, renderer:, cols:, rows:)
+      theme  = app.theme
+      buffer = Rendering::Buffer.new(width: cols, height: rows)
+      paint_node(node: app, buffer: buffer, theme: theme)
+      paint_modal(app: app, buffer: buffer, theme: theme)
+      renderer.render(buffer)
+    end
+
+    # Paint the modal Sigil into a Canvas built from its rect. The Buffer
+    # silently drops out-of-bounds cells, so an overflowing or fully off-
+    # screen modal clips naturally.
+    def paint_modal(app:, buffer:, theme:)
+      sigil = app.modal_sigil or return
+      rect  = app.modal_rect  or return
+      return if rect.width <= 0 || rect.height <= 0
+
+      canvas = Rendering::Canvas.new(buffer: buffer, rect: rect)
+      Thaum.safe_invoke("#{sigil.class}#render") { sigil.render(canvas: canvas, theme: theme) }
+    end
+
+    # Recursive draw walk. Octagrams render their background first (so
+    # children draw on top of it). Plain Layout nodes are pass-through.
+    # Leaf Sigils render into their own rect.
+    def paint_node(node:, buffer:, theme:)
+      if node.is_a?(Octagram) && node.rect
+        canvas = Rendering::Canvas.new(buffer: buffer, rect: node.rect)
+        Thaum.safe_invoke("#{node.class}#render") { node.render(canvas: canvas, theme: theme) }
+      end
+
+      (node.subtree_children || []).each do |child|
+        if child.is_a?(Sigil)
+          r = child.rect or next
+          canvas = Rendering::Canvas.new(buffer: buffer, rect: r)
+          Thaum.safe_invoke("#{child.class}#render") { child.render(canvas: canvas, theme: theme) }
+        elsif child.respond_to?(:subtree_children)
+          paint_node(node: child, buffer: buffer, theme: theme)
+        end
+      end
+    end
+  end
+end

data/lib/thaum/rect.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Thaum
+  Rect = Data.define(:x, :y, :width, :height)
+end