canopus 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7542ff6c8bf489ddfdb978f292d32778cc450b57d64035d94ef67797901b1545
-  data.tar.gz: 2a7f330905efe963d94d303c953f4d1b4ae8da51a0b409720b6c1cfbccf837a6
+  metadata.gz: 64a5ffb35c2d8fdfbc91881be747cdf0882548d2e924aa04846f333e23a73487
+  data.tar.gz: 17a825bf14afce060db1589fc6cb13986e0e7857a1d28622b99f1125d83de484
 SHA512:
-  metadata.gz: d62037a03bb3753cddd8551d88d33f59760500f6c9680b2ae4cb284b26a11de43c1c17ea9f9e437b890e722494b83702f7666d61df76d99045d6242e8cab852e
-  data.tar.gz: ec60287bf355093ace58c7d24fb0805e37a207d457bbce3eae09087d03bdaa4748742d37d4e98570095bb52f55ffa01c1b78aecb600ae4699966d8101f383471
+  metadata.gz: c499a3d6b07424ef0d696df9ae842eabc81ef6265aa251b3e32f22c20c1ab70be30e1a9df56351cbd182f7d11bc05e536726429e53a1adc57ce2a5729df37043
+  data.tar.gz: d1212a4befda0c26dee61f60de0a74c4a1d729b37806eccf99198d52045dbbdd6d43c493eaf33ebf0635892d9eae9b6773dd349e9bc40d031d5863a36b949b30

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0 — 2026-09-15
+
+- Route commands and keybindings through one context-aware command registry.
+- Register the explorer, project search, terminal, and plugin panels through one stateful panel registry.
+- Supply Git gutter marks and selection highlights through the decoration registry.
+- Include inline and block decorations in wrapping, display coordinates, hit testing, and generic rendering.
+- Expose rendered panels, badges, and decorations through stable UI test identifiers.
+
 ## 0.3.0 — 2026-09-14
 
 - Use the public `Thuban::IgnoreMatcher` and remove Canopus's duplicate implementation.

data/README.md

@@ -39,6 +39,8 @@ installable.
 - Editable project-wide search results and safe project file operations
 - Optional Vim-compatible modes, motions, operators, registers, macros, and Ex commands
 - Layered JSONC settings, keymaps, themes, snippets, and trusted Ruby plugins
+- Overlay-aware wrapping and coordinates for inline hints and block decorations
+- Rendered panel and decoration nodes expose stable `test_id` conventions for UI tests
 
 ## Installation
 
@@ -109,7 +111,10 @@ settings live at `$XDG_CONFIG_HOME/canopus/settings.jsonc` or
   "use_tabs": false,
   "tabs": { "activate_on_close": "history", "reopen_history_limit": 20 },
   "terminal": { "working_directory": "project", "scrollback_lines": 10000 },
-  "dock": { "bottom": { "size": 280, "visible": false } },
+  "dock": {
+    "bottom": { "size": 280, "visible": false },
+    "panels": { "terminal": { "size": 280, "visible": false } }
+  },
   "keymap": [
     { "context": "Editor && !vim_mode", "bindings": { "ctrl-k ctrl-s": "file.save" } }
   ],
@@ -120,7 +125,8 @@ settings live at `$XDG_CONFIG_HOME/canopus/settings.jsonc` or
 
 Closing a dirty tab asks whether to save, discard, or cancel. Reopening restores
 the file, selections, position, and pane while Canopus is running; discarded
-unsaved changes are never restored. Terminal session restoration, when enabled,
+unsaved changes are never restored. Dock and panel visibility and sizes are also
+restored. Terminal session restoration, when enabled,
 starts fresh shells with the saved tab count and working directories and does
 not restore processes or scrollback.
 

data/docs/adr/008-component-domain-boundaries.md

@@ -0,0 +1,26 @@
+# ADR 008: Keep one domain in each component repository
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+New editor capabilities can live in Canopus, extend an existing component, or
+become another independently released gem. Splitting by individual protocol
+operation would create small packages that expose each other's internal models;
+keeping every capability in Canopus would couple unrelated release cycles.
+
+## Decision
+
+Keep one externally specified or independently testable domain in each
+component repository. Extend an existing component when its internal model is
+required, and keep product UX and cross-component state ownership in Canopus.
+Canopus consumes components through released gems and does not copy their
+sources into its repository.
+
+## Consequences
+
+Component APIs and release order remain explicit, and each domain can be tested
+headlessly. Coordinated changes require publishing the provider before updating
+Canopus. Revisit a split when two components must expose private models to each
+other or routinely require lockstep releases.

data/docs/adr/009-decoration-overlay-path.md

@@ -0,0 +1,26 @@
+# ADR 009: Supply editor overlays through one decoration path
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+Git marks and selections were painted directly by the editor view. Diagnostics,
+inlay hints, code lenses, debugger state, and plugin overlays would each add
+another provider-specific branch to that view. Letting providers draw directly
+would also mix invalidation and data ownership with viewport rendering.
+
+## Decision
+
+Providers register bounded suppliers with `Decoration::Registry`. The registry
+owns source identity, ordering, caching, and invalidation. The view asks the
+registry for the current row range and renders items by decoration kind; click
+handlers return through the controller without embedding provider behavior in
+the renderer.
+
+## Consequences
+
+Future overlays share one rendering and invalidation boundary, while providers
+stay independent of scene construction. The registry contract becomes a public
+internal extension point, and display-coordinate-changing inline and block
+items still require a separate overlay-aware display map.

data/docs/adr/010-overlay-aware-display-map.md

@@ -0,0 +1,32 @@
+# ADR 010: Apply overlays before display wrapping
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+Inline hints occupy space without adding editable buffer bytes, and block
+decorations add vertical space without adding source lines. Painting either
+after display mapping makes wrapping, cursor placement, selections, and hit
+testing disagree with what the user sees. Embedding provider-specific layout in
+the workspace view would also bypass the decoration boundary from ADR 009.
+
+## Decision
+
+Make `OverlayMap` a display-map stage and keep the stage order `fold → overlay
+→ wrap → tab → block`. The wrap stage accounts for inline width measured from
+the active Alhena font, while the final tab projection preserves established
+tab-stop output. Block height is represented by non-selectable display rows.
+The generic view renders their content through Zaniah text overlays and routes
+clicks through the existing decoration action.
+
+Rendered panels, badges, inline overlays, gutter markers, and line highlights
+also carry Syrma's public test identifiers. They remain real Zaniah nodes with
+their painted bounds; Canopus does not depend on the test driver at runtime.
+
+## Consequences
+
+Buffer offsets remain the only editable coordinates, so overlay content cannot
+enter a selection. Changing one decoration rebuilds only its source row. A
+block height is rounded up to whole editor rows; sub-row scrolling would require
+a pixel-based vertical display coordinate model.

data/lib/canopus/command.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Canopus
+  module Command
+    Definition = Data.define(:id, :title, :category, :when, :run, :keybinding)
+
+    DEFAULT_KEYBINDINGS = {
+      "file.save" => {"cmd-s" => "", "ctrl-s" => ""}.freeze,
+      "file.new" => {"cmd-n" => "", "ctrl-n" => ""}.freeze,
+      "tab.close" => {"cmd-w" => "", "ctrl-w" => ""}.freeze,
+      "tab.close_all" => {"cmd-alt-w" => "", "ctrl-alt-w" => ""}.freeze,
+      "tab.reopen_closed" => {"cmd-shift-t" => "", "ctrl-shift-t" => ""}.freeze,
+      "file.find" => {"cmd-p" => "", "ctrl-p" => ""}.freeze,
+      "command.palette" => {"cmd-shift-p" => "", "ctrl-shift-p" => ""}.freeze,
+      "edit.undo" => {"cmd-z" => "", "ctrl-z" => ""}.freeze,
+      "edit.redo" => {"cmd-shift-z" => "", "ctrl-shift-z" => ""}.freeze,
+      "edit.select_all" => {"cmd-a" => "", "ctrl-a" => ""}.freeze,
+      "edit.select_next" => {"cmd-d" => "", "ctrl-d" => ""}.freeze,
+      "search.buffer" => {"cmd-f" => "", "ctrl-f" => ""}.freeze,
+      "edit.select_all_occurrences" => {"cmd-shift-l" => "", "ctrl-shift-l" => ""}.freeze,
+      "edit.move_line_up" => {"alt-up" => ""}.freeze,
+      "edit.move_line_down" => {"alt-down" => ""}.freeze,
+      "search.project" => {"cmd-shift-f" => "", "ctrl-shift-f" => ""}.freeze,
+      "search.replace" => {"cmd-alt-f" => "", "ctrl-h" => ""}.freeze,
+      "edit.toggle_comment" => {"cmd-/" => "", "ctrl-/" => ""}.freeze,
+      "view.project" => {"cmd-b" => "", "ctrl-b" => ""}.freeze,
+      "view.terminal" => {"ctrl-`" => ""}.freeze,
+      "pane.split_right" => {"cmd-\\" => "", "ctrl-\\" => ""}.freeze,
+      "language.completion" => {"ctrl-space" => ""}.freeze,
+      "language.definition" => {"f12" => ""}.freeze,
+      "language.references" => {"shift-f12" => ""}.freeze,
+      "language.rename" => {"f2" => ""}.freeze,
+      "language.codeAction" => {"alt-enter" => ""}.freeze,
+      "language.outline" => {"cmd-shift-o" => "", "ctrl-shift-o" => ""}.freeze,
+      "language.hover" => {"cmd-k" => "", "ctrl-k" => ""}.freeze,
+      "terminal.toggle" => {"ctrl-`" => "Terminal"}.freeze,
+      "terminal.new" => {"ctrl-shift-`" => ""}.freeze,
+      "terminal.close" => {"cmd-w" => "Terminal", "ctrl-w" => "Terminal"}.freeze,
+      "terminal.copy" => {"cmd-c" => "Terminal", "ctrl-shift-c" => "Terminal"}.freeze,
+      "terminal.paste" => {"cmd-v" => "Terminal", "ctrl-shift-v" => "Terminal"}.freeze,
+      "terminal.next" => {"ctrl-shift-]" => "Terminal"}.freeze,
+      "terminal.prev" => {"ctrl-shift-[" => "Terminal"}.freeze,
+      "terminal.clear" => {"cmd-k" => "Terminal"}.freeze,
+      **(1..9).to_h { |index| ["terminal.select_#{index}", {"cmd-#{index}" => "Terminal"}.freeze] }
+    }.freeze
+
+    class Registry
+      attr_reader :version
+
+      def initialize
+        @definitions, @predicates, @version = {}, {}, 0
+      end
+
+      def register(definition, description: definition.to_s, category: definition.to_s.split(".", 2).first,
+        condition: "", keybinding: nil, &run)
+        definition = Definition.new(definition.to_s, description, category, condition, run, keybinding) unless definition.is_a?(Definition)
+        definition = normalize(definition)
+        predicate = Zaniah::Input::ContextPredicate.new(definition.when)
+        @definitions[definition.id] = definition
+        @predicates[definition.id] = predicate
+        @version += 1
+        definition
+      end
+
+      def resolve(id, context: {})
+        id = id.to_s
+        definition = @definitions[id]
+        definition if definition && @predicates.fetch(id).call(context)
+      end
+
+      def call(id, *arguments, context: {})
+        definition = resolve(id, context: context)
+        raise KeyError, "command unavailable: #{id}" unless definition
+        definition.run.call(*arguments)
+      end
+
+      def each(context: nil)
+        return enum_for(__method__, context: context) unless block_given?
+        @definitions.each_value { |definition| yield definition if context.nil? || resolve(definition.id, context: context) }
+        self
+      end
+
+      def entries(context: nil) = each(context: context).to_h { |definition| [definition.id, definition.title] }.freeze
+
+      private
+
+      def normalize(definition)
+        raise ArgumentError, "command definition required" unless definition.is_a?(Definition)
+        id, title, category, condition, run, keybinding = definition.deconstruct
+        raise ArgumentError, "command id must not be empty" unless id.is_a?(String) && !id.empty?
+        raise ArgumentError, "command title must be a string" unless title.is_a?(String)
+        raise ArgumentError, "command category must be a string" unless category.is_a?(String)
+        raise ArgumentError, "command condition must be a string" unless condition.is_a?(String)
+        raise ArgumentError, "command runner must be callable" unless run.respond_to?(:call)
+        keybinding = normalize_keybinding(keybinding)
+        Definition.new(id.dup.freeze, title.dup.freeze, category.dup.freeze, condition.dup.freeze, run, keybinding)
+      end
+
+      def normalize_keybinding(keybinding)
+        return if keybinding.nil?
+        return keybinding.dup.freeze if keybinding.is_a?(String) && !keybinding.empty?
+        unless keybinding.is_a?(Hash) && keybinding.all? { |keys, condition| keys.is_a?(String) && !keys.empty? && condition.is_a?(String) }
+          raise ArgumentError, "command keybinding must be a string, binding map, or nil"
+        end
+        keybinding.to_h { |keys, condition| [keys.dup.freeze, condition.dup.freeze] }.freeze
+      end
+    end
+  end
+end

data/lib/canopus/controller.rb

@@ -4,29 +4,14 @@ require_relative "workspace/view"
 
 module Canopus
   class Controller
-    SHORTCUTS = {"cmd-s" => "file.save", "ctrl-s" => "file.save", "cmd-n" => "file.new", "ctrl-n" => "file.new",
-      "cmd-w" => "tab.close", "ctrl-w" => "tab.close", "cmd-alt-w" => "tab.close_all", "ctrl-alt-w" => "tab.close_all",
-      "cmd-shift-t" => "tab.reopen_closed", "ctrl-shift-t" => "tab.reopen_closed", "cmd-p" => "file.find", "ctrl-p" => "file.find",
-      "cmd-shift-p" => "command.palette", "ctrl-shift-p" => "command.palette", "cmd-z" => "edit.undo", "ctrl-z" => "edit.undo",
-      "cmd-shift-z" => "edit.redo", "ctrl-shift-z" => "edit.redo", "cmd-a" => "edit.select_all", "ctrl-a" => "edit.select_all",
-      "cmd-d" => "edit.select_next", "ctrl-d" => "edit.select_next", "cmd-f" => "search.buffer", "ctrl-f" => "search.buffer",
-      "cmd-shift-l" => "edit.select_all_occurrences", "ctrl-shift-l" => "edit.select_all_occurrences",
-      "alt-up" => "edit.move_line_up", "alt-down" => "edit.move_line_down",
-      "cmd-shift-f" => "search.project", "ctrl-shift-f" => "search.project", "cmd-alt-f" => "search.replace", "ctrl-h" => "search.replace",
-      "cmd-/" => "edit.toggle_comment", "ctrl-/" => "edit.toggle_comment", "cmd-b" => "view.project", "ctrl-b" => "view.project",
-      "ctrl-`" => "view.terminal", "ctrl-shift-`" => "terminal.new", "cmd-\\" => "pane.split_right", "ctrl-\\" => "pane.split_right",
-      "ctrl-space" => "language.completion", "f12" => "language.definition", "shift-f12" => "language.references",
-      "f2" => "language.rename", "alt-enter" => "language.codeAction", "cmd-shift-o" => "language.outline",
-      "ctrl-shift-o" => "language.outline", "cmd-k" => "language.hover", "ctrl-k" => "language.hover"}.freeze
-    TERMINAL_SHORTCUTS = {"ctrl-`" => "terminal.toggle", "ctrl-shift-`" => "terminal.new", "cmd-w" => "terminal.close",
-      "ctrl-w" => "terminal.close", "cmd-c" => "terminal.copy", "ctrl-shift-c" => "terminal.copy",
-      "cmd-v" => "terminal.paste", "ctrl-shift-v" => "terminal.paste", "cmd-shift-p" => "command.palette",
-      "ctrl-shift-p" => "command.palette", "ctrl-shift-]" => "terminal.next", "ctrl-shift-[" => "terminal.prev",
-      "cmd-k" => "terminal.clear"}.merge((1..9).to_h { |index| ["cmd-#{index}", "terminal.select_#{index}"] }).freeze
     attr_reader :workspace, :view, :window, :keymap
     def initialize(workspace, window)
       @workspace, @window, @view = workspace, window, Workspace::View.new(workspace)
       workspace.window = window
+      workspace.register_action("terminal.copy", condition: "Terminal") { terminal_copy }
+      workspace.register_action("terminal.paste", condition: "Terminal") do
+        terminal_paste(@window.respond_to?(:clipboard) ? @window.clipboard.to_s : @clipboard)
+      end
       reload_keymap
       window.draw { workspace.drain; @view }
       window.on_input { |event| input(event) }
@@ -167,23 +152,15 @@ module Canopus
           return @workspace.restart_terminal
         end
         mode = @workspace.settings["vim_mode"] && @workspace.editor ? @workspace.vim.mode.to_s : false
-        action = @keymap.dispatch(stroke, context: {"Terminal" => true, "Editor" => false, "vim_mode" => mode})
+        context = @workspace.command_context(terminal: true).merge("Editor" => false, "vim_mode" => mode)
+        action = @keymap.dispatch(stroke, context: context)
         if action && action != :pending
-          if action == "terminal.paste"
-            return terminal_paste(@window.respond_to?(:clipboard) ? @window.clipboard.to_s : @clipboard)
-          elsif action == "terminal.copy"
-            @clipboard = @view.terminal_selected_text
-            @window.clipboard = @clipboard if @window.respond_to?(:clipboard=)
-            return
-          end
           @drag_terminal_tab = nil if action == "terminal.close"
-          return @workspace.call(action)
+          return @workspace.call(action, context: context)
         elsif action == :pending
           return
         elsif ["cmd-c", "ctrl-shift-c"].include?(stroke)
-          @clipboard = @view.terminal_selected_text
-          @window.clipboard = @clipboard if @window.respond_to?(:clipboard=)
-          return
+          return terminal_copy
         end
         parts = stroke.split("-")
         name = parts.pop
@@ -193,13 +170,14 @@ module Canopus
       end
       return @workspace.settings_completions if stroke == "ctrl-space" && @workspace.editor && @workspace.settings_document?(@workspace.editor.buffer)
       mode = @workspace.settings["vim_mode"] && @workspace.editor ? @workspace.vim.mode.to_s : false
-      action = @keymap.dispatch(stroke, context: {"Editor" => !!@workspace.editor, "vim_mode" => mode})
+      context = @workspace.command_context.merge("vim_mode" => mode)
+      action = @keymap.dispatch(stroke, context: context)
       if action
         # Native adapters deliver text separately after printable key down.
         # Cocoa also sends an empty Composition before that ordinary commit.
         @suppress_key_text = stroke.match?(/\A(?:(?:alt|shift)-)*(?:space|[^\x00-\x1f\x7f])\z/)
         @drag_tab = nil if action.to_s.start_with?("tab.close") || action == "pane.close"
-        return action == :pending ? nil : @workspace.call(action)
+        return action == :pending ? nil : @workspace.call(action, context: context)
       end
       if ["cmd-c", "ctrl-c", "cmd-x", "ctrl-x", "cmd-v", "ctrl-v"].include?(stroke) && !(@workspace.settings["vim_mode"] && stroke == "ctrl-v")
         return clipboard(stroke.split("-").last)
@@ -325,11 +303,16 @@ module Canopus
     def reload_keymap
       language = @workspace.editor&.language_document&.definition&.name
       groups = @workspace.settings["languages"].dig(language, "keymap") || @workspace.settings["keymap"]
-      return if @keymap_groups.equal?(groups)
-      unless @keymap_groups == groups
+      return if @keymap_groups.equal?(groups) && @command_version == @workspace.commands.version
+      unless @keymap_groups == groups && @command_version == @workspace.commands.version
         replacement = Zaniah::Input::Keymap.new
-        SHORTCUTS.each { |keys, action| replacement.bind(keys, action) }
-        TERMINAL_SHORTCUTS.each { |keys, action| replacement.bind(keys, action, context: "Terminal") }
+        @workspace.commands.each do |definition|
+          bindings = definition.keybinding.is_a?(String) ? {definition.keybinding => ""} : definition.keybinding || {}
+          bindings.each do |keys, binding_context|
+            condition = [definition.when, binding_context].reject(&:empty?).map { |value| "(#{value})" }.join(" && ")
+            replacement.bind(keys, definition.id, context: condition)
+          end
+        end
         groups.each do |group|
           group.fetch("bindings").each { |keys, action| replacement.bind(keys, action, context: group.fetch("context")) }
         end
@@ -337,6 +320,7 @@ module Canopus
         @view.keymap = replacement
       end
       @keymap_groups = groups
+      @command_version = @workspace.commands.version
     end
     def palette_input(event)
       return false unless @workspace.palette
@@ -445,12 +429,15 @@ module Canopus
         @workspace.selected_project_path = args.first
         @drag_file = [args.first, event.position] if event.button == :left
         if event.button == :right
-          @workspace.palette = {kind: :commands, query: +"", index: 0, matches: %w[project.new_file project.new_folder project.rename project.trash]}
+          @workspace.palette_open(:commands, command_ids: %w[project.new_file project.new_folder project.rename project.trash],
+            context: @workspace.command_context)
           return
         end
       end
       @terminal_focus = [:terminal, :terminal_tab, :terminal_close].include?(kind)
       case kind
+      when :decoration
+        args[0].call(args[1], args[2]) if event.button == :left
       when :git_hunk then @workspace.toggle_git_hunk(args[0], row: args[1]) if event.button == :left
       when :hover_link
         return unless event.button == :left
@@ -567,6 +554,10 @@ module Canopus
         @workspace.terminal.paste(text)
       end
     end
+    def terminal_copy
+      @clipboard = @view.terminal_selected_text
+      @window.clipboard = @clipboard if @window.respond_to?(:clipboard=)
+    end
     def resize_drag(point)
       kind, target, bounds = @resize_drag
       if kind == :split_resize
@@ -578,7 +569,7 @@ module Canopus
         when :right then bounds.right - point.x
         when :bottom then bounds.bottom - 26 - point.y
         end
-        @workspace.docks[target][:size] = size.clamp(80, target == :bottom ? bounds.height * 0.7 : bounds.width * 0.4)
+        @workspace.panels.resize(target, size.clamp(80, target == :bottom ? bounds.height * 0.7 : bounds.width * 0.4))
       end
     end
   end

data/lib/canopus/decoration.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Canopus
+  module Decoration
+    KINDS = %i[inline block gutter highlight line].freeze
+    Item = Data.define(:kind, :range, :row, :content, :style, :priority, :source, :on_click)
+
+    class Registry
+      CACHE_LIMIT = 256
+
+      attr_reader :version
+
+      def initialize
+        @suppliers, @generations, @cache = {}, Hash.new(0), {}
+        @lock, @version = Mutex.new, 0
+      end
+
+      def register(source, &supplier)
+        raise ArgumentError, "decoration supplier required" unless supplier
+
+        source = normalize_source(source)
+        @lock.synchronize do
+          @suppliers[source] = supplier
+          invalidate_locked(source)
+        end
+        source
+      end
+
+      def unregister(source)
+        source = normalize_source(source)
+        @lock.synchronize do
+          supplier = @suppliers.delete(source)
+          invalidate_locked(source) if supplier
+          supplier
+        end
+      end
+
+      def items_for(buffer, row_range, context: nil)
+        first, last = normalize_rows(row_range)
+        state = [buffer.respond_to?(:version) ? buffer.version : nil,
+          context&.object_id,
+          context&.respond_to?(:selections) ? context.selections : buffer.respond_to?(:selections) ? buffer.selections : nil]
+        suppliers = @lock.synchronize do
+          @suppliers.map { |source, supplier| [source, supplier, @generations[source]] }
+        end
+        items = suppliers.flat_map do |source, supplier, generation|
+          key = [source, buffer.object_id, state, first, last]
+          cached = @lock.synchronize { @cache[key] }
+          next cached if cached
+
+          supplied = if supplier.arity == 2
+            supplier.call(buffer, first...last)
+          else
+            supplier.call(buffer, first...last, context)
+          end
+          raise TypeError, "decoration supplier must return an array" unless supplied.is_a?(Array)
+          supplied = supplied.map { |item| normalize_item(item, source) }.freeze
+          @lock.synchronize do
+            if @suppliers[source].equal?(supplier) && @generations[source] == generation
+              @cache.shift while @cache.length >= CACHE_LIMIT
+              @cache[key] = supplied
+            end
+          end
+          supplied
+        end
+        items.sort_by { |item| item.priority }.freeze
+      end
+
+      def invalidate(source, buffer: nil, rows: nil)
+        source = normalize_source(source)
+        row_bounds = normalize_rows(rows) if rows
+        @lock.synchronize do
+          @version += 1
+          @generations[source] += 1
+          if buffer || row_bounds
+            @cache.delete_if do |key, _|
+              same_source = key[0] == source
+              same_buffer = !buffer || key[1] == buffer.object_id
+              overlaps = !row_bounds || (key[3] < row_bounds[1] && row_bounds[0] < key[4])
+              same_source && same_buffer && overlaps
+            end
+          else
+            @cache.delete_if { |key, _| key[0] == source }
+          end
+        end
+        nil
+      end
+
+      private
+
+      def invalidate_locked(source)
+        @generations[source] += 1
+        @version += 1
+        @cache.delete_if { |key, _| key[0] == source }
+      end
+
+      def normalize_source(source)
+        valid = source.is_a?(Symbol) && !source.to_s.empty? && !source.to_s.include?(":") &&
+          !source.to_s.match?(/[\x00-\x1f\x7f]/)
+        raise ArgumentError, "invalid decoration source" unless valid
+
+        source
+      end
+
+      def normalize_rows(rows)
+        unless rows.is_a?(Range) && rows.begin.is_a?(Integer) && rows.end.is_a?(Integer) && rows.begin >= 0
+          raise ArgumentError, "decoration rows must be a nonnegative integer range"
+        end
+        last = rows.exclude_end? ? rows.end : rows.end + 1
+        raise ArgumentError, "decoration row range is reversed" if last < rows.begin
+
+        [rows.begin, last]
+      end
+
+      def normalize_item(item, source)
+        raise TypeError, "decoration supplier must return items" unless item.is_a?(Item)
+        raise ArgumentError, "invalid decoration kind" unless KINDS.include?(item.kind)
+        unless item.priority.is_a?(Numeric) && item.priority.finite?
+          raise ArgumentError, "decoration priority must be finite"
+        end
+        unless item.row.nil? || (item.row.is_a?(Integer) && item.row >= 0)
+          raise ArgumentError, "decoration row must be nonnegative"
+        end
+        unless item.range.nil? || (item.range.is_a?(Range) && item.range.begin.is_a?(Integer) && item.range.end.is_a?(Integer))
+          raise ArgumentError, "decoration range must contain integer offsets"
+        end
+        raise ArgumentError, "decoration click handler must be callable" unless item.on_click.nil? || item.on_click.respond_to?(:call)
+        item.source == source ? item : item.with(source: source)
+      end
+    end
+  end
+end

data/lib/canopus/display_map/line_builder.rb

@@ -11,8 +11,9 @@ class Canopus::DisplayMap::LineBuilder
   private_constant :EMPTY_LINES, :Row, :LineSet, :PendingLineSet, :UNWRAPPED_LINE
 
   attr_reader :rope, :fold, :blocks
-  def initialize(rope, fold, tab, wrap, blocks)
+  def initialize(rope, fold, overlay, tab, wrap, blocks)
     @rope, @tab, @wrap = rope, tab, wrap
+    @overlay = overlay.snapshot
     @fold = Canopus::FoldMap.new
     @fold.instance_variable_set(:@ranges, fold.ranges.dup.freeze)
     @fold.freeze
@@ -25,9 +26,17 @@ class Canopus::DisplayMap::LineBuilder
   def line(row, provisional: false, from: 0, checkpoint: nil)
     input = @fold.transform(@rope, row, max_bytes: provisional ? 16_384 : nil, from: from, checkpoint: checkpoint)
     return EMPTY_LINES unless input
-    text, offsets = @tab.transform(*input, checkpoint: checkpoint)
-    wrapped = provisional ? [[text.freeze, offsets.freeze]] : @wrap.transform(text, offsets, checkpoint: checkpoint)
-    rows = wrapped.map { |value, positions| Row.new(value, positions, :text, nil) }
+    text, offsets = input
+    overlays = @overlay.transform(@rope, row, text, offsets)
+    wrapped = provisional ? [[text.freeze, offsets.freeze, overlays]] : @wrap.transform(text, offsets,
+      checkpoint: checkpoint, overlays: overlays, tab_map: @tab)
+    rows = wrapped.map do |value, positions, placements|
+      placements ||= []
+      value, positions, placements = @tab.transform(value, positions, checkpoint: checkpoint, overlays: placements) if provisional && !placements.empty?
+      value, positions = @tab.transform(value, positions, checkpoint: checkpoint) if provisional && placements.empty?
+      Row.new(value.freeze, positions.freeze, :text, placements.empty? ? nil : placements)
+    end
+    rows = overlay_blocks(row, :above) + rows + overlay_blocks(row, :below)
     (@blocks[row] || []).each do |block|
       block.text.split("\n", -1).each do |value|
         checkpoint&.call
@@ -46,9 +55,20 @@ class Canopus::DisplayMap::LineBuilder
       if hidden[pointer]&.cover?(row)
         EMPTY_LINES
       else
-        count = 1 + (@blocks[row] || []).sum { |block| block.text.count("\n") + 1 }
+        count = 1 + %i[above below].sum { |position| @overlay.blocks(row, position).sum(&:row_span) } +
+          (@blocks[row] || []).sum { |block| block.text.count("\n") + 1 }
         count == 1 ? UNWRAPPED_LINE : PendingLineSet.new(count)
       end
     end
   end
+
+  private
+
+  def overlay_blocks(row, position)
+    @overlay.blocks(row, position).flat_map do |block|
+      anchor = position == :above ? 0 : @rope.line(row).bytesize
+      [Row.new("".freeze, [anchor].freeze, :overlay_block, block)] +
+        Array.new(block.row_span - 1) { Row.new("".freeze, [anchor].freeze, :overlay_block_continuation, nil) }
+    end
+  end
 end