thaum 0.1.0 → 0.2.0

data/lib/thaum/run_loop.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Owns the main run loop: terminal setup, the event queue, mount/draw
+  # pass, suspend/resume choreography, and graceful teardown.
+  module RunLoop
+    module_function
+
+    # Startup entry point. Blocks until app.quit is called. Returns nil.
+    def run(app:, tick: 0.1, threads: 4)
+      terminal   = Terminal.new
+      queue      = Thread::Queue.new
+      capability = Color.detect(ENV)
+      warn "[Thaum] color not supported, rendering without color" if capability == :none
+      renderer   = Rendering::Renderer.new(capability: capability)
+      pool       = Concurrent::FixedThreadPool.new(threads)
+      tick_task  = build_tick_task(queue:, interval: tick)
+
+      Thaum::Action.queue = queue
+      Thaum::Action.pool  = pool
+
+      install_traps(queue:, terminal:)
+      terminal.setup
+      cols, rows = terminal.size
+
+      mount_pass(app:, renderer:, cols:, rows:)
+
+      input_reader = InputReader.new(input: $stdin, queue: queue)
+      input_reader.start
+      tick_task.execute
+
+      event_loop(app:, queue:, terminal:, renderer:, cols:, rows:)
+    ensure
+      tick_task&.shutdown
+      input_reader&.stop
+      shutdown_pool(pool:)
+      Thaum::Action.queue = nil
+      Thaum::Action.pool  = nil
+      terminal&.teardown
+    end
+
+    def event_loop(app:, queue:, terminal:, renderer:, cols:, rows:)
+      until app.quit?
+        event = queue.pop
+
+        if event == :suspend
+          cols, rows = Suspender.suspend(app:, terminal:, queue:)
+          next
+        end
+        # Stray :resume outside a suspend window — ignore.
+        next if event == :resume
+
+        cols, rows = handle_resize(app:, event:, _cols: cols, _rows: rows) if event.is_a?(ResizeEvent)
+
+        Dispatch.from_queue(app:, event:)
+
+        next unless app.dirty?
+
+        app.clear_dirty
+        Thaum.safe_invoke("render") { Painter.paint(app:, renderer:, cols:, rows:) }
+      end
+      [cols, rows]
+    end
+
+    def mount_pass(app:, renderer:, cols:, rows:)
+      app.run_partition(rect: Rect.new(x: 0, y: 0, width: cols, height: rows))
+      app.wire_sigils
+      app.validate_focus_order_tree
+      Thaum.safe_invoke("App#on_mount") { app.on_mount }
+      Tree.walk(app) do |node|
+        next unless node.is_a?(Sigil) || node.is_a?(Octagram)
+
+        Thaum.safe_invoke("#{node.class}#on_mount") { node.on_mount }
+      end
+
+      first = Thaum.safe_invoke("App#initial_focus") { app.initial_focus }
+      if first
+        app.set_initial_focus(first)
+        Thaum.safe_invoke("#{first.class}#on_focus") { first.on_focus }
+      end
+
+      Painter.paint(app:, renderer:, cols:, rows:)
+    end
+
+    def handle_resize(app:, event:, _cols: nil, _rows: nil)
+      cols = event.width
+      rows = event.height
+      Thaum.safe_invoke("App#run_partition") do
+        app.run_partition(rect: Rect.new(x: 0, y: 0, width: cols, height: rows))
+      end
+      Thaum.safe_invoke("App#recompute_modal_rect") { app.recompute_modal_rect }
+      [cols, rows]
+    end
+
+    def build_tick_task(queue:, interval:)
+      last_tick = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      Concurrent::TimerTask.new(execution_interval: interval) do
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        queue.push(TickEvent.new(time: now, delta: now - last_tick))
+        last_tick = now
+      end
+    end
+
+    def install_traps(queue:, terminal:)
+      install_resize_trap(queue:, terminal:)
+      install_suspend_traps(queue:)
+    end
+
+    # Push a ResizeEvent on SIGWINCH.
+    def install_resize_trap(queue:, terminal:)
+      Signal.trap("WINCH") do
+        w, h = terminal.size
+        begin
+          queue.push(ResizeEvent.new(width: w, height: h))
+        rescue ClosedQueueError
+          nil
+        end
+      end
+    end
+
+    # Push :suspend / :resume sentinels onto the main queue from signal
+    # handlers. The actual suspend dance happens in Suspender so the signal
+    # handler stays minimal (signal-handler context has tight restrictions).
+    def install_suspend_traps(queue:)
+      Signal.trap("TSTP") do
+        queue.push(:suspend)
+      rescue ClosedQueueError
+        nil
+      end
+      Signal.trap("CONT") do
+        queue.push(:resume)
+      rescue ClosedQueueError
+        nil
+      end
+    end
+
+    def shutdown_pool(pool:)
+      return unless pool
+
+      pool.shutdown
+      pool.wait_for_termination(1) || pool.kill
+    end
+  end
+
+  # Handles a dequeued :suspend sentinel: tear the terminal down, actually
+  # stop the process, then on resume re-setup, repartition with current
+  # size, and force a re-render. Drains stray sentinels that arrive
+  # between teardown and resume. Internal — not delivered to App handlers
+  # per the spec.
+  module Suspender
+    module_function
+
+    def suspend(app:, terminal:, queue:)
+      Thaum.safe_invoke("Terminal#teardown(suspend)") { terminal.teardown }
+
+      # Reset TSTP to default so kill("TSTP", pid) actually stops us.
+      prev_tstp = Signal.trap("TSTP", "DEFAULT")
+      Process.kill("TSTP", Process.pid)
+      # ── process is stopped here; resumes when shell sends SIGCONT ──
+      Signal.trap("TSTP", prev_tstp)
+
+      drain_until_resume(queue:)
+
+      Thaum.safe_invoke("Terminal#setup(resume)") { terminal.setup }
+      cols, rows = terminal.size
+      Thaum.safe_invoke("App#run_partition(resume)") do
+        app.run_partition(rect: Rect.new(x: 0, y: 0, width: cols, height: rows))
+      end
+      app.request_render
+      [cols, rows]
+    end
+
+    def drain_until_resume(queue:)
+      loop do
+        msg = queue.pop
+        break if msg == :resume
+        # Ignore everything else during the suspended window — we
+        # re-render from scratch on resume anyway.
+      end
+    end
+  end
+end

data/lib/thaum/seq.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Sequences for terminal control and input.
+  module Seq
+    # Mode toggles
+    ALT_SCREEN_ON       = "\e[?1049h"
+    ALT_SCREEN_OFF      = "\e[?1049l"
+    CURSOR_HIDE         = "\e[?25l"
+    CURSOR_SHOW         = "\e[?25h"
+    BRACKETED_PASTE_ON  = "\e[?2004h"
+    BRACKETED_PASTE_OFF = "\e[?2004l"
+    SGR_MOUSE_ON        = "\e[?1006h"
+    SGR_MOUSE_OFF       = "\e[?1006l"
+    CELL_MOTION_ON      = "\e[?1002h"
+    CELL_MOTION_OFF     = "\e[?1002l"
+    SYNC_BEGIN          = "\e[?2026h"
+    SYNC_END            = "\e[?2026l"
+
+    # Select Graphic Rendition (SGR) attributes
+    RESET     = "\e[0m"
+    BOLD      = "\e[1m"
+    DIM       = "\e[2m"
+    ITALIC    = "\e[3m"
+    UNDERLINE = "\e[4m"
+
+    # Select Graphic Rendition (SGR) named color codes
+    FG = {
+      black: 30, red: 31, green: 32, yellow: 33,
+      blue: 34, magenta: 35, cyan: 36, white: 37,
+      bright_black: 90, bright_red: 91, bright_green: 92, bright_yellow: 93,
+      bright_blue: 94, bright_magenta: 95, bright_cyan: 96, bright_white: 97,
+      default: 39
+    }.freeze
+
+    BG = {
+      black: 40, red: 41, green: 42, yellow: 43,
+      blue: 44, magenta: 45, cyan: 46, white: 47,
+      bright_black: 100, bright_red: 101, bright_green: 102, bright_yellow: 103,
+      bright_blue: 104, bright_magenta: 105, bright_cyan: 106, bright_white: 107,
+      default: 49
+    }.freeze
+
+    # Control Sequence Introducer (CSI) input sequences (\e[ + final byte)
+    CSI_UP        = "\e[A"
+    CSI_DOWN      = "\e[B"
+    CSI_RIGHT     = "\e[C"
+    CSI_LEFT      = "\e[D"
+    CSI_HOME      = "\e[H"
+    CSI_END       = "\e[F"
+    CSI_SHIFT_TAB = "\e[Z"
+
+    # Single Shift 3 (SS3) input sequences (\eO + final byte) — VT100/application cursor mode
+    SS3_F1    = "\eOP"
+    SS3_F2    = "\eOQ"
+    SS3_F3    = "\eOR"
+    SS3_F4    = "\eOS"
+    SS3_HOME  = "\eOH"
+    SS3_END   = "\eOF"
+    SS3_UP    = "\eOA"
+    SS3_DOWN  = "\eOB"
+    SS3_RIGHT = "\eOC"
+    SS3_LEFT  = "\eOD"
+
+    # Tilde input sequences (\e[ + code + ~)
+    # F6-F8 skip 16 because some terminals use it for a modifier variant.
+    TILDE_HOME      = "\e[1~"
+    TILDE_INSERT    = "\e[2~"
+    TILDE_DELETE    = "\e[3~"
+    TILDE_END       = "\e[4~"
+    TILDE_PAGE_UP   = "\e[5~"
+    TILDE_PAGE_DOWN = "\e[6~"
+    TILDE_F1        = "\e[11~"
+    TILDE_F2        = "\e[12~"
+    TILDE_F3        = "\e[13~"
+    TILDE_F4        = "\e[14~"
+    TILDE_F5        = "\e[15~"
+    TILDE_F6        = "\e[17~"
+    TILDE_F7        = "\e[18~"
+    TILDE_F8        = "\e[19~"
+    TILDE_F9        = "\e[20~"
+    TILDE_F10       = "\e[21~"
+    TILDE_F11       = "\e[23~"
+    TILDE_F12       = "\e[24~"
+
+    # Dynamic sequences
+    def self.cursor_pos(x:, y:) = "\e[#{y};#{x}H"
+    def self.color(code) = "\e[#{code}m"
+    def self.truecolor(base:, r:, g:, b:) = "\e[#{base};2;#{r};#{g};#{b}m"
+  end
+end

data/lib/thaum/sigil.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Sigil
+    attr_accessor :rect, :thaum_app, :handler_parent
+
+    # The safe-nav `&.` makes `focused_sigil` nil when no app is set; nil.equal?(self) is false.
+    def focused?    = @thaum_app&.focused_sigil.equal?(self)
+    def focusable?  = true
+    def request_render = @thaum_app&.request_render
+
+    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
+
+    # Rendering — override in subclass
+    def render(canvas:, theme:); end
+
+    # Terminal event handlers — defaults propagate via emit
+    def on_key(event)   = emit(event)
+    def on_mouse(event) = emit(event)
+    def on_paste(event) = emit(event)
+
+    # Lifecycle — override for side effects
+    def on_mount;             end
+    def on_unmount;           end
+    def on_focus;             end
+    def on_blur;              end
+    def on_update(context);   end
+    def on_tick(event);       end
+  end
+end

data/lib/thaum/sigils/button.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Thaum
+  class Button
+    include Sigil
+
+    PressedEvent = Thaum::Event.define(:label)
+
+    attr_reader :label
+
+    def initialize(label:, disabled: false)
+      @label    = label
+      @disabled = disabled
+    end
+
+    def disabled?  = @disabled
+    def focusable? = !@disabled
+
+    def on_key(event)
+      case event.key
+      when :enter, " " then activate
+      else                  emit event
+      end
+    end
+
+    def render(canvas:, theme:)
+      fg, bg = colors(theme)
+      canvas.fill(bg: bg) if bg
+      canvas.text(content: @label, fg: fg, bg: bg, align: :center)
+    end
+
+    private
+
+    def colors(theme)
+      return [theme.dim, nil] if disabled?
+      return [theme.accent, theme.pressed] if focused?
+
+      [theme.fg, nil]
+    end
+
+    def activate
+      return if disabled?
+
+      emit PressedEvent.new(label: @label)
+    end
+  end
+end

data/lib/thaum/sigils/checkbox.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Tri-state boolean: unchecked, checked, indeterminate. Space (or Enter)
+  # toggles between unchecked and checked; indeterminate is set
+  # programmatically and any user toggle clears it. Emits Checkbox::ChangedEvent
+  # with the new :checked value.
+  class Checkbox
+    include Sigil
+
+    ChangedEvent = Thaum::Event.define(:checked)
+
+    attr_reader :checked, :indeterminate
+    attr_accessor :label
+
+    def initialize(checked: false, indeterminate: false, label: nil)
+      @checked       = checked
+      @indeterminate = indeterminate
+      @label         = label
+    end
+
+    def checked?       = @checked
+    def indeterminate? = @indeterminate
+
+    def indeterminate=(value)
+      @indeterminate = value
+      @checked = false if value
+    end
+
+    def on_key(event)
+      case event.key
+      when " ", :enter then toggle
+      else emit(event)
+      end
+    end
+
+    def render(canvas:, theme:)
+      canvas.fill(bg: theme.bg)
+      fg = focused? ? theme.accent : theme.fg
+      canvas.text(content: "#{mark} #{@label}".rstrip, fg: fg, bg: theme.bg)
+    end
+
+    private
+
+    def toggle
+      @indeterminate = false
+      @checked = !checked?
+      emit ChangedEvent.new(checked: checked?)
+    end
+
+    def mark
+      return "[-]" if indeterminate?
+
+      checked? ? "[X]" : "[ ]"
+    end
+  end
+end

data/lib/thaum/sigils/progress_bar.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Horizontal progress bar. Two modes:
+  # - determinate (default): `value` is 0.0..1.0, fills proportionally.
+  # - indeterminate: a fixed-width block walks across the bar on each tick.
+  # Non-focusable.
+  class ProgressBar
+    include Sigil
+
+    INDETERMINATE_BLOCK_WIDTH = 6
+    INDETERMINATE_INTERVAL    = 0.1
+
+    attr_accessor :value
+    attr_reader   :indeterminate
+
+    def initialize(value: 0.0, indeterminate: false)
+      @value         = value
+      @indeterminate = indeterminate
+      @offset        = 0
+      @elapsed       = 0.0
+    end
+
+    def focusable? = false
+    def indeterminate? = @indeterminate
+
+    def on_tick(event)
+      return unless indeterminate?
+
+      @elapsed += event.delta
+      advanced = false
+      while @elapsed >= INDETERMINATE_INTERVAL
+        @elapsed -= INDETERMINATE_INTERVAL
+        @offset += 1
+        advanced = true
+      end
+      request_render if advanced
+    end
+
+    def render(canvas:, theme:)
+      canvas.fill(bg: theme.bg)
+      if indeterminate?
+        render_indeterminate(canvas: canvas,
+                             theme: theme)
+      else
+        render_determinate(canvas: canvas, theme: theme)
+      end
+    end
+
+    private
+
+    def render_determinate(canvas:, theme:)
+      filled = (@value.clamp(0.0, 1.0) * canvas.width).round
+      canvas.fill(bg: theme.accent, width: filled) if filled.positive?
+    end
+
+    def render_indeterminate(canvas:, theme:)
+      span  = canvas.width + INDETERMINATE_BLOCK_WIDTH
+      start = (@offset % span) - INDETERMINATE_BLOCK_WIDTH
+      x     = [start, 0].max
+      w     = [INDETERMINATE_BLOCK_WIDTH - (x - start), canvas.width - x].min
+      canvas.fill(bg: theme.accent, x: x, width: w) if w.positive?
+    end
+  end
+end

data/lib/thaum/sigils/scroll_view.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Thaum
+  # A scrollable viewport over a list of pre-rendered text rows.
+  #
+  # This is the row-list variant — apps supply an Array of String rows
+  # (one row per element) and ScrollView handles vertical + horizontal
+  # scrolling. Long rows are sliced by display columns, so wide chars
+  # (CJK, emoji) scroll cleanly.
+  class ScrollView
+    include Sigil
+
+    WHEEL_STEP = 3
+
+    attr_reader :offset_y, :offset_x, :rows
+
+    def initialize(rows: [])
+      @rows     = rows
+      @offset_y = 0
+      @offset_x = 0
+    end
+
+    def rows=(new_rows)
+      @rows = new_rows
+      @offset_y = @offset_y.clamp(0, [rows.length - 1, 0].max)
+      @offset_y = 0 if rows.empty?
+      @offset_x = @offset_x.clamp(0, max_x)
+    end
+
+    def on_key(event)
+      case event.key
+      when :up        then @offset_y = [@offset_y - 1, 0].max
+      when :down      then @offset_y = [@offset_y + 1, max_offset_y_estimate].min
+      when :page_up   then @offset_y = [@offset_y - 10, 0].max
+      when :page_down then @offset_y = [@offset_y + 10, max_offset_y_estimate].min
+      when :home      then @offset_y = 0
+      when :end       then @offset_y = max_offset_y_estimate
+      when :left      then @offset_x = [@offset_x - 1, 0].max
+      when :right     then @offset_x = [@offset_x + 1, max_x].min
+      else                 emit event
+      end
+    end
+
+    def on_mouse(event)
+      case event.button
+      when :wheel_up   then @offset_y = [@offset_y - WHEEL_STEP, 0].max
+      when :wheel_down then @offset_y = [@offset_y + WHEEL_STEP, max_offset_y_estimate].min
+      else                  emit event
+      end
+    end
+
+    def render(canvas:, theme:)
+      canvas.fill(bg: theme.bg)
+
+      # Per-canvas vertical clamp: don't scroll past the last page.
+      max_offset = [rows.length - canvas.height, 0].max
+      @offset_y = max_offset if @offset_y > max_offset
+
+      canvas.height.times do |row_idx|
+        file_row = @offset_y + row_idx
+        text     = rows[file_row]
+        break if text.nil?
+
+        sliced = slice_by_columns(str: text, start_col: @offset_x, max_cols: canvas.width)
+        canvas.row(row_idx).text(content: sliced, fg: theme.fg)
+      end
+
+      draw_indicators(canvas: canvas, theme: theme)
+    end
+
+    private
+
+    def max_offset_y_estimate
+      [rows.length - 1, 0].max
+    end
+
+    def max_x
+      return 0 if rows.empty?
+
+      widest = rows.map(&:display_width).max
+      [widest - 1, 0].max
+    end
+
+    # Skip `start_col` display columns of input, then collect up to `max_cols`
+    # columns of output. Wide chars (display_width == 2) that straddle either
+    # edge are dropped to keep alignment honest.
+    def slice_by_columns(str:, start_col:, max_cols:)
+      return "" if str.nil? || str.empty?
+
+      result = +""
+      col    = 0
+      str.each_char do |ch|
+        w = ch.display_width
+        if col >= start_col
+          break if (col - start_col) + w > max_cols
+
+          result << ch
+        end
+        col += w
+      end
+      result
+    end
+
+    def draw_indicators(canvas:, theme:)
+      return if canvas.width.zero? || canvas.height.zero?
+
+      canvas.text(content: "▲", x: canvas.width - 1, y: 0, fg: theme.dim) if @offset_y.positive?
+
+      bottom_visible_row = @offset_y + canvas.height
+      return unless bottom_visible_row < rows.length
+
+      canvas.text(content: "▼", x: canvas.width - 1, y: canvas.height - 1, fg: theme.dim)
+    end
+  end
+end

data/lib/thaum/sigils/select.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Thaum
+  class Select
+    include Sigil
+
+    SelectedEvent = Thaum::Event.define(:index, :item)
+
+    attr_reader :items, :cursor
+
+    def initialize(items:, cursor: 0)
+      @items  = items
+      @cursor = cursor
+    end
+
+    def current = items[cursor]
+
+    def on_key(event)
+      case event.key
+      when :down  then @cursor = [cursor + 1, items.length - 1].min if items.any?
+      when :up    then @cursor = [cursor - 1, 0].max
+      when :enter then emit_selected
+      else emit(event)
+      end
+    end
+
+    def render(canvas:, theme:)
+      offset = scroll_offset(canvas.height)
+      visible_range = offset...(offset + canvas.height)
+
+      visible_range.each_with_index do |item_idx, row_idx|
+        item = items[item_idx] or next
+        row  = canvas.row(row_idx) or break
+
+        bg = item_idx == cursor ? theme.selection : theme.bg
+        fg = item_idx == cursor ? theme.selection_fg : theme.fg
+        row.fill(bg: bg)
+        row.text(content: item.to_s, fg: fg, bg: bg)
+      end
+    end
+
+    private
+
+    def emit_selected
+      return if items.empty?
+
+      emit SelectedEvent.new(index: cursor, item: items[cursor])
+    end
+
+    def scroll_offset(height)
+      return 0 if cursor < height
+
+      cursor - height + 1
+    end
+  end
+end

data/lib/thaum/sigils/spinner.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Animated activity indicator. Advances one frame per `interval` seconds,
+  # driven by tick deltas (not wall clock — works with whatever tick rate
+  # the app runs at). Non-focusable.
+  class Spinner
+    include Sigil
+
+    DEFAULT_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+    attr_reader :frame, :frames, :interval
+
+    def initialize(frames: DEFAULT_FRAMES, interval: 0.1)
+      @frames    = frames
+      @interval  = interval
+      @frame     = 0
+      @elapsed   = 0.0
+    end
+
+    def focusable? = false
+
+    def on_tick(event)
+      @elapsed += event.delta
+      advanced = false
+      while @elapsed >= @interval
+        @elapsed -= @interval
+        @frame = (@frame + 1) % @frames.length
+        advanced = true
+      end
+      request_render if advanced
+    end
+
+    def render(canvas:, theme:)
+      canvas.fill(bg: theme.bg)
+      canvas.text(content: @frames[@frame], fg: theme.accent, bg: theme.bg)
+    end
+  end
+end