merminal 0.1.0

data/lib/merminal/flowchart.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "strscan"
+require "cgi"
+
+module Merminal
+  # Flowchart grammar and Scene layout.
+  module Flowchart
+    Node = Data.define(:id, :label, :shape, :classes, :source_pos)
+    Edge = Data.define(:id, :from, :to, :label, :stroke, :start_marker, :end_marker, :minlen, :source_pos)
+    Subgraph = Data.define(:id, :label, :node_ids, :parent)
+    Diagram = Data.define(:direction, :nodes, :edges, :subgraphs, :styles)
+
+    SHAPES = [
+      ["(((", ")))", :double_circle], ["((", "))", :circle], ["([", "])", :stadium],
+      ["[(", ")]", :database], ["[[", "]]", :subroutine], ["{{", "}}", :hexagon],
+      ["(", ")", :rounded], ["{", "}", :decision], ["[", "]", :rectangle], [">", "]", :flag]
+    ].freeze
+    EDGE_PATTERN = /(?:<|o|x)?(?:-{2,}|-\.+-|={2,}|~{3,})(?:>|o|x)?/
+    DIRECTIONS = %w[TB TD BT LR RL].freeze
+
+    def self.diagram_type = :flowchart
+    def self.keywords = %w[flowchart flowchart-v2 flowchart-elk graph]
+
+    def self.parse(source)
+      Parser.new(source).parse
+    end
+
+    def self.layout(ast, **options)
+      Layout.new(ast, **options).scene
+    end
+
+    # Statement parser; scanner offsets are used in diagnostics.
+    class Parser
+      def initialize(source)
+        @source = source
+        @nodes = {}
+        @edges = []
+        @subgraphs = []
+        @styles = {}
+        @diagnostics = []
+        @stack = []
+        @direction = :TB
+      end
+
+      def parse
+        header, *rest = @source.lines
+        header_parts = header.to_s.split(";", 2)
+        words = header_parts[0].to_s.split
+        @direction = words[1].to_sym if DIRECTIONS.include?(words[1])
+        split_statements(header_parts[1].to_s).each { |statement| parse_statement(statement.strip, @source.line_map.first || 1) } if header_parts[1]
+        rest.each_with_index do |line, index|
+          split_statements(line.to_s).each { |statement| parse_statement(statement.strip, @source.line_map[index + 1] || 1) }
+        end
+        group_ids = @subgraphs.map(&:id)
+        @edges.each do |edge|
+          from = group_ids.include?(edge.from) ? edge.from : nil
+          to = group_ids.include?(edge.to) ? edge.to : nil
+          @styles["group_edge:#{edge.id}"] = [from, to] if from || to
+        end
+        @subgraphs.each do |group|
+          representative = group.node_ids.first
+          next unless representative
+
+          @edges.map! do |edge|
+            edge.with(from: edge.from == group.id ? representative : edge.from,
+                      to: edge.to == group.id ? representative : edge.to)
+          end
+          @nodes.delete(group.id) unless group.node_ids.include?(group.id)
+        end
+        @diagnostics << Diagnostic.new(severity: :error, message: "unclosed subgraph", line: @source.line_map.last || 1, column: 1, length: 1) unless @stack.empty?
+        [Diagram.new(direction: @direction, nodes: @nodes.values.freeze, edges: @edges.freeze,
+                     subgraphs: @subgraphs.freeze, styles: @styles.freeze), @diagnostics.freeze]
+      end
+
+      def split_statements(line)
+        statements = []
+        current = +""
+        quote = nil
+        depth = 0
+        line.each_char do |char|
+          if quote
+            quote = nil if char == quote
+          elsif char == '"' || char == "'"
+            quote = char
+          elsif ["(", "[", "{"].include?(char)
+            depth += 1
+          elsif [")", "]", "}"].include?(char)
+            depth -= 1 if depth.positive?
+          elsif char == ";" && depth.zero?
+            statements << current
+            current = +""
+            next
+          end
+          current << char
+        end
+        statements << current
+      end
+
+      def parse_statement(statement, line)
+        return if statement.empty?
+
+        case statement
+        when /\Adirection\s+(TB|TD|BT|LR|RL)\z/
+          if @stack.any?
+            info("subgraph direction ignored", line)
+          else
+            @direction = Regexp.last_match(1).to_sym
+          end
+        when /\Asubgraph\s+(.+)\z/
+          name = Regexp.last_match(1).strip
+          id, label = name =~ /\A([^\[]+)\[(.*)\]\z/ ? [Regexp.last_match(1).strip, Regexp.last_match(2)] : [name, name]
+          @subgraphs << Subgraph.new(id: id, label: label, node_ids: [], parent: @stack.last)
+          @stack << id
+        when "end"
+          @stack.pop || error("unexpected end", line)
+        when /\Astyle\s+(\S+)\s+(.+)\z/
+          @styles[Regexp.last_match(1)] = Regexp.last_match(2)
+        when /\AclassDef\s+(\S+)\s+(.+)\z/
+          @styles["class:#{Regexp.last_match(1)}"] = Regexp.last_match(2)
+        when /\Aclass\s+([\w,.-]+)\s+(\S+)\z/
+          ids, name = Regexp.last_match.captures
+          ids.split(",").each do |id|
+            previous = @nodes[id]
+            @nodes[id] = previous.with(classes: (previous.classes + [name]).uniq.freeze) if previous
+          end
+        when /\AlinkStyle\s+(\S+)\s+(.+)\z/
+          @styles["link:#{Regexp.last_match(1)}"] = Regexp.last_match(2)
+        when /\Aclick\b/
+          info("click ignored", line)
+        else
+          parse_chain(statement, line)
+        end
+      end
+
+      def parse_chain(statement, line)
+        scanner = StringScanner.new(statement)
+        previous = parse_group(scanner, line)
+        return unless previous
+
+        until scanner.eos?
+          scanner.skip(/\s*/)
+          operator = scanner.scan(EDGE_PATTERN)
+          unless operator
+            error("unexpected input", line, scanner.pos + 1)
+            break
+          end
+          label = nil
+          scanner.skip(/\s*/)
+          if scanner.scan(/\|/)
+            label = scanner.scan_until(/\|/)&.chop
+            error("unclosed edge label", line, scanner.pos + 1) unless label
+          elsif operator == "--" && scanner.scan(/(.+?)\s+-->/)
+            label = scanner[1]
+            operator = "-->"
+          end
+          following = parse_group(scanner, line)
+          break unless following
+
+          previous.product(following).each do |from, to|
+            @edges << Edge.new(id: @edges.length, from: from, to: to, label: label,
+                               stroke: operator.include?("~") ? :invisible : operator.include?("=") ? :heavy : operator.include?(".") ? :dotted : :light,
+                               start_marker: marker(operator[0]), end_marker: marker(operator[-1]),
+                               minlen: [operator.count("-=.") - 1, 1].max, source_pos: [line, scanner.pos])
+          end
+          previous = following
+        end
+      end
+
+      def parse_group(scanner, line)
+        ids = []
+        loop do
+          scanner.skip(/\s*/)
+          id = scanner.scan(/[[:alnum:]_](?:[[:alnum:]_.]|-(?![-.=>~]))*/)
+          unless id
+            error("expected node", line, scanner.pos + 1)
+            return nil
+          end
+          shape, label = parse_shape(scanner, line)
+          previous = @nodes[id]
+          classes = []
+          while scanner.scan(/:::/)
+            name = scanner.scan(/[[:alnum:]_-]+/)
+            classes << name if name
+          end
+          label ||= previous&.label || id
+          label = CGI.unescapeHTML(label.gsub(/<br\s*\/?\s*>/i, "\n").gsub(/<[^>]+>/, ""))
+          if previous && shape
+            info("node #{id} redefined", line)
+          end
+          @nodes[id] = Node.new(id: id, label: shape ? label : previous&.label || label,
+                                shape: shape || previous&.shape || :rectangle,
+                                classes: ((previous&.classes || []) + classes).uniq.freeze, source_pos: [line, scanner.pos])
+          @subgraphs.each { |group| group.node_ids << id if @stack.include?(group.id) } if @stack.any?
+          ids << id
+          scanner.skip(/\s*/)
+          break unless scanner.scan(/&/)
+        end
+        ids
+      end
+
+      def parse_shape(scanner, line)
+        if scanner.scan(/@\{/)
+          value = scanner.scan_until(/\}/)
+          unless value
+            error("unclosed shape object", line, scanner.pos + 1)
+            return [:rectangle, ""]
+          end
+          name = value[/shape\s*:\s*([\w-]+)/, 1]
+          shape = { "rect" => :rectangle, "rounded" => :rounded, "diamond" => :decision,
+                    "hex" => :hexagon, "circle" => :circle, "stadium" => :stadium,
+                    "cyl" => :database, "subproc" => :subroutine }[name]
+          info("unknown shape #{name}", line) unless shape
+          return [shape || :rectangle, nil]
+        end
+        if scanner.peek(2) == "[/" || scanner.peek(2) == "[\\"
+          value = scan_shape_content(scanner, "]", escape_closer: false)
+          unless value
+            error("unclosed node shape", line, scanner.pos + 1)
+            return [:parallelogram, ""]
+          end
+          first = value[1]
+          last = value[-1]
+          shape = first == last ? :parallelogram : :trapezoid
+          return [shape, value[2...-1].delete_prefix('"').delete_suffix('"')]
+        end
+        opener, closer, shape = SHAPES.find { |start, _, _| scanner.peek(start.length) == start }
+        return [nil, nil] unless opener
+
+        scanner.pos += opener.length
+        value = scan_shape_content(scanner, closer)
+        unless value
+          error("unclosed node shape", line, scanner.pos + 1)
+          return [shape, ""]
+        end
+        [shape, value.delete_prefix('"').delete_suffix('"')]
+      end
+
+      def scan_shape_content(scanner, closer, escape_closer: true)
+        result = +""
+        quote = nil
+        escaped = false
+        until scanner.eos?
+          if !quote && (!escaped || !escape_closer) && scanner.peek(closer.bytesize) == closer
+            scanner.pos += closer.bytesize
+            return result
+          end
+
+          char = scanner.getch
+          if escaped
+            escaped = false
+          elsif char == "\\"
+            escaped = true
+          elsif quote == char
+            quote = nil
+          elsif !quote && (char == '"' || char == "'")
+            quote = char
+          end
+          result << char
+        end
+        nil
+      end
+
+      def marker(char)
+        { ">" => :arrow, "<" => :arrow, "o" => :circle, "x" => :cross }[char]
+      end
+
+      def error(message, line, column = 1)
+        @diagnostics << Diagnostic.new(severity: :error, message: message, line: line, column: column, length: 1)
+      end
+
+      def info(message, line)
+        @diagnostics << Diagnostic.new(severity: :info, message: message, line: line, column: 1, length: 1)
+      end
+    end
+  end
+end
+
+require_relative "flowchart/layout"

data/lib/merminal/markdown.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Merminal
+  # One Mermaid fence extracted from a Markdown document.
+  MarkdownBlock = Data.define(:source, :line) do
+    def render(**options)
+      Merminal.render(source, **options)
+    end
+  end
+
+  module Markdown
+    module_function
+
+    def blocks(markdown)
+      result = []
+      fence = nil
+      start = nil
+      content = []
+      markdown.to_s.each_line.with_index(1) do |line, number|
+        if fence
+          if line.match?(/\A\s*#{Regexp.escape(fence[0])}{#{fence.length},}\s*\z/)
+            result << MarkdownBlock.new(source: content.join, line: start) if start
+            fence = nil
+            start = nil
+            content = []
+          else
+            content << line if start
+          end
+        elsif line =~ /\A\s*(`{3,}|~{3,})([^`~]*)\z/
+          fence = Regexp.last_match(1)
+          start = number + 1 if Regexp.last_match(2).strip == "mermaid"
+        end
+      end
+      result.freeze
+    end
+  end
+end

data/lib/merminal/output.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "shareable"
+
+module Merminal
+  # Plain and ANSI terminal output.
+  module Output
+    THEMES = Shareable.make({
+      default: { node_border: 39, node_text: 255, edge: 110, edge_label: 222, marker: 203,
+                 container_border: 103, container_title: 222, axis: 244, axis_label: 250,
+                 series_1: 39, series_2: 203, emphasis: 229, muted: 244 },
+      mono: {},
+      high_contrast: { node_border: 15, node_text: 15, edge: 15, edge_label: 11, marker: 9,
+                       axis: 15, axis_label: 15, series_1: 11, series_2: 13, emphasis: 15 },
+      solarized: { node_border: 37, node_text: 230, edge: 66, edge_label: 136, marker: 160,
+                   axis: 244, axis_label: 187, series_1: 37, series_2: 166, emphasis: 230 }
+    })
+    BASIC = Shareable.make([[0, 0, 0], [128, 0, 0], [0, 128, 0], [128, 128, 0],
+                                    [0, 0, 128], [128, 0, 128], [0, 128, 128], [192, 192, 192],
+                                    [128, 128, 128], [255, 0, 0], [0, 255, 0], [255, 255, 0],
+                                    [0, 0, 255], [255, 0, 255], [0, 255, 255], [255, 255, 255]])
+
+    module_function
+
+    def render(grid, charset: :unicode, color: false, theme: :default)
+      raise ArgumentError, "unknown theme: #{theme}" unless THEMES.key?(theme.to_sym)
+
+      colored = color == true || color == :always || (color == :auto && $stdout.tty?)
+      colored = false if ENV.key?("NO_COLOR") && !ENV.key?("FORCE_COLOR")
+      colored = true if ENV.key?("FORCE_COLOR") && color != false && color != :never
+      grid.lines(charset: charset).map do |cells|
+        last = cells.rindex { |char, _| char != " " }
+        cells = last ? cells.take(last + 1) : []
+        next "" if cells.empty?
+
+        colored ? ansi_line(cells, THEMES.fetch(theme.to_sym), color_depth) : cells.map(&:first).join
+      end.drop_while(&:empty?).reverse.drop_while(&:empty?).reverse.join("\n")
+    end
+
+    def ansi_line(cells, theme, depth)
+      current = nil
+      result = +""
+      cells.each do |char, role, background|
+        next_style = [role.to_s.start_with?("fg:") ? role.to_s.delete_prefix("fg:") : theme[role], background]
+        if next_style != current
+          result << "\e[0m" if current&.any?
+          codes = []
+          codes << color_code(next_style[0], depth) if next_style[0]
+          codes << color_code(next_style[1], depth, foreground: false) if next_style[1]
+          result << "\e[#{codes.join(';')}m" unless codes.empty?
+          current = next_style
+        end
+        result << char
+      end
+      result << "\e[0m" if current&.any?
+      result
+    end
+
+    def color_depth
+      return :truecolor if %w[truecolor 24bit].include?(ENV["COLORTERM"])
+      return :color256 if ENV["TERM"].to_s.include?("256color")
+
+      :color16
+    end
+
+    def color_code(value, depth, foreground: true)
+      prefix = foreground ? 38 : 48
+      rgb = value.is_a?(Integer) ? rgb256(value) : hex_rgb(value)
+      return "#{prefix};2;#{rgb.join(';')}" if depth == :truecolor
+      if depth == :color256
+        index = value.is_a?(Integer) ? value : (16..255).min_by { |candidate| rgb256(candidate).zip(rgb).sum { |a, b| (a - b)**2 } }
+        return "#{prefix};5;#{index}"
+      end
+
+      nearest = BASIC.each_with_index.min_by { |candidate, _| candidate.zip(rgb).sum { |a, b| (a - b)**2 } }.last
+      (nearest < 8 ? (foreground ? 30 : 40) + nearest : (foreground ? 90 : 100) + nearest - 8).to_s
+    end
+
+    def hex_rgb(value)
+      hex = value.to_s.delete_prefix("#")
+      hex = hex.chars.map { |char| char * 2 }.join if hex.length == 3
+      [0, 2, 4].map { |offset| hex[offset, 2].to_i(16) }
+    end
+
+    def rgb256(index)
+      return BASIC[index] if index < 16
+      return Array.new(3, 8 + (index - 232) * 10) if index >= 232
+
+      cube = index - 16
+      [cube / 36, cube / 6 % 6, cube % 6].map { |value| value.zero? ? 0 : 55 + value * 40 }
+    end
+  end
+end

data/lib/merminal/raster/box_drawing_table.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# Unicode 17.0.0; generated from UnicodeData.txt.
+
+module Merminal::Raster
+  BOX_DRAWING = Merminal::Shareable.make({"0001" => "╴", "0002" => "╸", "0010" => "╷", "0011" => "┐", "0012" => "┑", "0013" => "╕", "0020" => "╻", "0021" => "┒", "0022" => "┓", "0031" => "╖", "0033" => "╗", "0100" => "╶", "0101" => "─", "0102" => "╾", "0110" => "┌", "0111" => "┬", "0112" => "┭", "0120" => "┎", "0121" => "┰", "0122" => "┱", "0130" => "╓", "0131" => "╥", "0200" => "╺", "0201" => "╼", "0202" => "━", "0210" => "┍", "0211" => "┮", "0212" => "┯", "0220" => "┏", "0221" => "┲", "0222" => "┳", "0303" => "═", "0310" => "╒", "0313" => "╤", "0330" => "╔", "0333" => "╦", "1000" => "╵", "1001" => "┘", "1002" => "┙", "1003" => "╛", "1010" => "│", "1011" => "┤", "1012" => "┥", "1013" => "╡", "1020" => "╽", "1021" => "┧", "1022" => "┪", "1100" => "└", "1101" => "┴", "1102" => "┵", "1110" => "├", "1111" => "┼", "1112" => "┽", "1120" => "┟", "1121" => "╁", "1122" => "╅", "1200" => "┕", "1201" => "┶", "1202" => "┷", "1210" => "┝", "1211" => "┾", "1212" => "┿", "1220" => "┢", "1221" => "╆", "1222" => "╈", "1300" => "╘", "1303" => "╧", "1310" => "╞", "1313" => "╪", "2000" => "╹", "2001" => "┚", "2002" => "┛", "2010" => "╿", "2011" => "┦", "2012" => "┩", "2020" => "┃", "2021" => "┨", "2022" => "┫", "2100" => "┖", "2101" => "┸", "2102" => "┹", "2110" => "┞", "2111" => "╀", "2112" => "╃", "2120" => "┠", "2121" => "╂", "2122" => "╉", "2200" => "┗", "2201" => "┺", "2202" => "┻", "2210" => "┡", "2211" => "╄", "2212" => "╇", "2220" => "┣", "2221" => "╊", "2222" => "╋", "3001" => "╜", "3003" => "╝", "3030" => "║", "3031" => "╢", "3033" => "╣", "3100" => "╙", "3101" => "╨", "3130" => "╟", "3131" => "╫", "3300" => "╚", "3303" => "╩", "3330" => "╠", "3333" => "╬"})
+end

data/lib/merminal/raster.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "shareable"
+
+module Merminal
+  # Converts Scene primitives to terminal cells.
+  module Raster
+    require_relative "raster/box_drawing_table"
+
+    Cell = Struct.new(:char, :arms, :weights, :owners, :role, :background, :protected, :continuation, :weight, :pattern, :rounded, keyword_init: true)
+    ARM = { n: 1, e: 2, s: 4, w: 8 }.freeze
+    INDEX = { n: 0, e: 1, s: 2, w: 3 }.freeze
+    WEIGHT = { light: 1, heavy: 2, double: 3 }.freeze
+    OPPOSITE = { n: :s, e: :w, s: :n, w: :e }.freeze
+    ROUNDED = { 3 => "╰", 6 => "╭", 9 => "╯", 12 => "╮" }.freeze
+
+    # Mutable raster grid. Bounds errors signal a layout bug.
+    class Grid
+      attr_reader :width, :height, :rows
+
+      def initialize(width, height, crossings: :plain)
+        @width, @height = width, height
+        @crossings = crossings
+        @rows = Array.new(height) { Array.new(width) { Cell.new(char: " ", arms: 0, weights: [0, 0, 0, 0]) } }
+      end
+
+      def at(x, y)
+        raise RangeError, "drawing outside Scene: #{x},#{y}" unless x.between?(0, width - 1) && y.between?(0, height - 1)
+
+        rows[y][x]
+      end
+
+      def line(points, stroke, role, protect: false, rounded: false, owner: nil)
+        points.each_cons(2) do |(x1, y1), (x2, y2)|
+          raise ArgumentError, "diagonal line" unless x1 == x2 || y1 == y2
+
+          dx = x2 <=> x1
+          dy = y2 <=> y1
+          x, y = x1, y1
+          until x == x2 && y == y2
+            nx, ny = x + dx, y + dy
+            direction = dx.positive? ? :e : dx.negative? ? :w : dy.positive? ? :s : :n
+            add_arm(x, y, direction, stroke, role, protect, rounded, owner)
+            add_arm(nx, ny, OPPOSITE.fetch(direction), stroke, role, protect, rounded, owner)
+            x, y = nx, ny
+          end
+        end
+      end
+
+      def add_arm(x, y, direction, stroke, role, protect, rounded, owner)
+        cell = at(x, y)
+        return if cell.continuation
+
+        cell.arms |= ARM.fetch(direction)
+        if owner
+          cell.owners ||= {}
+          (cell.owners[direction] ||= []) << owner
+        end
+        index = INDEX.fetch(direction)
+        cell.weights[index] = [cell.weights[index], WEIGHT.fetch(stroke.weight)].max
+        cell.role = role if !cell.protected || protect
+        cell.protected ||= protect
+        cell.weight = stroke.weight if !cell.weight || cell.weight == :light
+        cell.pattern = stroke.pattern
+        cell.rounded ||= rounded
+      end
+
+      def put(x, y, char, role, protect: false, ambiguous_width: 1)
+        cells = Text.width(char, ambiguous_width: ambiguous_width)
+        return if cells.zero?
+
+        cell = at(x, y)
+        raise RangeError, "drawing across Scene edge" if cells == 2 && x == width - 1
+        return if cell.protected && !protect
+
+        cell.char = char
+        cell.arms = 0
+        cell.role = role
+        cell.protected ||= protect
+        if cells == 2
+          follower = at(x + 1, y)
+          follower.char = ""
+          follower.arms = 0
+          follower.continuation = true
+          follower.role = role
+        end
+      end
+
+      def fill(rect, background)
+        rect.y.upto(rect.y + rect.height - 1) do |y|
+          rect.x.upto(rect.x + rect.width - 1) { |x| at(x, y).background = background }
+        end
+      end
+
+      def lines(charset: :unicode)
+        rows.map do |row|
+          row.filter_map do |cell|
+            next if cell.continuation
+
+            [character(cell, charset), cell.role, cell.background]
+          end
+        end
+      end
+
+      def character(cell, charset)
+        return cell.char if cell.arms.zero? || cell.char != " " && cell.protected
+
+        arms = cell.arms
+        if @crossings == :bridge && arms == 15 && !cell.protected && cell.owners
+          horizontal = (cell.owners[:e] || []) + (cell.owners[:w] || [])
+          vertical = (cell.owners[:n] || []) + (cell.owners[:s] || [])
+          return charset == :ascii ? "|" : "│" if (horizontal & vertical).empty?
+        end
+        if charset == :ascii
+          return "+" unless [5, 10].include?(arms)
+          return arms == 5 ? "|" : cell.weight == :heavy ? "=" : cell.pattern == :dotted ? "." : "-"
+        end
+        return ROUNDED[arms] if cell.rounded && cell.weight == :light && ROUNDED.key?(arms)
+        return cell.weight == :heavy ? "┇" : "┆" if cell.pattern == :dotted && arms == 5
+        return cell.weight == :heavy ? "┅" : "┄" if cell.pattern == :dotted && arms == 10
+
+        key = cell.weights.join
+        BOX_DRAWING[key] || BOX_DRAWING[key.tr("3", "1")] || BOX_DRAWING[key.tr("32", "11")]
+      end
+    end
+
+    module_function
+
+    def rasterize(scene, charset: :unicode, rounded: true, ambiguous_width: 1, crossings: :plain)
+      grid = Grid.new(scene.width, scene.height, crossings: crossings)
+      scene.items.each_with_index.sort_by { |item, index| [Scene::LAYERS.fetch(item.layer, 3), index] }.each do |item, _|
+        case item
+        in Scene::Box
+          r = item.rect
+          grid.line([[r.x, r.y], [r.x + r.width - 1, r.y], [r.x + r.width - 1, r.y + r.height - 1],
+                     [r.x, r.y + r.height - 1], [r.x, r.y]], item.stroke, item.role,
+                    protect: true, rounded: rounded && item.corners == :rounded)
+        in Scene::Polyline
+          grid.line(item.points, item.stroke, item.role, owner: item.points.first)
+        in Scene::Text
+          x = item.x
+          Text.each_cell(item.string, ambiguous_width: ambiguous_width) do |char, cells|
+            if charset == :ascii && cells == 2
+              grid.put(x, item.y, "?", item.role)
+              grid.put(x + 1, item.y, "?", item.role)
+            else
+              grid.put(x, item.y, charset == :ascii ? ascii(char) : char, item.role, ambiguous_width: ambiguous_width)
+            end
+            x += cells
+          end
+        in Scene::Marker
+          char = marker(item.kind, item.direction, charset)
+          grid.put(item.x, item.y, char, item.role, protect: true)
+        in Scene::Glyph
+          grid.put(item.x, item.y, charset == :ascii ? ascii(item.char) : item.char, item.role, protect: true)
+        in Scene::Fill
+          grid.fill(item.rect, item.role.to_s.delete_prefix("bg:")) if item.role.to_s.start_with?("bg:")
+        end
+      end
+      grid
+    end
+
+    def marker(kind, direction, charset)
+      return { arrow: { n: "^", e: ">", s: "v", w: "<" }, circle: "o", cross: "x",
+               triangle: "^", diamond: "*", open_diamond: "o" }.fetch(kind).then { |v| v.is_a?(Hash) ? v.fetch(direction) : v } if charset == :ascii
+
+      { arrow: { n: "▲", e: "▶", s: "▼", w: "◀" }, circle: "○", cross: "×",
+        triangle: "△", diamond: "◆", open_diamond: "◇" }.fetch(kind).then { |v| v.is_a?(Hash) ? v.fetch(direction) : v }
+    end
+
+    def ascii(char)
+      char.ascii_only? && char.ord.between?(32, 126) ? char : "?"
+    end
+  end
+end

data/lib/merminal/scene.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Merminal
+  # Immutable drawing instructions in terminal cell coordinates.
+  Scene = Data.define(:width, :height, :items)
+  class Scene
+    Rect = Data.define(:x, :y, :width, :height)
+    Stroke = Data.define(:weight, :pattern)
+    Box = Data.define(:rect, :stroke, :corners, :role, :layer)
+    Polyline = Data.define(:points, :stroke, :role, :layer) do
+      def initialize(points:, **options)
+        raise ArgumentError, "polyline must be orthogonal" unless points.each_cons(2).all? { |a, b| a[0] == b[0] || a[1] == b[1] }
+
+        super
+      end
+    end
+    Text = Data.define(:x, :y, :string, :role, :layer, :emphasis)
+    Marker = Data.define(:x, :y, :kind, :direction, :role, :layer)
+    Glyph = Data.define(:x, :y, :char, :role, :layer)
+    Fill = Data.define(:rect, :role, :layer)
+
+    LIGHT = Stroke.new(weight: :light, pattern: :solid)
+    LAYERS = { background: 0, container: 1, edge: 2, node: 3, marker: 4, label: 5 }.freeze
+
+    def self.translate(item, dx: 0, dy: 0)
+      case item
+      in Box | Fill
+        rect = item.rect
+        item.with(rect: rect.with(x: rect.x + dx, y: rect.y + dy))
+      in Polyline
+        item.with(points: item.points.map { |x, y| [x + dx, y + dy] })
+      in Text | Marker | Glyph
+        item.with(x: item.x + dx, y: item.y + dy)
+      end
+    end
+  end
+end

data/lib/merminal/shareable.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Merminal
+  module Shareable
+    def self.make(value)
+      defined?(Ractor) ? Ractor.make_shareable(value) : value.freeze
+    end
+  end
+end