thaum 0.1.0 → 0.2.0

data/lib/thaum/rendering/box_drawing.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Segment-bitmap merging for Unicode box-drawing characters.
+  #
+  # Each known glyph is encoded as four directional segment weights:
+  # [up, down, left, right]. Weights are 0 (none), 1 (light), 2 (heavy),
+  # 3 (double). When two glyphs are merged the result's weights are the
+  # per-direction max of the inputs, looked up back to a canonical glyph.
+  #
+  # Coverage:
+  # - Light family (U+2500-U+2503, U+250C-U+253C, half-stubs)
+  # - Heavy family (U+2501, U+2503, U+250F, U+2513, U+2517, U+251B,
+  #   U+2523, U+252B, U+2533, U+253B, U+254B, U+2578-U+257B)
+  # - Mixed light/heavy (U+250D-U+250F minus 250C, U+2511-U+2513 minus
+  #   2510, etc. — full U+250C-U+254B region)
+  # - Double family (U+2550, U+2551, U+2554, U+2557, U+255A, U+255D,
+  #   U+2560, U+2563, U+2566, U+2569, U+256C)
+  # - Mixed light/double (U+2552, U+2553, U+2555, U+2556, U+2558,
+  #   U+2559, U+255B, U+255C, U+255E-U+256B)
+  # - Rounded corners (U+256D-U+2570) — share segments with non-rounded
+  #   light corners; merges return the non-rounded canonical glyph.
+  #
+  # Heavy + double in different directions has no Unicode glyph; merge
+  # falls through to "incoming wins."
+  module Rendering
+    module BoxDrawing
+      # char => [up, down, left, right] weights (0=none, 1=light, 2=heavy, 3=double)
+      SEGMENTS = {
+        # ----- Pure light --------------------------------------------------
+        "─" => [0, 0, 1, 1],
+        "│" => [1, 1, 0, 0],
+        "┌" => [0, 1, 0, 1],
+        "┐" => [0, 1, 1, 0],
+        "└" => [1, 0, 0, 1],
+        "┘" => [1, 0, 1, 0],
+        "├" => [1, 1, 0, 1],
+        "┤" => [1, 1, 1, 0],
+        "┬" => [0, 1, 1, 1],
+        "┴" => [1, 0, 1, 1],
+        "┼" => [1, 1, 1, 1],
+        "╴" => [0, 0, 1, 0],
+        "╵" => [1, 0, 0, 0],
+        "╶" => [0, 0, 0, 1],
+        "╷" => [0, 1, 0, 0],
+        # Rounded corners share signatures with the non-rounded corners.
+        "╭" => [0, 1, 0, 1],
+        "╮" => [0, 1, 1, 0],
+        "╰" => [1, 0, 0, 1],
+        "╯" => [1, 0, 1, 0],
+
+        # ----- Pure heavy --------------------------------------------------
+        "━" => [0, 0, 2, 2],
+        "┃" => [2, 2, 0, 0],
+        "┏" => [0, 2, 0, 2],
+        "┓" => [0, 2, 2, 0],
+        "┗" => [2, 0, 0, 2],
+        "┛" => [2, 0, 2, 0],
+        "┣" => [2, 2, 0, 2],
+        "┫" => [2, 2, 2, 0],
+        "┳" => [0, 2, 2, 2],
+        "┻" => [2, 0, 2, 2],
+        "╋" => [2, 2, 2, 2],
+        "╸" => [0, 0, 2, 0],
+        "╹" => [2, 0, 0, 0],
+        "╺" => [0, 0, 0, 2],
+        "╻" => [0, 2, 0, 0],
+
+        # ----- Mixed light/heavy corners (U+250D-U+251B minus pures) -------
+        "┍" => [0, 1, 0, 2], # d light, r heavy
+        "┎" => [0, 2, 0, 1], # d heavy, r light
+        "┑" => [0, 1, 2, 0], # d light, l heavy
+        "┒" => [0, 2, 1, 0], # d heavy, l light
+        "┕" => [1, 0, 0, 2], # u light, r heavy
+        "┖" => [2, 0, 0, 1], # u heavy, r light
+        "┙" => [1, 0, 2, 0], # u light, l heavy
+        "┚" => [2, 0, 1, 0], # u heavy, l light
+
+        # ----- Mixed light/heavy left-tees (U+251D-U+2522) -----------------
+        "┝" => [1, 1, 0, 2],
+        "┞" => [2, 1, 0, 1],
+        "┟" => [1, 2, 0, 1],
+        "┠" => [2, 2, 0, 1],
+        "┡" => [2, 1, 0, 2],
+        "┢" => [1, 2, 0, 2],
+
+        # ----- Mixed light/heavy right-tees (U+2525-U+252A) ----------------
+        "┥" => [1, 1, 2, 0],
+        "┦" => [2, 1, 1, 0],
+        "┧" => [1, 2, 1, 0],
+        "┨" => [2, 2, 1, 0],
+        "┩" => [2, 1, 2, 0],
+        "┪" => [1, 2, 2, 0],
+
+        # ----- Mixed light/heavy top-tees (U+252D-U+2532) ------------------
+        "┭" => [0, 1, 2, 1],
+        "┮" => [0, 1, 1, 2],
+        "┯" => [0, 1, 2, 2],
+        "┰" => [0, 2, 1, 1],
+        "┱" => [0, 2, 2, 1],
+        "┲" => [0, 2, 1, 2],
+
+        # ----- Mixed light/heavy bottom-tees (U+2535-U+253A) ---------------
+        "┵" => [1, 0, 2, 1],
+        "┶" => [1, 0, 1, 2],
+        "┷" => [1, 0, 2, 2],
+        "┸" => [2, 0, 1, 1],
+        "┹" => [2, 0, 2, 1],
+        "┺" => [2, 0, 1, 2],
+
+        # ----- Mixed light/heavy crosses (U+253D-U+254A) -------------------
+        "┽" => [1, 1, 2, 1],
+        "┾" => [1, 1, 1, 2],
+        "┿" => [1, 1, 2, 2],
+        "╀" => [2, 1, 1, 1],
+        "╁" => [1, 2, 1, 1],
+        "╂" => [2, 2, 1, 1],
+        "╃" => [2, 1, 2, 1],
+        "╄" => [2, 1, 1, 2],
+        "╅" => [1, 2, 2, 1],
+        "╆" => [1, 2, 1, 2],
+        "╇" => [2, 1, 2, 2],
+        "╈" => [1, 2, 2, 2],
+        "╉" => [2, 2, 2, 1],
+        "╊" => [2, 2, 1, 2],
+
+        # ----- Pure double -------------------------------------------------
+        "═" => [0, 0, 3, 3],
+        "║" => [3, 3, 0, 0],
+        "╔" => [0, 3, 0, 3],
+        "╗" => [0, 3, 3, 0],
+        "╚" => [3, 0, 0, 3],
+        "╝" => [3, 0, 3, 0],
+        "╠" => [3, 3, 0, 3],
+        "╣" => [3, 3, 3, 0],
+        "╦" => [0, 3, 3, 3],
+        "╩" => [3, 0, 3, 3],
+        "╬" => [3, 3, 3, 3],
+
+        # ----- Mixed light/double corners (U+2552-U+2559, U+255B-U+255C) ---
+        "╒" => [0, 1, 0, 3], # d light, r double
+        "╓" => [0, 3, 0, 1], # d double, r light
+        "╕" => [0, 1, 3, 0],
+        "╖" => [0, 3, 1, 0],
+        "╘" => [1, 0, 0, 3],
+        "╙" => [3, 0, 0, 1],
+        "╛" => [1, 0, 3, 0],
+        "╜" => [3, 0, 1, 0],
+
+        # ----- Mixed light/double tees -------------------------------------
+        "╞" => [1, 1, 0, 3],
+        "╟" => [3, 3, 0, 1],
+        "╡" => [1, 1, 3, 0],
+        "╢" => [3, 3, 1, 0],
+        "╤" => [0, 1, 3, 3],
+        "╥" => [0, 3, 1, 1],
+        "╧" => [1, 0, 3, 3],
+        "╨" => [3, 0, 1, 1],
+        "╪" => [1, 1, 3, 3],
+        "╫" => [3, 3, 1, 1]
+      }.freeze
+
+      # [up, down, left, right] => canonical glyph (non-rounded; light-form
+      # preferred where a signature is ambiguous, e.g. the rounded corners).
+      GLYPH_FROM_SEGMENTS = SEGMENTS.each_with_object({}) do |(glyph, sig), out|
+        # Skip rounded corners — their signatures collide with the non-
+        # rounded light corners, which should win as the canonical form.
+        next if %w[╭ ╮ ╰ ╯].include?(glyph)
+
+        out[sig] ||= glyph
+      end.freeze
+
+      # Merge two glyphs. Returns the union glyph if both are known
+      # box-drawing chars and the resulting signature has a Unicode glyph;
+      # otherwise the incoming char (new-write-wins).
+      def self.merge(existing:, incoming:)
+        seg_a = SEGMENTS[existing]
+        seg_b = SEGMENTS[incoming]
+        return incoming unless seg_a && seg_b
+
+        merged = [seg_a, seg_b].transpose.map(&:max)
+        GLYPH_FROM_SEGMENTS[merged] || incoming
+      end
+    end
+  end
+end

data/lib/thaum/rendering/buffer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Thaum
+  # A 2D grid of Cells, addressed by (x:, y:) with (0, 0) at the top-left.
+  module Rendering
+    class Buffer
+      attr_reader :width, :height
+      attr_accessor :cursor
+
+      def initialize(width:, height:)
+        @width  = width
+        @height = height
+        @cursor = nil # [x, y] in buffer coords, or nil to hide
+        # Stored row-major: @cells[y][x]. Public API takes (x:, y:) per convention,
+        # but rows-of-columns makes row iteration and row_text natural.
+        @cells = Array.new(height) { Array.new(width) { Cell.new } }
+      end
+
+      def cell(x:, y:)
+        @cells[y][x]
+      end
+
+      def row_text(y:)
+        @cells[y].map(&:char).join
+      end
+
+      def set(x:, y:, char:, style: nil)
+        return unless cover?(x:, y:)
+
+        current = @cells[y][x]
+        # When both the existing and incoming chars are box-drawing glyphs,
+        # merge their segments so adjacent borders form correct junctions.
+        # For any other pair, the new char wins (existing behavior).
+        resolved = BoxDrawing.merge(existing: current.char, incoming: char)
+        @cells[y][x] = current.with(char: resolved, style: style || current.style)
+      end
+
+      def cover?(x:, y:)
+        x >= 0 && x < @width && y >= 0 && y < @height
+      end
+
+      # One line per row, plain text — no ANSI sequences. Use for content
+      # and layout assertions in snapshot tests.
+      def to_text_snapshot
+        (0...@height).map { |y| row_text(y: y) }.join("\n")
+      end
+
+      # One line per row, with inline ANSI style transitions. Each row resets
+      # style at the end so rows are independent. Use for visual assertions
+      # including color.
+      def to_ansi_snapshot
+        (0...@height).map { |y| ansi_row(y) }.join("\n")
+      end
+
+      private
+
+      def ansi_row(y)
+        out = +""
+        prev = nil
+        @cells[y].each do |cell|
+          out << style_diff(prev: prev, style: cell.style)
+          out << cell.char
+          prev = cell.style
+        end
+        out << Seq::RESET unless prev.nil? || prev.empty?
+        out
+      end
+
+      def style_diff(prev:, style:)
+        return "" if prev == style
+
+        out = +""
+        out << Seq::RESET if prev && !prev.empty?
+        out << Seq::BOLD      if style.bold
+        out << Seq::DIM       if style.dim
+        out << Seq::ITALIC    if style.italic
+        out << Seq::UNDERLINE if style.underline
+        out << Color.to_escape(style.fg, capability: :truecolor, base: 38) if style.fg
+        out << Color.to_escape(style.bg, capability: :truecolor, base: 48) if style.bg
+        out
+      end
+    end
+  end
+end

data/lib/thaum/rendering/canvas.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Thaum
+  # A rectangular view into a Buffer that translates local coordinates to buffer coordinates.
+  module Rendering
+    class Canvas
+      BORDERS = {
+        single:  { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│" },
+        rounded: { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│" },
+        double:  { tl: "╔", tr: "╗", bl: "╚", br: "╝", h: "═", v: "║" },
+        thick:   { tl: "┏", tr: "┓", bl: "┗", br: "┛", h: "━", v: "┃" },
+        # Dashed + dotted reuse the light corner glyphs — Unicode does not
+        # define dashed corners. The horizontal/vertical runs use 2-dash
+        # (dashed) or 4-dash (dotted, denser-looking) light glyphs.
+        dashed:  { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "╌", v: "╎" },
+        dotted:  { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "┈", v: "┊" },
+        ascii:   { tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|" }
+      }.freeze
+
+      attr_reader :rect
+
+      def initialize(buffer:, rect:)
+        @buffer = buffer
+        @rect   = rect
+      end
+
+      def x      = @rect.x
+      def y      = @rect.y
+      def width  = @rect.width
+      def height = @rect.height
+
+      def fill(char: " ", fg: nil, bg: nil, x: 0, y: 0, width: @rect.width, height: @rect.height)
+        height.times do |dy|
+          width.times do |dx|
+            cx = @rect.x + x + dx
+            cy = @rect.y + y + dy
+            @buffer.set(x: cx, y: cy, char: char, style: blend_style(cx: cx, cy: cy, fg: fg, bg: bg))
+          end
+        end
+      end
+
+      def text(content:, fg: nil, bg: nil, x: 0, y: 0, align: :left, wrap: :none, **_opts)
+        if content.is_a?(Array)
+          draw_styled_runs(runs: content, x: x, y: y, align: align)
+        else
+          draw_string_text(content: content.to_s, x: x, y: y, align: align, wrap: wrap, fg: fg, bg: bg)
+        end
+      end
+
+      def cursor(x:, y:)
+        @buffer.cursor = [@rect.x + x, @rect.y + y]
+      end
+
+      # Draws a box around the perimeter and returns the inset canvas (w-2 × h-2)
+      # so callers can render contents inside. style is one of BORDERS' keys.
+      def border(fg: nil, bg: nil, style: :single)
+        chars = BORDERS.fetch(style) { raise ArgumentError, "unknown border style: #{style.inspect}" }
+        return inset(1) if @rect.width < 2 || @rect.height < 2
+
+        draw_border(chars: chars, fg: fg, bg: bg)
+        inset(1)
+      end
+
+      def measure(content:, wrap: :none, width: @rect.width)
+        lines = wrap == :none ? [content.to_s] : wrap_lines(text: content.to_s, width: width)
+        { width: lines.map(&:display_width).max || 0, height: lines.size }
+      end
+
+      def row(n)
+        return nil if n.negative? || n >= @rect.height
+
+        child_canvas(Rect.new(x: @rect.x, y: @rect.y + n, width: @rect.width, height: 1))
+      end
+
+      # rect is in local coordinates (relative to this canvas's origin).
+      def sub(rect:)
+        child_canvas(Rect.new(x: @rect.x + rect.x, y: @rect.y + rect.y, width: rect.width, height: rect.height))
+      end
+
+      def top(n)
+        child_canvas(Rect.new(x: @rect.x, y: @rect.y, width: @rect.width, height: [n, @rect.height].min))
+      end
+
+      def bottom(n)
+        child_canvas(Rect.new(x: @rect.x, y: @rect.y + @rect.height - n, width: @rect.width,
+                              height: [n, @rect.height].min))
+      end
+
+      def left(n)
+        child_canvas(Rect.new(x: @rect.x, y: @rect.y, width: [n, @rect.width].min, height: @rect.height))
+      end
+
+      def right(n)
+        child_canvas(Rect.new(x: @rect.x + @rect.width - n, y: @rect.y, width: [n, @rect.width].min,
+                              height: @rect.height))
+      end
+
+      def inset(n_or_opts)
+        if n_or_opts.is_a?(Integer)
+          n = n_or_opts
+          child_canvas(Rect.new(x: @rect.x + n, y: @rect.y + n, width: @rect.width - (n * 2),
+                                height: @rect.height - (n * 2)))
+        else
+          t = n_or_opts[:top]    || 0
+          r = n_or_opts[:right]  || 0
+          b = n_or_opts[:bottom] || 0
+          l = n_or_opts[:left]   || 0
+          child_canvas(Rect.new(x: @rect.x + l, y: @rect.y + t, width: @rect.width - l - r,
+                                height: @rect.height - t - b))
+        end
+      end
+
+      private
+
+      def child_canvas(rect) = Canvas.new(buffer: @buffer, rect: rect)
+
+      def draw_border(chars:, fg:, bg:)
+        w = @rect.width
+        h = @rect.height
+        top = "#{chars[:tl]}#{chars[:h] * (w - 2)}#{chars[:tr]}"
+        bot = "#{chars[:bl]}#{chars[:h] * (w - 2)}#{chars[:br]}"
+        text(content: top, y: 0,     fg: fg, bg: bg)
+        text(content: bot, y: h - 1, fg: fg, bg: bg)
+        (1..(h - 2)).each do |row_y|
+          text(content: chars[:v], x: 0,     y: row_y, fg: fg, bg: bg)
+          text(content: chars[:v], x: w - 1, y: row_y, fg: fg, bg: bg)
+        end
+      end
+
+      def draw_string_text(content:, x:, y:, align:, wrap:, fg:, bg:)
+        lines = wrap == :none ? [content] : wrap_lines(text: content, width: @rect.width - x)
+        right_edge = @rect.x + @rect.width
+
+        lines.each_with_index do |line, dy|
+          row_y = y + dy
+          break if row_y >= @rect.height
+
+          bx = align_offset(line: line, available_width: @rect.width, align: align, x: x)
+          line.each_char do |char|
+            w = char.display_width
+            break if bx + w > right_edge
+
+            cy    = @rect.y + row_y
+            style = blend_style(cx: bx, cy: cy, fg: fg, bg: bg)
+            @buffer.set(x: bx,     y: cy, char: char, style: style)
+            @buffer.set(x: bx + 1, y: cy, char: "",   style: style) if w == 2
+            bx += w
+          end
+        end
+      end
+
+      # Compose a Style by overlaying explicitly-set fg/bg onto the cell's
+      # current style. nil means "inherit." This makes layered draws compose:
+      # fill bg, then text fg, keeps bg. Per DECISIONS.md 2026-06-10.
+      def blend_style(cx:, cy:, fg:, bg:)
+        return nil if fg.nil? && bg.nil?
+        return Style.new(fg: fg, bg: bg) unless @buffer.cover?(x: cx, y: cy)
+
+        existing = @buffer.cell(x: cx, y: cy).style
+        existing.with(fg: fg || existing.fg, bg: bg || existing.bg)
+      end
+
+      def draw_styled_runs(runs:, x:, y:, align:)
+        return if y >= @rect.height
+
+        total_w = runs.sum { |str, _style| str.display_width }
+        bx = case align
+             when :center then @rect.x + [(@rect.width - total_w) / 2, 0].max
+             when :right  then @rect.x + [@rect.width - total_w, 0].max
+             else              @rect.x + x
+             end
+        row_y = @rect.y + y
+        right_edge = @rect.x + @rect.width
+
+        runs.each do |str, style|
+          str.each_char do |char|
+            w = char.display_width
+            break if bx + w > right_edge
+
+            @buffer.set(x: bx, y: row_y, char: char, style: style)
+            @buffer.set(x: bx + 1, y: row_y, char: "", style: style) if w == 2
+            bx += w
+          end
+          break if bx >= right_edge
+        end
+      end
+
+      def align_offset(line:, available_width:, align:, x:)
+        case align
+        when :center then @rect.x + [(available_width - line.display_width) / 2, 0].max
+        when :right  then @rect.x + [available_width - line.display_width, 0].max
+        else              @rect.x + x # :left
+        end
+      end
+
+      def wrap_lines(text:, width:)
+        return [text] if width <= 0
+
+        lines = []
+        text.each_line(chomp: true) do |para|
+          words = para.split
+          line  = +""
+          words.each do |word|
+            if line.empty?
+              line << word
+            elsif line.display_width + 1 + word.display_width <= width
+              line << " " << word
+            else
+              lines << line
+              line = +word
+            end
+          end
+          lines << line
+        end
+        lines.empty? ? [""] : lines
+      end
+    end
+  end
+end

data/lib/thaum/rendering/cell.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Rendering
+    Cell = Data.define(:char, :style) do
+      def initialize(char: " ", style: Style.new)
+        super
+      end
+    end
+  end
+end

data/lib/thaum/rendering/renderer.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Thaum
+  # Renders a Buffer to a terminal output stream using ANSI escape sequences.
+  module Rendering
+    class Renderer
+      def initialize(output: $stdout, capability: :truecolor)
+        @output = output
+        @out = +""
+        @prev_buffer = nil
+        @capability = capability
+      end
+
+      def render(buffer)
+        @out.clear
+        full_redraw = @prev_buffer.nil? ||
+                      @prev_buffer.width != buffer.width ||
+                      @prev_buffer.height != buffer.height
+        prev_style = nil
+        any_writes = false
+
+        buffer.height.times do |y|
+          if full_redraw
+            first_x = 0
+            last_x  = buffer.width - 1
+          else
+            first_x, last_x = dirty_span(buffer: buffer, y: y)
+            next unless first_x
+          end
+
+          # Emit the full span between the first and last dirty cells. Skipping
+          # unchanged cells inside the span and jumping the cursor over them
+          # would leave their on-screen state untouched, which is only safe if
+          # the terminal really mirrors prev_buffer at those positions. When
+          # consecutive themes share slot values, that assumption produces the
+          # bug where swatches keep stale pixels across transitions.
+          @out << Seq.cursor_pos(x: first_x + 1, y: y + 1)
+          (first_x..last_x).each do |x|
+            cell = buffer.cell(x: x, y: y)
+            emit_style(style: cell.style, prev: prev_style)
+            @out << cell.char
+            prev_style = cell.style
+          end
+          any_writes = true
+        end
+
+        @out << Seq::RESET if any_writes
+
+        emit_cursor(buffer: buffer, full_redraw: full_redraw)
+
+        @prev_buffer = buffer
+        return if @out.empty?
+
+        @output.write(Seq::SYNC_BEGIN, @out, Seq::SYNC_END)
+        @output.flush
+      end
+
+      private
+
+      def dirty_span(buffer:, y:)
+        first = nil
+        last  = nil
+        buffer.width.times do |x|
+          next if buffer.cell(x: x, y: y) == @prev_buffer.cell(x: x, y: y)
+
+          first ||= x
+          last = x
+        end
+        [first, last]
+      end
+
+      def emit_cursor(buffer:, full_redraw:)
+        prev = @prev_buffer&.cursor
+        curr = buffer.cursor
+        return unless full_redraw || prev != curr
+
+        if curr
+          @out << Seq.cursor_pos(x: curr[0] + 1, y: curr[1] + 1) << Seq::CURSOR_SHOW
+        else
+          @out << Seq::CURSOR_HIDE
+        end
+      end
+
+      def emit_style(style:, prev:)
+        return if prev && style == prev
+
+        @out << Seq::RESET if prev && !prev.empty?
+
+        @out << Seq::BOLD      if style.bold
+        @out << Seq::DIM       if style.dim
+        @out << Seq::ITALIC    if style.italic
+        @out << Seq::UNDERLINE if style.underline
+        @out << Color.to_escape(style.fg, capability: @capability, base: 38) if style.fg
+        @out << Color.to_escape(style.bg, capability: @capability, base: 48) if style.bg
+      end
+    end
+  end
+end

data/lib/thaum/rendering/style.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Thaum
+  module Rendering
+    Style = Data.define(:fg, :bg, :bold, :italic, :underline, :dim) do
+      def initialize(fg: nil, bg: nil, bold: false, italic: false, underline: false, dim: false)
+        super
+      end
+
+      def empty? = !fg && !bg && !bold && !italic && !underline && !dim
+    end
+  end
+end