canopus 0.1.0

data/lib/canopus/settings.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require "kochab"
+
+module Canopus
+  class Settings
+    DEFAULTS = {"font_size" => 14, "tab_size" => 4, "use_tabs" => false, "soft_wrap" => false, "vim_mode" => false, "keymap" => [].freeze,
+      "scroll_friction" => 12,
+      "theme" => "Canopus Dark", "font_family" => nil, "icon_theme" => nil, "languages" => {}, "language_servers" => {}}.freeze
+    SCHEMA = {"$schema" => "https://json-schema.org/draft/2020-12/schema", "type" => "object", "properties" => {
+      "font_size" => {"type" => "number", "minimum" => 6, "maximum" => 96},
+      "tab_size" => {"type" => "integer", "minimum" => 1, "maximum" => 16},
+      "scroll_friction" => {"type" => "number", "minimum" => 0, "maximum" => 100},
+      "soft_wrap" => {"type" => "boolean"}, "vim_mode" => {"type" => "boolean"},
+      "use_tabs" => {"type" => "boolean"},
+      "keymap" => {"type" => "array", "maxItems" => 128, "items" => {"type" => "object", "required" => ["bindings"], "properties" => {
+        "context" => {"type" => "string", "maxLength" => 256},
+        "bindings" => {"type" => "object", "maxProperties" => 1024, "additionalProperties" => {"type" => ["string", "null"]}}}}},
+      "theme" => {"type" => "string"}, "font_family" => {"type" => ["string", "null"]},
+      "icon_theme" => {"type" => ["string", "null"]},
+      "languages" => {"type" => "object", "additionalProperties" => {"$ref" => "#"}},
+      "language_servers" => {"type" => "object"}}}.freeze
+    attr_reader :values, :errors, :layers
+    def self.schema = SCHEMA
+    def self.user_path
+      File.join(ENV["XDG_CONFIG_HOME"] || File.expand_path("~/.config"), "canopus", "settings.jsonc")
+    end
+    def initialize(*layers)
+      @values, @errors = DEFAULTS.dup, []
+      @layers = layers.compact
+      layers.compact.each { |layer| merge!(layer.is_a?(String) ? parse_file(layer) : layer) }
+      validate!
+    end
+    def [](key) = @values[key.to_s]
+    def paths = @layers.grep(String)
+    def reload = self.class.new(*@layers)
+    def for_language(language) = Settings.new(@values, @values.fetch("languages", {}).fetch(language, {}))
+    def merge!(layer)
+      raise Error, "settings must be an object" unless layer.is_a?(Hash)
+      previous = @values
+      @values = merge(@values, layer)
+      validate!
+      self
+    rescue StandardError
+      @values = previous if previous
+      raise
+    end
+    def set_file(path, key, value)
+      source = File.file?(path) ? File.read(path) : "{}\n"
+      doc = Kochab.parse(source)
+      raise Error, "cannot edit invalid settings" unless doc.valid?
+      replacement = Kochab.apply(source, doc.set([key.to_s], value))
+      Settings.new(Kochab.parse(replacement).value)
+      FileUtils.mkdir_p(File.dirname(path))
+      Tempfile.create([".settings-", ".json"], File.dirname(path)) do |file|
+        file.write(replacement)
+        file.flush
+        file.fsync
+        file.close
+        raise SaveConflict, "settings changed during save" if File.file?(path) && File.read(path) != source
+        File.rename(file.path, path)
+      end
+    end
+    private
+    def parse_file(path)
+      return {} unless File.file?(path)
+      document = Kochab.parse(File.read(path))
+      @errors.concat(document.errors)
+      raise Error, "invalid settings: #{path}" unless document.valid?
+      document.value
+    end
+    def merge(left, right)
+      left.merge(right) { |_, old, new| old.is_a?(Hash) && new.is_a?(Hash) ? merge(old, new) : new }
+    end
+    def validate!
+      {"font_size" => 6..96, "tab_size" => 1..16, "scroll_friction" => 0..100}.each do |key, range|
+        value = @values[key]
+        raise Error, "invalid #{key}" unless value.is_a?(Numeric) && range.cover?(value)
+      end
+      raise Error, "tab_size must be an integer" unless @values["tab_size"].is_a?(Integer)
+      %w[soft_wrap vim_mode use_tabs].each { |key| raise Error, "#{key} must be true or false" unless [true, false].include?(@values[key]) }
+      validate_keymap!
+      %w[languages language_servers].each { |key| raise Error, "#{key} must be an object" unless @values[key].is_a?(Hash) }
+      raise Error, "theme must be a string" unless @values["theme"].is_a?(String)
+      raise Error, "font_family must be a string or null" unless @values["font_family"].nil? || @values["font_family"].is_a?(String)
+      raise Error, "icon_theme must be a string or null" unless @values["icon_theme"].nil? || @values["icon_theme"].is_a?(String)
+      @values["languages"] = @values["languages"].to_h do |name, layer|
+        raise Error, "language settings must be objects" unless name.is_a?(String) && layer.is_a?(Hash)
+        raise Error, "language settings cannot contain nested languages" if layer.key?("languages")
+        checked = Settings.new(@values.merge("languages" => {}), layer)
+        [name, layer.key?("keymap") ? layer.merge("keymap" => checked["keymap"]) : layer]
+      end
+    end
+    def validate_keymap!
+      groups = @values["keymap"]
+      raise Error, "keymap must be an array of at most 128 groups" unless groups.is_a?(Array) && groups.length <= 128
+      count = 0
+      @values["keymap"] = groups.map do |group|
+        raise Error, "keymap groups require a bindings object" unless group.is_a?(Hash) && group["bindings"].is_a?(Hash)
+        context = group.fetch("context", "")
+        raise Error, "keymap context must be a string of at most 256 bytes" unless context.is_a?(String) && context.bytesize <= 256
+        Zaniah::Input::ContextPredicate.new(context)
+        bindings = group["bindings"].to_h do |keys, action|
+          count += 1
+          raise Error, "keymap exceeds 1024 bindings" if count > 1024
+          raise Error, "invalid keymap key sequence" unless keys.is_a?(String) && keys.bytesize.between?(1, 256) && !keys.strip.empty?
+          keys.split.each { |key| Zaniah::Input::Keystroke.normalize(key) }
+          raise Error, "keymap action must be a string or null" unless action.nil? || (action.is_a?(String) && action.bytesize.between?(1, 256))
+          [keys.dup.freeze, action&.dup&.freeze]
+        end.freeze
+        {"context" => context.dup.freeze, "bindings" => bindings}.freeze
+      end.freeze
+    rescue ArgumentError => error
+      raise Error, "invalid keymap: #{error.message}"
+    end
+  end
+end

data/lib/canopus/snippet/transform.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+# Deliberately uses bounded Ruby Regexp, never eval or an external JS runtime.
+# Supported syntax and JS portability boundaries are in docs/snippets.md.
+class Canopus::Snippet::Transform
+  TIMEOUT = 0.05
+  SPACE = '\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff'
+  CASES = %w[upcase downcase capitalize camelcase pascalcase snakecase kebabcase].freeze
+  Format = Data.define(:index, :operation, :positive, :negative)
+  private_constant :Format
+  attr_reader :pattern, :flags
+
+  def self.parse(scanner, depth)
+    pattern = +""
+    closed = false
+    until scanner.eos?
+      character = scanner.getch
+      if character == "\\"
+        following = scanner.getch
+        raise Canopus::Error, "unclosed snippet transform" unless following
+        pattern << (following == "/" ? "/" : "\\#{following}")
+      elsif character == "/"
+        closed = true
+        break
+      else
+        pattern << character
+      end
+    end
+    raise Canopus::Error, "unclosed snippet transform pattern" unless closed
+    replacement = parse_format(scanner, ["/"], depth)
+    raise Canopus::Error, "unclosed snippet transform replacement" unless scanner.getch == "/"
+    flags = scanner.scan(/[A-Za-z]*/)
+    raise Canopus::Error, "unclosed snippet transform" unless scanner.getch == "}"
+    new(pattern, replacement, flags)
+  end
+
+  def self.parse_format(scanner, endings, depth, budget = [0])
+    raise Canopus::Error, "snippet format nesting exceeds #{Canopus::Snippet::MAX_DEPTH}" if depth > Canopus::Snippet::MAX_DEPTH
+    nodes, literal = [], +""
+    until scanner.eos? || endings.include?(scanner.peek(1))
+      character = scanner.getch
+      if character == "\\" && scanner.peek(1).match?(/[\\\/$}:]/)
+        literal << scanner.getch
+      elsif character == "$"
+        braced = !!scanner.scan(/\{/)
+        number = scanner.scan(/\d+/)
+        unless number
+          raise Canopus::Error, "invalid snippet transform capture" if braced
+          literal << "$"
+          next
+        end
+        raise Canopus::Error, "snippet capture index is too large" if number.length > 7 || number.to_i > 1_000_000
+        nodes << literal.freeze unless literal.empty?
+        literal = +""
+        operation, positive, negative = :capture, [], []
+        budget[0] += 1
+        raise Canopus::Error, "too many snippet format captures" if budget[0] > Canopus::Snippet::MAX_NODES
+        if braced && scanner.scan(/:/)
+          operation_start = scanner.pos
+          case scanner.getch
+          when "/"
+            operation = scanner.scan(/[a-z]+/)
+            raise Canopus::Error, "unsupported snippet case conversion" unless CASES.include?(operation)
+          when "+"
+            operation = :if
+            positive = parse_format(scanner, ["}"], depth + 1, budget)
+          when "?"
+            operation = :conditional
+            positive = parse_format(scanner, [":", "}"], depth + 1, budget)
+            raise Canopus::Error, "snippet conditional requires ':'" unless scanner.getch == ":"
+            negative = parse_format(scanner, ["}"], depth + 1, budget)
+          when "-"
+            operation = :else
+            negative = parse_format(scanner, ["}"], depth + 1, budget)
+          else
+            scanner.pos = operation_start
+            operation = :else
+            negative = parse_format(scanner, ["}"], depth + 1, budget)
+          end
+        end
+        raise Canopus::Error, "unclosed snippet transform format" if braced && scanner.getch != "}"
+        nodes << Format.new(number.to_i, operation, positive.freeze, negative.freeze)
+      else
+        literal << character
+      end
+    end
+    nodes << literal.freeze unless literal.empty?
+    nodes.freeze
+  end
+
+  def initialize(pattern, replacement, flags)
+    raise Canopus::Error, "unsupported snippet transform flags: #{flags}" unless flags.match?(/\A[gimsu]*\z/) && flags.chars.uniq.length == flags.length
+    raise Canopus::Error, "snippet transform pattern is too large" if pattern.bytesize > 65_536
+    @pattern, @flags, @replacement = pattern.freeze, flags.freeze, replacement
+    # Reject Ruby-only syntax and constructs with incompatible JS semantics.
+    translated, in_class, scanner, groups = +"", false, StringScanner.new(pattern), []
+    until scanner.eos?
+      character = scanner.getch
+      if character == "\\"
+        following = scanner.getch
+        raise Canopus::Error, "incomplete snippet regular expression escape" unless following
+        raise Canopus::Error, "unsupported snippet regular expression escape: \\#{following}" if following.match?(/[AGKRXZzghkpPc1-9]/) || (following == "u" && flags.include?("i"))
+        translated << case following
+        when "s" then in_class ? SPACE : "[#{SPACE}]"
+        when "S" then "[^#{SPACE}]"
+        when "b" then in_class ? "\\b" : '(?:(?<=\w)(?!\w)|(?<!\w)(?=\w))'
+        when "B"
+          @nonword_boundary = true unless in_class
+          in_class ? "B" : '(?:(?<=\w)(?=\w)|(?<!\w)(?!\w))'
+        else character + following
+        end
+      else
+        if !in_class && ((character == "(" && scanner.peek(1) == "?" && !scanner.rest.match?(/\A\?(?:[:=!]|<[=!])/)) || (character.match?(/[*+?}]/) && scanner.peek(1) == "+"))
+          raise Canopus::Error, "unsupported snippet regular expression construct"
+        end
+        raise Canopus::Error, "unsupported snippet character-class intersection" if in_class && character == "&" && scanner.peek(1) == "&"
+        if !in_class && character == "("
+          capture = scanner.peek(1) != "?"
+          groups.map! { |parent| parent || capture }
+          groups << capture
+          raise Canopus::Error, "snippet regular expression nesting exceeds #{Canopus::Snippet::MAX_DEPTH}" if groups.length > Canopus::Snippet::MAX_DEPTH
+        elsif !in_class && character == ")"
+          captures = groups.pop
+          raise Canopus::Error, "captures inside repeated groups are not portable" if captures && scanner.peek(1).match?(/[*+{]/)
+        end
+        translated << case character
+        when "[" then if in_class then "\\[" else in_class = true; character end
+        when "]" then in_class = false; character
+        when "^" then in_class ? character : flags.include?("m") ? '(?:\A|(?<=[\r\n\u2028\u2029]))' : '\A'
+        when "$" then in_class ? character : flags.include?("m") ? '(?=\z|[\r\n\u2028\u2029])' : '\z'
+        when "." then !in_class && !flags.include?("s") ? "[^\\n\\r\\u2028\\u2029]" : character
+        else character
+        end
+      end
+    end
+    options = (flags.include?("i") ? Regexp::IGNORECASE : 0) | (flags.include?("s") ? Regexp::MULTILINE : 0)
+    @regexp = Regexp.new(translated, options, timeout: TIMEOUT)
+    freeze
+  rescue RegexpError => error
+    raise Canopus::Error, "invalid snippet regular expression: #{error.message}"
+  end
+
+  def apply(value)
+    raise Canopus::Error, "snippet transform input exceeds output limit" if value.bytesize > Canopus::Snippet::MAX_OUTPUT
+    astral = value.match?(/[\u{10000}-\u{10ffff}]/) || @pattern.match?(/[\u{10000}-\u{10ffff}]/)
+    raise Canopus::Error, "astral Unicode snippet transforms require the 'u' flag" if astral && !@flags.include?("u")
+    raise Canopus::Error, "\\B with astral Unicode is not portable between JavaScript and Ruby" if astral && @nonword_boundary
+    if @flags.include?("i") && [value, @pattern].any? { |source| source.each_char.any? { |character| !character.ascii_only? && ((folded = character.downcase(:fold)).length != 1 || folded.ascii_only?) } }
+      raise Canopus::Error, "Unicode case folding into ASCII or multiple characters is not portable"
+    end
+    output, cursor, count, matched = +"", 0, 0, false
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + TIMEOUT
+    Canopus.with_regexp_timeout(@regexp) do
+      value.to_enum(:scan, @regexp).each do
+        match = Regexp.last_match
+        matched = true
+        count += 1
+        raise Canopus::Error, "snippet transform exceeded execution limit" if count > Canopus::Snippet::MAX_NODES || Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        first, last = match.byteoffset(0)
+        append(output, value.byteslice(cursor...first))
+        append(output, format(@replacement, match))
+        cursor = last
+        break unless @flags.include?("g")
+      end
+    end
+    return format(@replacement, nil) if !matched && fallback?(@replacement)
+    append(output, value.byteslice(cursor..))
+    output
+  rescue Regexp::TimeoutError
+    raise Canopus::Error, "snippet regular expression timed out"
+  end
+
+  private
+
+  def append(output, text)
+    raise Canopus::Error, "snippet transform exceeds output limit" if output.bytesize + text.bytesize > Canopus::Snippet::MAX_OUTPUT
+    output << text
+  end
+
+  def fallback?(nodes)
+    nodes.any? { |node| node.is_a?(Format) && ([:else, :conditional].include?(node.operation) || fallback?(node.positive) || fallback?(node.negative)) }
+  end
+
+  def format(nodes, match)
+    nodes.each_with_object(+"") do |node, output|
+      if node.is_a?(String)
+        append(output, node)
+        next
+      end
+      value = (match && node.index < match.length ? match[node.index] : nil).to_s
+      replacement = case node.operation
+      when :capture then value
+      when :if then value.empty? ? "" : format(node.positive, match)
+      when :conditional then format(value.empty? ? node.negative : node.positive, match)
+      when :else then value.empty? ? format(node.negative, match) : value
+      when "upcase" then value.upcase
+      when "downcase" then value.downcase
+      when "capitalize" then value.sub(/\A./m) { |first| first.upcase }
+      when "camelcase", "pascalcase"
+        words = value.scan(/[\p{L}\p{N}]+/)
+        words.each_with_index.map { |word, index| word.sub(/\A./m) { |first| index.zero? && node.operation == "camelcase" ? first.downcase : first.upcase } }.join
+      when "snakecase" then value.gsub(/([\p{Ll}\d])([\p{Lu}])/, '\1_\2').gsub(/[\s-]+/, "_").downcase
+      when "kebabcase"
+        value.gsub(/([\p{Lu}]+)([\p{Lu}][\p{Ll}])/, '\1-\2').gsub(/([\p{Ll}\d])([\p{Lu}])/, '\1-\2').gsub(/[^\p{L}\p{N}]+/, "-").sub(/\A-/, "").sub(/-\z/, "").downcase
+      end
+      append(output, replacement)
+    end
+  end
+end

data/lib/canopus/snippet.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Canopus
+  # LSP/TextMate snippets. All exported offsets are UTF-8 byte offsets.
+  class Snippet
+    MAX_SOURCE = 1 << 20
+    MAX_OUTPUT = 4 << 20
+    MAX_DEPTH = 32
+    MAX_NODES = 10_000
+    VARIABLES = %w[TM_SELECTED_TEXT TM_CURRENT_LINE TM_CURRENT_WORD TM_LINE_INDEX TM_LINE_NUMBER
+      TM_FILENAME TM_FILENAME_BASE TM_DIRECTORY TM_FILEPATH RELATIVE_FILEPATH CLIPBOARD
+      WORKSPACE_NAME WORKSPACE_FOLDER CURSOR_INDEX CURSOR_NUMBER CURRENT_YEAR CURRENT_YEAR_SHORT
+      CURRENT_MONTH CURRENT_MONTH_NAME CURRENT_MONTH_NAME_SHORT CURRENT_DATE CURRENT_DAY_NAME
+      CURRENT_DAY_NAME_SHORT CURRENT_HOUR CURRENT_MINUTE CURRENT_SECOND CURRENT_MILLISECOND
+      CURRENT_SECONDS_UNIX CURRENT_MILLISECONDS_UNIX CURRENT_TIMEZONE_OFFSET CURRENT_TIMEZONE_NAME
+      RANDOM RANDOM_HEX UUID BLOCK_COMMENT_START BLOCK_COMMENT_END LINE_COMMENT].freeze
+    Occurrence = Data.define(:index, :range, :transform, :parents)
+    Node = Struct.new(:index, :children, :choices, :transform)
+    private_constant :Node
+    attr_reader :text, :tabstops, :choices, :transforms, :occurrences
+
+    def initialize(source, variables: {})
+      raise Error, "snippet must be valid UTF-8" unless source.is_a?(String) && source.valid_encoding? && (source.encoding == Encoding::UTF_8 || (source.encoding.ascii_compatible? && source.ascii_only?))
+      raise Error, "snippet exceeds #{MAX_SOURCE} bytes" if source.bytesize > MAX_SOURCE
+      raise Error, "snippet variables must be a Hash" unless variables.is_a?(Hash)
+      @variables = variables.to_h do |key, value|
+        raise Error, "snippet variable values must be UTF-8 strings or nil" unless value.nil? || (value.is_a?(String) && value.valid_encoding? && (value.encoding == Encoding::UTF_8 || (value.encoding.ascii_compatible? && value.ascii_only?)))
+        raise Error, "snippet variable exceeds output limit" if value && value.bytesize > MAX_OUTPUT
+        [key.to_s, value&.encode(Encoding::UTF_8)]
+      end
+      @scanner, @node_count, @maximum_index = StringScanner.new(source), 0, 0
+      nodes = parse
+      nodes = resolve_variables(nodes)
+      @defaults, @choices = {}, {}
+      collect_defaults(nodes)
+      @text, @tabstops, @transforms = +"", Hash.new { |h, k| h[k] = [] }, []
+      @occurrences = []
+      render(nodes)
+      @text.freeze
+      @tabstops = @tabstops.sort_by { |index, _| index.zero? ? Float::INFINITY : index }.to_h.transform_values { |ranges| ranges.freeze }.freeze
+      @choices.freeze
+      @transforms.freeze
+      @occurrences.freeze
+      # The parse tree and variable values are not retained by a live editor.
+      @scanner = @variables = @defaults = nil
+    end
+
+    private
+
+    def parse(ending = nil, depth = 0)
+      raise Error, "snippet nesting exceeds #{MAX_DEPTH}" if depth > MAX_DEPTH
+      nodes, literal = [], +""
+      until @scanner.eos?
+        character = @scanner.getch
+        if character == ending
+          nodes << literal unless literal.empty?
+          return nodes
+        elsif character == "\\" && @scanner.peek(1).match?(/[\\$}]/)
+          literal << @scanner.getch
+        elsif character == "$"
+          braced = !!@scanner.scan(/\{/)
+          identifier = @scanner.scan(/\d+|[A-Za-z_][A-Za-z_0-9]*/)
+          if !identifier && !braced
+            literal << "$"
+            next
+          end
+          raise Error, "invalid snippet identifier" unless identifier
+          nodes << literal unless literal.empty?
+          literal = +""
+          numbered = identifier.match?(/\A\d+\z/)
+          raise Error, "snippet tabstop index is too long" if numbered && identifier.length > 7
+          index = numbered ? Integer(identifier, 10) : identifier
+          raise Error, "snippet tabstop index is too large" if index.is_a?(Integer) && index > 1_000_000
+          @maximum_index = [@maximum_index, index].max if index.is_a?(Integer)
+          node = Node.new(index)
+          @node_count += 1
+          raise Error, "too many snippet nodes" if @node_count > MAX_NODES
+          if braced
+            case @scanner.getch
+            when "}" # Bare tabstop or variable.
+            when ":" then node.children = parse("}", depth + 1)
+            when "|"
+              raise Error, "choices require a numbered tabstop" unless index.is_a?(Integer)
+              node.choices = parse_choices
+              node.children = [node.choices.first]
+            when "/" then node.transform = Transform.parse(@scanner, depth + 1)
+            else raise Error, "invalid or unclosed snippet placeholder"
+            end
+          end
+          nodes << node
+        else
+          literal << character
+        end
+      end
+      raise Error, "unclosed snippet placeholder" if ending
+      nodes << literal unless literal.empty?
+      nodes
+    end
+
+    def parse_choices
+      choices, value = [], +""
+      until @scanner.eos?
+        character = @scanner.getch
+        if character == "\\" && @scanner.peek(1).match?(/[\\,|]/)
+          value << @scanner.getch
+        elsif character == ","
+          choices << value.freeze
+          value = +""
+        elsif character == "|" && @scanner.scan(/\}/)
+          choices << value.freeze
+          return choices.freeze
+        else
+          value << character
+        end
+        raise Error, "too many snippet choices" if choices.length >= MAX_NODES
+      end
+      raise Error, "unclosed snippet choice"
+    end
+
+    def resolve_variables(nodes)
+      nodes.flat_map do |node|
+        next node if node.is_a?(String)
+        if node.index.is_a?(Integer)
+          node.children = resolve_variables(node.children) if node.children
+          [node]
+        elsif node.transform
+          [node.transform.apply(@variables[node.index] || "")]
+        elsif @variables[node.index]
+          [@variables[node.index]]
+        elsif node.children
+          resolve_variables(node.children)
+        elsif @variables.key?(node.index) || VARIABLES.include?(node.index)
+          [""]
+        else
+          @maximum_index += 1
+          [Node.new(@maximum_index, [node.index])]
+        end
+      end
+    end
+
+    def collect_defaults(nodes)
+      nodes.each do |node|
+        next if node.is_a?(String)
+        @defaults[node.index] ||= node.children if node.children && !node.children.empty?
+        @choices[node.index] ||= node.choices if node.choices
+        collect_defaults(node.children) if node.children
+      end
+    end
+
+    def render(nodes, ancestors = [])
+      nodes.each do |node|
+        if node.is_a?(String)
+          raise Error, "expanded snippet exceeds #{MAX_OUTPUT} bytes" if @text.bytesize + node.bytesize > MAX_OUTPUT
+          @text << node
+          next
+        end
+        raise Error, "cyclic snippet placeholder #{node.index}" if ancestors.include?(node.index)
+        raise Error, "expanded snippet nesting exceeds #{MAX_DEPTH}" if ancestors.length >= MAX_DEPTH
+        start = @text.bytesize
+        # Transformed mirrors start with the placeholder value, and change on Tab.
+        # Their nested fields are not independent editable tabstops.
+        previous_tabstops, previous_transforms, previous_occurrences = @tabstops, @transforms, @occurrences if node.transform
+        @tabstops, @transforms, @occurrences = Hash.new { |h, k| h[k] = [] }, [], [] if node.transform
+        render(@defaults[node.index] || [], [*ancestors, node.index])
+        @tabstops, @transforms, @occurrences = previous_tabstops, previous_transforms, previous_occurrences if node.transform
+        range = (start...@text.bytesize).freeze
+        occurrence = Occurrence.new(node.index, range, node.transform, ancestors.freeze)
+        @occurrences << occurrence
+        if node.transform
+          @transforms << occurrence
+        else
+          @tabstops[node.index] << range
+        end
+        @rendered_nodes = (@rendered_nodes || 0) + 1
+        raise Error, "too many expanded snippet nodes" if @rendered_nodes > MAX_NODES
+      end
+    end
+  end
+end
+
+require_relative "snippet/transform"

data/lib/canopus/tab_map.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Canopus
+  class TabMap
+    attr_reader :tab_size
+    def initialize(tab_size: 4)
+      raise ArgumentError, "tab size must be positive" unless tab_size.is_a?(Integer) && tab_size.positive?
+      @tab_size = tab_size
+    end
+    def transform(text, offsets, checkpoint: nil)
+      output, positions, column, i = +"", [offsets.first], 0, 0
+      text.each_grapheme_cluster do |char|
+        checkpoint&.call if (i & 1023).zero?
+        if char == "\t"
+          count = @tab_size - column % @tab_size
+          output << " " * count
+          (count - 1).times { positions << offsets[i] }
+          positions << offsets[i + 1]
+          column += count
+        else
+          output << char
+          char.length.times { |index| positions << offsets[i + index + 1] }
+          column += char.ascii_only? ? char.length : Zaniah::Unicode.width(char)
+        end
+        i += char.length
+      end
+      [output, positions]
+    end
+  end
+end

data/lib/canopus/terminal/cell.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Canopus
+  module Terminal
+    Cell = Struct.new(:text, :width, :foreground, :background, :attributes, :hyperlink, keyword_init: true)
+  end
+end