thaum 0.1.0 → 0.2.0

data/lib/thaum/escape_parser.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Parses raw terminal input bytes into KeyEvent / PasteEvent objects.
+  #
+  # The parser is stateful: a paste payload that spans multiple parse()
+  # calls (chunked reads from the InputReader) is accumulated across calls
+  # and emitted as a single PasteEvent once the closing \e[201~ marker
+  # arrives. The class-level .parse helper makes a fresh instance for
+  # one-shot use.
+  class EscapeParser
+    PASTE_START = "\e[200~"
+    PASTE_END   = "\e[201~"
+
+    # Ground state byte codes
+    CR = 0x0d     # Carriage return
+    LF = 0x0a     # Line feed
+    TAB = 0x09    # Tab
+    DEL = 0x7f    # Delete
+    BS = 0x08     # Backspace
+    CTRL_START = 0x01
+    CTRL_END = 0x1a
+    PRINTABLE_START = 0x20
+    PRINTABLE_END = 0x7e
+
+    # Escape sequence byte codes
+    ESC = 0x1b
+    SGR_MOUSE_MARKER = 0x3c  # '<' for SGR mouse introducer
+    SGR_MOUSE_PRESS = 0x4d   # 'M'
+    SGR_MOUSE_RELEASE = 0x6d # 'm'
+    CSI_FINAL_START = 0x40
+    CSI_FINAL_END = 0x7e
+    SGR_DIGIT_START = 0x30   # '0'
+    SGR_DIGIT_END = 0x39     # '9'
+    SGR_SEP = 0x3b           # ';'
+
+    def self.parse(input) = new.parse(input)
+
+    def initialize
+      @paste_buf = nil
+    end
+
+    def parse(input)
+      events = []
+      i = 0
+      while i < input.bytesize
+        if @paste_buf
+          i = collect_paste(input: input, i: i, events: events)
+        elsif input.getbyte(i) == ESC
+          i = parse_at_escape(input: input, i: i, events: events)
+        else
+          event = parse_ground(input.getbyte(i))
+          events << event if event
+          i += 1
+        end
+      end
+      events
+    end
+
+    private
+
+    # Inside a paste — look for PASTE_END from position i. Returns the
+    # index to resume parsing from (just past PASTE_END, or bytesize if
+    # the terminator hasn't arrived yet).
+    def collect_paste(input:, i:, events:)
+      end_idx = input.byteindex(PASTE_END, i)
+      if end_idx
+        @paste_buf << input.byteslice(i, end_idx - i)
+        events << PasteEvent.new(text: @paste_buf)
+        @paste_buf = nil
+        end_idx + PASTE_END.bytesize
+      else
+        @paste_buf << input.byteslice(i, input.bytesize - i)
+        input.bytesize
+      end
+    end
+
+    # ESC at position i. Either paste-start, paste-end (stray — ignored as
+    # a bare :escape), or a normal escape sequence. Returns the next index.
+    def parse_at_escape(input:, i:, events:)
+      if input.byteslice(i, PASTE_START.bytesize) == PASTE_START
+        @paste_buf = +""
+        return i + PASTE_START.bytesize
+      end
+
+      event, consumed = parse_escape_at(input: input, i: i)
+      events << event if event
+      i + consumed
+    end
+
+    # Returns [KeyEvent, bytes_consumed] starting from position i (the ESC byte).
+    def parse_escape_at(input:, i:)
+      next_pos = i + 1
+      return [KeyEvent.new(key: :escape), 1] if next_pos >= input.bytesize
+
+      case input.getbyte(next_pos)
+      when Seq::CSI_UP.getbyte(1) then parse_csi_at(input: input, i: i)   # Control Sequence Introducer (CSI): 0x5b [
+      when Seq::SS3_UP.getbyte(1) then parse_ss3_at(input: input, i: i)   # Single Shift 3 (SS3): 0x4f O
+      else
+        # Alt + whatever the next ground byte produces
+        event = parse_ground(input.getbyte(next_pos))
+        if event
+          [KeyEvent.new(key: event.key, alt: true), 2]
+        else
+          [KeyEvent.new(key: :escape), 1]
+        end
+      end
+    end
+
+    # i points to ESC; input[i+1] == '[' (Control Sequence Introducer).
+    def parse_csi_at(input:, i:)
+      # SGR mouse: ESC [ < Cb ; Cx ; Cy (M|m)
+      return parse_sgr_mouse_at(input: input, i: i) if input.getbyte(i + 2) == SGR_MOUSE_MARKER
+
+      j = i + 2
+      params_start = j
+      while j < input.bytesize
+        b = input.getbyte(j)
+        if b.between?(CSI_FINAL_START, CSI_FINAL_END)
+          params = input.byteslice(params_start, j - params_start)
+          final  = b.chr
+          return [decode_csi(params: params, final: final), j - i + 1]
+        end
+        j += 1
+      end
+      [KeyEvent.new(key: :escape), 1]
+    end
+
+    # i points to ESC; input[i+1] == '['; input[i+2] == '<'. Scan to the
+    # final byte (M or m) and decode an SGR mouse event.
+    def parse_sgr_mouse_at(input:, i:)
+      j = i + 3
+      params_start = j
+      while j < input.bytesize
+        b = input.getbyte(j)
+        if [SGR_MOUSE_PRESS, SGR_MOUSE_RELEASE].include?(b)
+          params = input.byteslice(params_start, j - params_start)
+          final  = b.chr
+          # Well-formed SGR sequence — consume it whether or not we emit.
+          # decode_sgr_mouse returns nil for events we intentionally drop.
+          return [decode_sgr_mouse(params: params, final: final), j - i + 1]
+        end
+        # SGR mouse params are digits and ';'. Bail out if we see anything else.
+        break unless b.between?(SGR_DIGIT_START, SGR_DIGIT_END) || b == SGR_SEP
+
+        j += 1
+      end
+      [KeyEvent.new(key: :escape), 1]
+    end
+
+    def decode_sgr_mouse(params:, final:)
+      parts = params.split(";")
+      return nil if parts.size != 3
+
+      cb = parts[0].to_i
+      cx = parts[1].to_i
+      cy = parts[2].to_i
+
+      shift = cb.anybits?(4)
+      alt   = cb.anybits?(8)
+      ctrl  = cb.anybits?(16)
+      motion = cb.anybits?(32)
+      wheel  = cb.anybits?(64)
+      btn_bits = cb & 0b11
+
+      button, action = button_and_action(btn_bits: btn_bits, final: final, wheel: wheel, motion: motion)
+      return nil if action == :invalid
+
+      # SGR coords are 1-based; convert to 0-based.
+      ax = cx - 1
+      ay = cy - 1
+      MouseEvent.new(button: button, action: action, abs_x: ax, abs_y: ay,
+                     shift: shift, alt: alt, ctrl: ctrl)
+    end
+
+    def button_from_bits(btn_bits)
+      case btn_bits
+      when 0 then :left
+      when 1 then :middle
+      when 2 then :right
+      end
+    end
+
+    def button_and_action(btn_bits:, final:, wheel:, motion:)
+      if wheel
+        button = btn_bits.zero? ? :wheel_up : :wheel_down
+        [button, :scroll]
+      elsif final == "m"
+        # Release. SGR encodes the released button in the low bits;
+        # value 3 historically means "unknown" — leave button nil.
+        [button_from_bits(btn_bits), :release]
+      elsif motion
+        # Under button-event tracking (1002), motion arrives only while a
+        # button is held → :drag. btn_bits == 3 (no button) shouldn't occur;
+        # drop it if it does.
+        button = button_from_bits(btn_bits)
+        button ? [button, :drag] : [nil, :invalid]
+      else
+        button = button_from_bits(btn_bits)
+        return [nil, :invalid] unless button # btn_bits == 3 with no motion bit is unspecified
+
+        [button, :press]
+      end
+    end
+
+    # i points to ESC; input[i+1] == 'O' (Single Shift 3).
+    def parse_ss3_at(input:, i:)
+      pos = i + 2
+      return [KeyEvent.new(key: :escape), 1] if pos >= input.bytesize
+
+      key = Keys::SS3[input.getbyte(pos).chr]
+      key ? [KeyEvent.new(key: key), 3] : [KeyEvent.new(key: :escape), 1]
+    end
+
+    def decode_csi(params:, final:)
+      case final
+      when Seq::CSI_SHIFT_TAB[-1]
+        KeyEvent.new(key: :tab, shift: true)
+      when "~"
+        parts = params.split(";")
+        key   = Keys::TILDE[parts[0].to_i]
+        return KeyEvent.new(key: :escape) unless key
+
+        mod = parts[1]&.to_i
+        mod ? KeyEvent.new(key: key, **modifier_flags(mod)) : KeyEvent.new(key: key)
+      else
+        key = Keys::CSI[final]
+        return KeyEvent.new(key: :escape) unless key
+
+        if params.include?(";")
+          mod = params.split(";")[1]&.to_i
+          mod ? KeyEvent.new(key: key, **modifier_flags(mod)) : KeyEvent.new(key: key)
+        else
+          KeyEvent.new(key: key)
+        end
+      end
+    end
+
+    def parse_ground(byte)
+      case byte
+      when CR, LF
+        KeyEvent.new(key: :enter)
+      when TAB
+        KeyEvent.new(key: :tab)
+      when DEL, BS
+        KeyEvent.new(key: :backspace)
+      when CTRL_START..CTRL_END
+        KeyEvent.new(key: (byte + 96).chr, ctrl: true)
+      when PRINTABLE_START..PRINTABLE_END
+        KeyEvent.new(key: byte.chr)
+      end
+    end
+
+    # xterm modifier encoding: param = bitflags + 1
+    # bit 0 = shift, bit 1 = alt, bit 2 = ctrl
+    def modifier_flags(mod)
+      flags = mod - 1
+      {
+        shift: flags.anybits?(1),
+        alt: flags.anybits?(2),
+        ctrl: flags.anybits?(4)
+      }
+    end
+  end
+end

data/lib/thaum/event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Event
+    def self.define(*attrs, &block)
+      Data.define(*attrs) do
+        include Thaum::Event
+
+        class_eval(&block) if block
+      end
+    end
+  end
+end

data/lib/thaum/events.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Framework-internal event types pushed onto the main queue by the input
+# reader, signal traps, and the tick timer. KeyEvent has its own file
+# because it carries modifier predicates.
+module Thaum
+  PasteEvent  = Event.define(:text)
+  ResizeEvent = Event.define(:width, :height)
+  TickEvent   = Event.define(:time, :delta)
+
+  # SGR mouse event. Actions: :press / :release / :drag / :scroll.
+  # Scroll direction is folded into `button` (:wheel_up / :wheel_down).
+  # Modifier booleans (shift/alt/ctrl) come from the SGR Cb bits.
+  #
+  # `x`/`y` are canvas-relative to the receiving Sigil and are set by the
+  # dispatcher right before invoking on_mouse. `abs_x`/`abs_y` are the
+  # terminal-absolute coordinates and are always populated.
+  MouseEvent = Event.define(:button, :action, :x, :y, :abs_x, :abs_y, :shift, :alt, :ctrl) do
+    def initialize(button:, action:, abs_x:, abs_y:, x: abs_x, y: abs_y,
+                   shift: false, alt: false, ctrl: false)
+      super
+    end
+
+    def shift? = shift
+    def alt?   = alt
+    def ctrl?  = ctrl
+  end
+end

data/lib/thaum/hit_test.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Mouse hit testing for the layout tree and modals.
+  module HitTest
+    module_function
+
+    # Walk every leaf Sigil with an allocated rect, return the LAST one
+    # whose rect contains (abs_x, abs_y). Last-in-render-order wins on
+    # overlap, matching the draw walk in Painter.
+    def hit(app:, abs_x:, abs_y:)
+      hit = nil
+      Tree.walk(app) do |node|
+        next unless node.is_a?(Sigil)
+
+        rect = node.rect or next
+        next unless point_in_rect?(x: abs_x, y: abs_y, rect: rect)
+
+        hit = node
+      end
+      hit
+    end
+
+    def point_in_rect?(x:, y:, rect:)
+      x >= rect.x && x < rect.x + rect.width && y >= rect.y && y < rect.y + rect.height
+    end
+  end
+end

data/lib/thaum/input_reader.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Reads raw bytes from an input stream in a background thread and pushes KeyEvents onto a queue.
+  class InputReader
+    ESCAPE_TIMEOUT = 0.05 # seconds to wait after a bare \e before treating it as Escape
+
+    def initialize(input:, queue:, parser: EscapeParser.new)
+      @input  = input
+      @queue  = queue
+      @parser = parser
+      @thread = nil
+    end
+
+    def start
+      @thread = Thread.new { run }
+    end
+
+    def stop
+      @thread&.join(1)
+      @thread = nil
+    end
+
+    def alive?
+      @thread&.alive? || false
+    end
+
+    private
+
+    def run
+      loop do
+        bytes = read_chunk
+        @parser.parse(bytes).each { |event| @queue.push(event) }
+      end
+    rescue IOError
+      # input closed — exit cleanly
+    end
+
+    def read_chunk
+      bytes = @input.readpartial(1024)
+      # If bytes end with a bare ESC, wait briefly — it may be the start of a sequence.
+      bytes += @input.readpartial(1024) if bytes.end_with?("\e") && @input.wait_readable(ESCAPE_TIMEOUT)
+      bytes
+    end
+  end
+end

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/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 Concerns::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