canopus 0.1.0

data/lib/canopus/lsp/protocol.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Canopus
+  module LSP
+    module Protocol
+      module_function
+      def uri(path)
+        absolute = File.expand_path(path).tr("\\", "/")
+        absolute = "/#{absolute}" if absolute.match?(/\A[A-Za-z]:/)
+        "file://" + URI::RFC2396_PARSER.escape(absolute, /[^a-zA-Z0-9\-._~\/:]/)
+      end
+      def path(uri)
+        parsed = URI.parse(uri)
+        raise Error, "expected local file URI" unless parsed.scheme == "file" && [nil, "", "localhost"].include?(parsed.host) && parsed.query.nil? && parsed.fragment.nil? && parsed.path&.start_with?("/")
+        path = URI::RFC2396_PARSER.unescape(parsed.path)
+        raise Error, "invalid file URI path" if path.include?("\0") || !path.valid_encoding?
+        RUBY_PLATFORM.match?(/mswin|mingw/) ? path.sub(%r{\A/([A-Za-z]:/)}, '\\1') : path
+      rescue URI::InvalidURIError => error
+        raise Error, error.message
+      end
+      def position(rope, offset)
+        point = rope.utf16_point_at(offset)
+        {line: point.row, character: point.column}
+      end
+      def offset(rope, position)
+        raise Error, "invalid LSP position" unless position.is_a?(Hash) && uint?(position["line"]) && uint?(position["character"])
+        row, column = position.fetch("line"), position.fetch("character")
+        start = rope.line_start(row)
+        finish = start + rope.line(row).bytesize
+        units = rope.utf16_offset_at(finish) - rope.utf16_offset_at(start)
+        rope.offset_at_utf16(rope.utf16_offset_at(start) + [column, units].min)
+      end
+      def range(rope, range)
+        {start: position(rope, range.begin), end: position(rope, range.end + (range.exclude_end? ? 0 : 1))}
+      end
+      def semantic_delta(data, edits)
+        raise Error, "invalid semantic token delta" unless data.is_a?(Array) && edits.is_a?(Array)
+        output = data.dup
+        last = 0
+        edits.each do |edit|
+          raise Error, "invalid semantic token delta" unless edit.is_a?(Hash) && uint?(edit["start"]) && uint?(edit["deleteCount"]) && edit.fetch("data", []).is_a?(Array)
+        end
+        sorted = edits.sort_by { |edit| edit.fetch("start") }
+        sorted.each do |edit|
+          start, count = edit.fetch("start"), edit.fetch("deleteCount")
+          raise Error, "invalid semantic token delta" unless start.is_a?(Integer) && count.is_a?(Integer) && start >= last && count >= 0 && start + count <= data.length
+          last = start + count
+        end
+        sorted.reverse_each { |edit| output[edit.fetch("start"), edit.fetch("deleteCount")] = edit.fetch("data", []) }
+        semantic_tokens(output)
+        output
+      end
+      def uint?(value) = value.is_a?(Integer) && value.between?(0, 0x7fffffff)
+      def diagnostics(values)
+        valid = values.is_a?(Array) && values.all? do |value|
+          next false unless value.is_a?(Hash) && value["message"].is_a?(String) && value["range"].is_a?(Hash)
+          range = value["range"]
+          points = %w[start end].map { |key| range[key] }
+          points.all? { |point| point.is_a?(Hash) && uint?(point["line"]) && uint?(point["character"]) } &&
+            ([points[0]["line"], points[0]["character"]] <=> [points[1]["line"], points[1]["character"]]) <= 0 &&
+            (!value.key?("severity") || (value["severity"].is_a?(Integer) && value["severity"].between?(1, 4)))
+        end
+        raise Error, "invalid LSP diagnostics" unless valid
+        values
+      end
+      def semantic_tokens(data, legend: nil)
+        raise Error, "invalid semantic token tuple count" unless data.is_a?(Array) && data.length % 5 == 0
+        if legend
+          raise Error, "invalid semantic token legend" unless legend.is_a?(Hash) && %w[tokenTypes tokenModifiers].all? { |key| legend[key].is_a?(Array) && legend[key].all? { |name| name.is_a?(String) } }
+        end
+        row, column = 0, 0
+        data.each_slice(5).map do |delta_row, delta_column, length, type, modifiers|
+          raise Error, "invalid semantic token value" unless [delta_row, delta_column, length, type, modifiers].all? { |v| uint?(v) } && length.positive?
+          raise Error, "semantic token exceeds legend" if legend && (type >= legend["tokenTypes"].length || modifiers.bit_length > legend["tokenModifiers"].length)
+          row += delta_row
+          column = delta_row.zero? ? column + delta_column : delta_column
+          raise Error, "semantic token position overflow" unless uint?(row) && uint?(column + length)
+          {line: row, character: column, length: length, type: type, modifiers: modifiers}
+        end
+      end
+    end
+  end
+end

data/lib/canopus/lsp/server_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Canopus
+  module LSP
+    class ServerError < Error
+      attr_reader :code, :data
+      def initialize(error)
+        @code, @data = error["code"], error["data"]
+        super(error["message"])
+      end
+    end
+  end
+end

data/lib/canopus/lsp/timeout.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Canopus
+  module LSP
+    class Timeout < Error; end
+  end
+end

data/lib/canopus/lsp/transport.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Canopus
+  module LSP
+    class Transport
+      MAX_MESSAGE = 32 << 20
+      attr_reader :stderr_lines, :pid
+      def initialize(command, cwd: nil, env: {}, &receive)
+        raise ArgumentError, "command must be a nonempty argument array" unless command.is_a?(Array) && !command.empty? && command.all? { |part| part.is_a?(String) && !part.include?("\0") }
+        raise ArgumentError, "receiver required" unless receive
+        options = cwd ? {chdir: cwd} : {}
+        @stdin, @stdout, @stderr, @process = Open3.popen3(env, *command, **options)
+        @stdin.binmode
+        @stdout.binmode
+        @pid, @write_lock, @stderr_lines = @process.pid, Mutex.new, []
+        @reader = Thread.new do
+          begin
+            loop do
+              message = self.class.read_message(@stdout)
+              break unless message
+              receive.call(message, nil)
+            end
+            receive.call(nil, Error.new("language server closed stdout")) unless @closing
+          rescue StandardError => error
+            begin
+              receive.call(nil, error) unless @closing
+            rescue StandardError
+              nil
+            end
+          end
+        end
+        @logger = Thread.new do
+          while (line = @stderr.gets("\n", 8192))
+            @stderr_lines << line.scrub.byteslice(0, 8192).scrub("")
+            @stderr_lines.shift if @stderr_lines.length > 200
+          end
+        rescue IOError
+          nil
+        end
+      end
+      def self.read_message(io)
+        headers, count = {}, 0
+        loop do
+          line = io.gets("\r\n", 8193)
+          return nil if line.nil? && headers.empty?
+          raise Error, "truncated or oversized LSP header" unless line && line.end_with?("\r\n") && line.bytesize <= 8192
+          break if line == "\r\n"
+          count += line.bytesize
+          raise Error, "oversized LSP headers" if count > 16384
+          raise Error, "non-ASCII LSP header" unless line.ascii_only?
+          key, value = line.strip.split(":", 2)
+          raise Error, "invalid LSP header" unless value && key.match?(/\A[A-Za-z][A-Za-z0-9-]*\z/)
+          key = key.downcase
+          raise Error, "duplicate LSP header" if headers.key?(key)
+          headers[key] = value.strip
+        end
+        raw_length = headers["content-length"]
+        raise Error, "missing or invalid Content-Length" unless raw_length&.match?(/\A\d+\z/)
+        length = Integer(raw_length, 10)
+        raise Error, "oversized LSP message" unless length.between?(1, MAX_MESSAGE)
+        charset = headers["content-type"]&.match(/charset\s*=\s*"?([^;"\s]+)/i)&.[](1)
+        raise Error, "unsupported LSP character encoding" if charset && !%w[utf-8 utf8].include?(charset.downcase)
+        body = io.read(length)
+        raise Error, "truncated LSP body" unless body && body.bytesize == length
+        body.force_encoding(Encoding::UTF_8)
+        raise Error, "invalid LSP UTF-8 body" unless body.valid_encoding?
+        validate_message(JSON.parse(body))
+      rescue JSON::ParserError => error
+        raise Error, "invalid LSP JSON: #{error.message.byteslice(0, 256)}"
+      end
+      def self.validate_message(message)
+        raise Error, "invalid JSON-RPC message" unless message.is_a?(Hash) && message["jsonrpc"] == "2.0"
+        if message.key?("method")
+          raise Error, "invalid JSON-RPC method" unless message["method"].is_a?(String) && !message["method"].empty?
+          raise Error, "invalid JSON-RPC parameters" if message.key?("params") && !message["params"].is_a?(Hash) && !message["params"].is_a?(Array)
+          raise Error, "request contains a response" if message.key?("result") || message.key?("error")
+        else
+          raise Error, "invalid JSON-RPC response" unless message.key?("id") && (message.key?("result") ^ message.key?("error"))
+          if message.key?("error")
+            error = message["error"]
+            raise Error, "invalid JSON-RPC error" unless error.is_a?(Hash) && error["code"].is_a?(Integer) && error["message"].is_a?(String)
+          end
+        end
+        id = message["id"]
+        raise Error, "invalid JSON-RPC id" if message.key?("id") && !id.is_a?(Integer) && !id.is_a?(String) && !(id.nil? && !message.key?("method"))
+        message
+      end
+      def write(message)
+        raise Error, "expected JSON-RPC object" unless message.is_a?(Hash)
+        normalized = message.transform_keys(&:to_s)
+        normalized["error"] = normalized["error"].transform_keys(&:to_s) if normalized["error"].is_a?(Hash)
+        self.class.validate_message(normalized)
+        body = JSON.generate(message).b
+        raise Error, "oversized LSP message" unless body.bytesize.between?(1, MAX_MESSAGE)
+        @write_lock.synchronize do
+          @stdin.write("Content-Length: #{body.bytesize}\r\n\r\n")
+          @stdin.write(body)
+          @stdin.flush
+        end
+      rescue IOError, Errno::EPIPE => error
+        raise Error, "language server write failed: #{error.message}"
+      end
+      def alive? = @process.alive?
+      def close
+        return if @closing
+        @closing = true
+        @stdin.close unless @stdin.closed?
+        unless @process.join(1)
+          Process.kill("TERM", @pid) rescue Errno::ESRCH
+          unless @process.join(1)
+            Process.kill("KILL", @pid) rescue Errno::ESRCH
+            @process.join
+          end
+        end
+        [@stdout, @stderr].each { |io| io.close unless io.closed? }
+        [@reader, @logger].each do |thread|
+          next if thread == Thread.current
+          thread.kill unless thread.join(1)
+        end
+      end
+    end
+  end
+end

data/lib/canopus/lsp.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "uri"
+require "thread"
+
+module Canopus
+  module LSP; end
+end
+
+require_relative "lsp/error"
+require_relative "lsp/timeout"
+require_relative "lsp/server_error"
+require_relative "lsp/protocol"
+require_relative "lsp/future"
+require_relative "lsp/future/subscription"
+require_relative "lsp/transport"
+require_relative "lsp/client"

data/lib/canopus/markdown.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rouge"
+require "unicode/display_width"
+
+module Canopus
+  # Bounded hover content. Rouge already understands Markdown and fenced code;
+  # HTML and images remain text and never fetch resources or execute anything.
+  class Markdown
+    Run = Data.define(:text, :style, :url)
+    attr_reader :rows
+
+    def initialize(source, width: 72, max_rows: 18, markup: true)
+      raise ArgumentError, "invalid hover dimensions" unless width.is_a?(Integer) && width.positive? && max_rows.is_a?(Integer) && max_rows.positive?
+      source = source.to_s.byteslice(0, 65_536).to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace).scrub
+      tokens = markup ? Rouge::Lexer.find("markdown").new.lex(source).map { |token, value| [token.qualname, value] } : [["Text", source]]
+      @rows, column, index = [[]], 0, 0
+      while index < tokens.length && @rows.length <= max_rows
+        kind, value = tokens[index]
+        style, url = :text, nil
+        if markup && value == "[" && tokens[index + 1]&.first == "Name.Variable" && tokens[index + 2]&.last == "](" && tokens[index + 3]&.first == "Literal.String.Other" && tokens[index + 4]&.last == ")"
+          value, url, style = tokens[index + 1].last, tokens[index + 3].last, :link
+          index += 4
+        elsif markup
+          case kind
+          when "Generic.Heading", "Generic.Subheading"
+            value, style = value.sub(/\A\#{1,6}\s*/, ""), :heading
+          when "Generic.Strong" then value, style = value[2...-2], :strong
+          when "Generic.Emph" then value, style = value[1...-1], :emphasis
+          when "Literal.String.Backtick" then value, style = value.sub(/\A`+/, "").sub(/`+\z/, ""), :code
+          when "Generic.Traceback" then value, style = value.sub(/\A>\s?/, "│ "), :quote
+          when "Punctuation"
+            if value.match?(/\A(?:`{3,}|~{3,})\z/)
+              index += 1 if tokens[index + 1]&.first == "Name.Label"
+              value = ""
+            end
+          else
+            style = kind unless kind == "Text"
+          end
+        end
+        value.to_s.each_grapheme_cluster do |grapheme|
+          if grapheme.include?("\n")
+            @rows << []
+            column = 0
+            break if @rows.length > max_rows
+            next
+          end
+          cells = Unicode::DisplayWidth.of(grapheme, emoji: :rgi)
+          if column.positive? && column + cells > width
+            @rows << []
+            column = 0
+            break if @rows.length > max_rows
+          end
+          previous = @rows.last.last
+          if previous && previous.style == style && previous.url == url
+            previous.text << grapheme
+          else
+            @rows.last << Run.new(+grapheme, style, url)
+          end
+          column += cells
+        end
+        index += 1
+      end
+      @rows = @rows.first(max_rows)
+      @rows.pop while @rows.length > 1 && @rows.last.empty?
+      @rows.each { |row| row.each { |run| run.text.freeze }; row.freeze }.freeze
+    end
+  end
+end

data/lib/canopus/match_data_compat.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+unless MatchData.method_defined?(:byteoffset) && MatchData.method_defined?(:bytebegin)
+  class MatchData
+    unless method_defined?(:byteoffset)
+      def byteoffset(index)
+        first, last = offset(index)
+        first && [string[0...first].bytesize, string[0...last].bytesize]
+      end
+    end
+
+    unless method_defined?(:bytebegin)
+      def bytebegin(index) = byteoffset(index)&.first
+      def byteend(index) = byteoffset(index)&.last
+    end
+  end
+end

data/lib/canopus/multi_buffer.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Canopus
+  # Editable, nonoverlapping source excerpts with protected headings.
+  class MultiBuffer < Buffer
+    Excerpt = Struct.new(:buffer, :first, :last, :title, :view_start, :view_end)
+    attr_reader :excerpts
+    def initialize(excerpts: [])
+      super("")
+      @excerpts, @source_subscriptions, @multi_undo, @multi_redo = [], {}, [], []
+      validate_excerpt_ranges(excerpts)
+      @building = true
+      excerpts.each { |buffer, range, title| add_excerpt(buffer, range, title: title) }
+      @building = false
+      refresh
+    end
+    def add_excerpt(buffer, range, title: nil)
+      raise Error, "excerpt source must be a regular buffer" unless buffer.is_a?(Buffer) && !buffer.is_a?(MultiBuffer)
+      ending = range.end + (range.exclude_end? ? 0 : 1)
+      buffer.rope.byteslice(range.begin, ending - range.begin)
+      overlap = !@building && @excerpts.any? do |excerpt|
+        excerpt.buffer.equal?(buffer) && range.begin <= buffer.resolve(excerpt.last) && ending >= buffer.resolve(excerpt.first)
+      end
+      raise Error, "excerpts of the same buffer must be disjoint and nonadjacent" if overlap
+      label = title || "#{buffer.path || 'Untitled'}:#{buffer.rope.point_at(range.begin).row + 1}"
+      @excerpts << Excerpt.new(buffer, buffer.anchor(range.begin, bias: :left), buffer.anchor(ending, bias: :right), label.to_s.freeze)
+      @source_subscriptions[buffer] ||= buffer.on_edit { refresh unless @syncing }
+      refresh unless @building
+      self
+    end
+
+    # Attach a privately prepared projection to live sources on the foreground
+    # thread. Source ropes must be the exact immutable snapshots used to build
+    # it; caller additionally validates workspace identity/version before this.
+    # No text rebuild, regex scan or disk IO occurs here.
+    def attach_sources(replacements)
+      raise Error, "cannot attach an edited projection" unless @multi_undo.empty? && @multi_redo.empty?
+      return self if replacements.empty?
+      replacements.each do |source, target|
+        raise Error, "unknown excerpt source" unless @source_subscriptions.key?(source)
+        raise Error, "excerpt source must be a regular buffer" unless target.is_a?(Buffer) && !target.is_a?(MultiBuffer)
+        raise Error, "source buffer is read-only" if target.read_only
+        raise Error, "excerpt source snapshot changed" unless source.rope.equal?(target.rope)
+      end
+      targets = @source_subscriptions.keys.map { |source| replacements.fetch(source, source) }
+      raise Error, "excerpt source aliases would overlap" unless targets.uniq.length == targets.length
+      anchors = []
+      subscriptions = {}
+      replacements.each do |source, target|
+        subscriptions[target] = target.on_edit { refresh unless @syncing } unless source.equal?(target)
+      end
+      @excerpts.each do |excerpt|
+        target = replacements[excerpt.buffer]
+        next unless target && !target.equal?(excerpt.buffer)
+        entry = [excerpt, target, target.copy_anchor(excerpt.buffer, excerpt.first)]
+        anchors << entry
+        entry << target.copy_anchor(excerpt.buffer, excerpt.last)
+      end
+      committed = true
+      anchors.each do |excerpt, target, first, last|
+        excerpt.buffer.release_anchor(excerpt.first)
+        excerpt.buffer.release_anchor(excerpt.last)
+        excerpt.buffer, excerpt.first, excerpt.last = target, first, last
+      end
+      @source_subscriptions = @source_subscriptions.to_h do |source, subscription|
+        target = replacements.fetch(source, source)
+        if source.equal?(target)
+          [source, subscription]
+        else
+          subscription.detach
+          [target, subscriptions.fetch(target)]
+        end
+      end
+      self
+    rescue StandardError
+      unless committed
+        subscriptions&.each_value(&:detach)
+        anchors&.each do |_, target, first, last|
+          target.release_anchor(first)
+          target.release_anchor(last) if last
+        end
+      end
+      raise
+    end
+    def dirty? = @excerpts.any? { |excerpt| excerpt.buffer.dirty? }
+    def begin_undo_group
+      @multi_undo_start = @multi_undo.length unless @undo_group_depth&.positive?
+      @excerpts.map(&:buffer).uniq.each(&:begin_undo_group)
+      super
+    end
+    def end_undo_group
+      super
+      @excerpts.map(&:buffer).uniq.each(&:end_undo_group)
+    end
+    def edit(changes, **options)
+      return super if @refreshing
+      return if changes.empty?
+      @rope.apply_edits(changes)
+      grouped = changes.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |(range, text), result|
+        ending = range.end + (range.exclude_end? ? 0 : 1)
+        excerpt = @excerpts.find { |item| range.begin >= item.view_start && ending <= item.view_end }
+        raise Error, "search-result headings cannot be edited" unless excerpt
+        raise Error, "source buffer is read-only" if excerpt.buffer.read_only
+        start = excerpt.buffer.resolve(excerpt.first)
+        result[excerpt.buffer] << [(start + range.begin - excerpt.view_start)...(start + ending - excerpt.view_start), text]
+      end
+      patches = grouped.to_h do |buffer, edits|
+        [buffer, Patch.new(buffer.rope, buffer.rope.apply_edits(edits), edits)]
+      end
+      checkpoints = grouped.keys.to_h { |buffer| [buffer, buffer.send(:edit_checkpoint)] }
+      before = grouped.keys.to_h { |buffer| [buffer, buffer.rope] }
+      @syncing = true
+      applied = []
+      begin
+        grouped.each do |buffer, edits|
+          begin
+            buffer.edit(edits, kind: :multi_buffer)
+          ensure
+            # A source may mutate and then raise. Conversely a pre-commit
+            # failure must never undo an unrelated previous source edit.
+            applied << buffer unless buffer.rope.equal?(before.fetch(buffer))
+          end
+        end
+        result = super(changes, **options)
+        rebuild_text
+        after = grouped.keys.to_h { |buffer| [buffer, buffer.rope] }
+        if @undo_group_depth&.positive? && @multi_undo.length > @multi_undo_start
+          previous = @multi_undo.last
+          previous[0] = before.merge(previous.first)
+          previous[1] = previous.last.merge(after)
+        else
+          @multi_undo << [before, after]
+        end
+        @multi_redo.clear
+        result
+      rescue StandardError
+        applied.reverse_each do |buffer|
+          buffer.send(:restore_edit, checkpoints.fetch(buffer), patches.fetch(buffer).inverse)
+        rescue StandardError
+          # Preserve the original application error, and still restore the
+          # other sources. Notification failures are isolated by Buffer.
+        end
+        raise
+      ensure
+        @syncing = false
+      end
+    end
+    def undo
+      raise Error, "end the undo group before undo" if @undo_group_depth&.positive?
+      group = @multi_undo.last
+      return false unless group
+      raise Error, "source changed since this excerpt edit" unless group.last.all? { |buffer, snapshot| buffer.rope.equal?(snapshot) }
+      @syncing = true
+      group.last.keys.reverse_each(&:undo)
+      super
+      @multi_redo << @multi_undo.pop
+      rebuild_text
+      true
+    ensure
+      @syncing = false
+    end
+    def redo
+      raise Error, "end the undo group before redo" if @undo_group_depth&.positive?
+      group = @multi_redo.last
+      return false unless group
+      raise Error, "source changed since this excerpt edit" unless group.first.all? { |buffer, snapshot| buffer.rope.equal?(snapshot) }
+      @syncing = true
+      group.first.keys.each(&:redo)
+      super
+      @multi_undo << @multi_redo.pop
+      rebuild_text
+      true
+    ensure
+      @syncing = false
+    end
+    def save(path = nil, force: false)
+      raise Error, "Save excerpt files individually to choose new paths" if path
+      @excerpts.map(&:buffer).uniq.each { |buffer| buffer.save(force: force) if buffer.dirty? }
+      self
+    end
+    def close
+      @source_subscriptions.each_value(&:detach)
+      @excerpts.each do |excerpt|
+        excerpt.buffer.release_anchor(excerpt.first)
+        excerpt.buffer.release_anchor(excerpt.last)
+      end
+    end
+
+    private
+    # Validate grouped, sorted intervals once. Repeated add_excerpt overlap
+    # scans made a 10,000-excerpt constructor quadratic in excerpt count.
+    def validate_excerpt_ranges(excerpts)
+      excerpts.group_by(&:first).each do |buffer, entries|
+        raise Error, "excerpt source must be a regular buffer" unless buffer.is_a?(Buffer) && !buffer.is_a?(MultiBuffer)
+        previous_end = nil
+        entries.sort_by { |_, range, _| range.begin }.each do |_, range, _|
+          ending = range.end + (range.exclude_end? ? 0 : 1)
+          buffer.rope.byteslice(range.begin, ending - range.begin)
+          raise Error, "excerpts of the same buffer must be disjoint and nonadjacent" if previous_end && range.begin <= previous_end
+          previous_end = ending
+        end
+      end
+    end
+
+    def rebuild_text
+      text = +""
+      @excerpts.each do |excerpt|
+        text << "#{excerpt.title}\n"
+        excerpt.view_start = text.bytesize
+        first, last = excerpt.buffer.resolve(excerpt.first), excerpt.buffer.resolve(excerpt.last)
+        text << excerpt.buffer.rope.byteslice(first...last).to_s
+        excerpt.view_end = text.bytesize
+        text << "\n\n"
+      end
+      text
+    end
+    def refresh
+      normalize_excerpts
+      text = rebuild_text
+      @refreshing = true
+      edit([[0...@rope.bytesize, text]], kind: :source_refresh)
+      @saved_rope = @rope
+      @history.clear
+      @redo.clear
+      @multi_undo.clear
+      @multi_redo.clear
+    ensure
+      @refreshing = false
+    end
+
+    # External source edits can collapse previously disjoint anchored ranges.
+    # Keep their union once, under the earliest heading, so every displayed byte
+    # still has one editable source location. No source text is discarded.
+    def normalize_excerpts
+      removed = {}.compare_by_identity
+      @excerpts.each_with_index.group_by { |excerpt, _| excerpt.buffer }.each do |buffer, values|
+        group, first, last = [], nil, nil
+        values.sort_by { |excerpt, _| buffer.resolve(excerpt.first) }.each do |entry|
+          excerpt = entry.first
+          start, ending = buffer.resolve(excerpt.first), buffer.resolve(excerpt.last)
+          if last && start > last
+            merge_excerpts(buffer, group, first, last, removed)
+            group = []
+          end
+          first = start if group.empty?
+          last = group.empty? ? ending : [last, ending].max
+          group << entry
+        end
+        merge_excerpts(buffer, group, first, last, removed)
+      end
+      @excerpts.reject! { |excerpt| removed.key?(excerpt) }
+    end
+
+    def merge_excerpts(buffer, entries, first, last, removed)
+      return if entries.length < 2
+      keeper = entries.min_by(&:last).first
+      entries.each do |excerpt, _|
+        buffer.release_anchor(excerpt.first)
+        buffer.release_anchor(excerpt.last)
+        removed[excerpt] = true unless excerpt.equal?(keeper)
+      end
+      keeper.first = buffer.anchor(first, bias: :left)
+      keeper.last = buffer.anchor(last, bias: :right)
+    end
+  end
+end

data/lib/canopus/pane.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Canopus
+  class Pane
+    attr_reader :editors, :pinned
+    attr_accessor :active_index
+    def initialize
+      @editors, @pinned, @active_index, @past, @future = [], [], 0, [], []
+    end
+    def active = @editors[@active_index]
+    def open(buffer)
+      existing = @editors.index { |editor| editor.buffer.equal?(buffer) }
+      if existing
+        activate(existing)
+      else
+        @editors << Editor.new(buffer)
+        activate(@editors.length - 1)
+      end
+      active
+    end
+    def activate(index)
+      raise IndexError, "tab outside pane" unless index.is_a?(Integer) && index.between?(0, @editors.length - 1)
+      @past << active if active && @active_index != index
+      @active_index = index
+      @future.clear
+    end
+    def pin(editor = active)
+      @pinned << editor unless @pinned.include?(editor)
+    end
+    def close(editor = active, discard: false)
+      raise Error, "buffer has unsaved changes" if editor.buffer.dirty? && !discard
+      @pinned.delete(editor)
+      @editors.delete(editor)
+      @past.delete(editor)
+      @future.delete(editor)
+      @active_index = [@active_index, @editors.length - 1].min.clamp(0, @editors.length)
+      editor.dispose
+    end
+    def detach(editor)
+      raise Error, "tab is not in pane" unless @editors.include?(editor)
+      active = self.active
+      @pinned.delete(editor)
+      @editors.delete(editor)
+      @past.delete(editor)
+      @future.delete(editor)
+      @active_index = @editors.index(active) || [@active_index, @editors.length - 1].min.clamp(0, @editors.length)
+    end
+    def back
+      previous = @past.pop
+      return unless previous && @editors.include?(previous)
+      @future << active
+      @active_index = @editors.index(previous)
+    end
+    def forward
+      following = @future.pop
+      return unless following && @editors.include?(following)
+      @past << active
+      @active_index = @editors.index(following)
+    end
+  end
+end

data/lib/canopus/patch/composite.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class Canopus::Patch::Composite
+  attr_reader :patches
+  def initialize(patches) = @patches = patches.freeze
+  def before = patches.first.before
+  def after = patches.last.after
+  def edits = patches.flat_map(&:edits)
+  def map_offset(offset, bias: :right) = patches.reduce(offset) { |position, patch| patch.map_offset(position, bias: bias) }
+  def inverse = self.class.new(patches.reverse.map(&:inverse))
+  def compose(other) = self.class.new([*patches, other])
+end