canopus 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64a5ffb35c2d8fdfbc91881be747cdf0882548d2e924aa04846f333e23a73487
-  data.tar.gz: 17a825bf14afce060db1589fc6cb13986e0e7857a1d28622b99f1125d83de484
+  metadata.gz: dac47b89af1ba7edf042a4fadccd34541f9d5911398fa083e503171df18fe387
+  data.tar.gz: 659e1e6e40f34404ab9d31c8a106792051e8f255e7195b806189124b63d661a9
 SHA512:
-  metadata.gz: c499a3d6b07424ef0d696df9ae842eabc81ef6265aa251b3e32f22c20c1ab70be30e1a9df56351cbd182f7d11bc05e536726429e53a1adc57ce2a5729df37043
-  data.tar.gz: d1212a4befda0c26dee61f60de0a74c4a1d729b37806eccf99198d52045dbbdd6d43c493eaf33ebf0635892d9eae9b6773dd349e9bc40d031d5863a36b949b30
+  metadata.gz: b6a72df6cb9b0846584044cb6f480003f50452c170f54f14aff7b1a53b4801c2824d1acfb4e5f0a2e2e3d16a10631dad64e4f57be5d76ee3a9b567e83b0ecf34
+  data.tar.gz: 2b447543c35849039cdf37b2a2bd78dbe10b57be8fee85468059c1bcb503ef8ce1fc9aace832d07c148d22dd0892f2931e6413ed67c54767ce20e341d525953c

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.0 — 2026-09-19
+
+- Configure automatic pairs and selection surrounding globally or per language without affecting paste, completion, or Vim insertion.
+
+- Add command-palette actions for cursors at every selected line start or end and selections for every regular-expression match.
+
+- Add rectangular Alt-drag selection and Ctrl-Alt-Up/Down cursor insertion across wrapped Unicode text.
+
+- Track shell commands and working directories through Tarazed OSC 133/7 integration, fold output, show exit status, and navigate command boundaries or failed commands.
+- Split the terminal panel horizontally or vertically, restore its layout and profiles, and inject editor integration variables.
+- Add `--wait` for blocking editor invocations such as `EDITOR="canopus --wait"`.
+- Periodically save bounded private snapshots of dirty buffers and offer valid crash recovery on the next startup.
+- Require Zaniah 0.5.2 so equal-position inline overlays preserve source order on every platform.
+- Delegate language-server protocol transport and lifecycle handling to Sadr.
+- Delegate terminal emulation and POSIX/Windows PTY handling to Tarazed; the editor UI is unchanged.
+- Delegate project walking and content search to Alkaid while retaining Canopus's search and replace UI.
+- Show language-server diagnostics as severity-colored wave underlines and optional line-end messages.
+- Collect LSP, task, and test diagnostics in one bounded registry with a filterable Problems panel and status counts.
+- Run opt-in formatting and configured source actions before saving without letting language-server failures block the write.
+- Route each language through ordered language servers, aggregate completion, diagnostics, and code actions, and restart individual servers.
+- Search symbols from every active routed language server with Cmd-T/Ctrl-T and fall back to bounded Alkaid project search.
+- Load bounded JSONC debug configurations, expand explicit launch variables, and resolve configured adapters.
+- Persist bounded conditional breakpoints with coalesced writes and keep their lines aligned through edits, undo, and redo.
+- Toggle breakpoints from the gutter and edit conditions, hit counts, log messages, and enabled state from its context menu.
+- Start Megrez-backed debug sessions, configure enabled breakpoints, and highlight safe workspace stop locations.
+- Browse stack frames, lazily expand fresh variable paths, reevaluate watches, and list breakpoints in the Debug panel.
+- Evaluate selected-frame REPL and hover expressions and show bounded, ordered adapter output in the Debug Console.
+- Run bounded JSONC project tasks through Tarazed PTYs in interactive, color-preserving Output tabs.
+- Publish bounded single-line, multi-line, and watch task problem matches through the shared diagnostics registry.
+- Keep regex-backed task diagnostics responsive on Ruby 3.1 with one deferred complete-line retry before fail-closed disabling.
+- Discover bounded Minitest and RSpec declarations with Alkaid and Prism and browse them in the Tests panel.
+- Run discovered tests from the gutter, display bounded results, and publish navigable failure diagnostics.
+- Preserve registration order for equal-priority decorations across Ruby versions and platforms.
+- Show cached, viewport-scoped language-server inlay hints inline with clickable label locations.
+- Show cached language-server code lenses above source lines and resolve them only when visible.
+- Highlight language-server read, write, and text occurrences for each visible editor caret.
+- Prefer language-server folding ranges with asynchronous Antares structure fallback.
+- Expand and shrink multiple selections from language-server ranges or asynchronous Antares structure data.
+- Validate rename targets asynchronously before opening the dialog when the language server supports preparation.
+- Underline and safely open language-server document links, resolving targets only when clicked.
+- Turn validated language-server linked ranges into multiple selections from the command palette, with a bounded HTML/XML tag fallback.
+- Browse call and type hierarchies in a lazily loaded side panel.
+- Color nested bracket pairs from Antares structure data and draw display-aware active indentation guides.
+- Render configurable space, tab, and ideographic-space markers without changing display coordinates.
+- Keep the active declaration chain visible with cached LSP symbols and an Antares fallback.
+- Navigate files and the cached declaration hierarchy from editor breadcrumbs.
+- Add an opt-in GUI minimap with shared, edit-aware line textures and Git, search, and diagnostic overview marks.
+- Route LSP, snippet, and extension completion through a bounded provider registry with stable fuzzy ranking.
+- Stage Git files, hunks, and lines and create or amend commits from the Source Control panel.
+- Compare Git changes and revisions inline or side by side, with word highlights and per-file history.
+- Resolve text merge regions in base/ours/theirs panes, stage the completed file atomically, and advance to the next conflict.
+- Browse and search bounded commit graphs, run cancellable authenticated remote transfers, and show cached inline blame on clean or edited buffers.
+
 ## 0.4.0 — 2026-09-15
 
 - Route commands and keybindings through one context-aware command registry.

data/README.md

@@ -33,9 +33,25 @@ installable.
 
 - Native GPU windows on macOS, Linux, and Windows, plus TUI and headless modes
 - Persistent buffers, tabs, splits, sessions, and explicit save-conflict handling
-- LSP completion, diagnostics, hover, symbols, formatting, rename, and code actions
-- Resizable integrated terminal with multiple tabs, scrollback, selection, colors, and clickable links
-- Git diff, blame, hunk reversal, and branch switching
+- LSP completion, diagnostics, hover, document and workspace symbols, formatting, prevalidated rename, and code actions
+- Bounded debug console output, stopped-frame REPL evaluation, and safe identifier hover evaluation
+- Filterable Problems tree for LSP, task, and test diagnostics, with error and warning status counts
+- Automatic read, write, and text highlights for the symbol at each visible editor's caret
+- Clickable LSP document links with on-demand resolution and safe HTTP or local-file navigation
+- LSP folding ranges with an asynchronous Antares fallback
+- LSP-aware selection expansion with an asynchronous Antares fallback
+- LSP linked-range selection for starting a multi-cursor edit from the command palette
+- Rectangular selection with Alt-drag and vertical cursor insertion
+- Multi-cursor expansion to selected line starts, line ends, or every regular-expression match
+- Lazy call and type hierarchy trees with bidirectional navigation
+- Menkar-based encoding detection, newline display and conversion, and encoding-aware saves
+- Ranked, extensible completion and inline-completion provider registry
+- Viewport-scoped LSP inlay hints with clickable label locations
+- Nested bracket colors and active indentation guides backed by Antares structure analysis
+- Optional GPU minimap with shared line textures, viewport navigation, and overview markers
+- Resizable integrated terminal with tabs, horizontal/vertical splits, profiles, scrollback, OSC 133 command history, colors, and clickable links
+- Bounded JSONC project tasks with color-preserving, interactive Output tabs
+- Git diff and staging, searchable commit graphs, cancellable fetch/pull/push, inline blame, and branch switching
 - 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
@@ -75,6 +91,9 @@ canopus --tui --project .
 canopus --headless /tmp/canopus.png README.md
 ```
 
+Use `EDITOR="canopus --wait"` when a caller such as Git must wait until every
+requested file tab is closed.
+
 Run `canopus --help` for session, settings, replay, backend, profiling, and
 plugin options.
 
@@ -83,19 +102,45 @@ plugin options.
 | Action | macOS | Linux / Windows |
 | --- | --- | --- |
 | File finder / commands | Cmd-P / Cmd-Shift-P | Ctrl-P / Ctrl-Shift-P |
+| Workspace symbols | Cmd-T | Ctrl-T |
 | Save / undo / redo | Cmd-S / Cmd-Z / Cmd-Shift-Z | Ctrl-S / Ctrl-Z / Ctrl-Shift-Z |
 | Find / project search | Cmd-F / Cmd-Shift-F | Ctrl-F / Ctrl-Shift-F |
 | Replace / next occurrence | Cmd-Alt-F / Cmd-D | Ctrl-H / Ctrl-D |
-| All occurrences / move lines | Cmd-Shift-L / Alt-Up or Down | Ctrl-Shift-L / Alt-Up or Down |
-| Completion / definition | Ctrl-Space / F12 | Ctrl-Space / F12 |
+| All occurrences / expand or shrink selection | Cmd-Shift-L / Alt-Up or Down | Ctrl-Shift-L / Alt-Up or Down |
+| Add cursor above / below | Ctrl-Alt-Up or Down | Ctrl-Alt-Up or Down |
+| Line-start, line-end, or regex cursors | Command palette | Command palette |
+| Move lines | Alt-Shift-Up or Down | Alt-Shift-Up or Down |
+| Completion / definition / rename | Ctrl-Space / F12 / F2 | Ctrl-Space / F12 / F2 |
 | Split / terminal | Cmd-Backslash / Ctrl-Backtick | Ctrl-Backslash / Ctrl-Backtick |
 | Close / reopen tab | Cmd-W / Cmd-Shift-T | Ctrl-W / Ctrl-Shift-T |
 | New terminal tab | Ctrl-Shift-Backtick | Ctrl-Shift-Backtick |
 | Next / previous terminal | Ctrl-Shift-] / Ctrl-Shift-[ | Ctrl-Shift-] / Ctrl-Shift-[ |
-
-The command palette also exposes Git operations, language actions, project file
-operations, settings, themes, docks, and Vim mode. Project deletion moves files
-to `.canopus/trash` instead of deleting them immediately.
+| Previous / next terminal command | Ctrl-Shift-Up / Ctrl-Shift-Down | Ctrl-Shift-Up / Ctrl-Shift-Down |
+| Run task | Cmd-Shift-B | Ctrl-Shift-B |
+
+The command palette also exposes Git operations, language actions (including
+`language.linked_editing`, `language.call_hierarchy`, and
+`language.type_hierarchy`), project file operations, settings, themes, docks,
+Vim mode, `git.history`, `git.fetch`, `git.pull`, `git.push`,
+`terminal.commands`, `terminal.commands.failed`, `terminal.command.toggle_fold`,
+`terminal.split_right`, `terminal.split_down`,
+`panel.problems`, and
+`problems.filter`. The problem filter accepts
+free text plus optional `severity:error` and `source:lsp` terms (`warning`,
+`information`, `hint`, `task`, and `test` are also accepted). Project deletion
+moves files to `.canopus/trash` instead of deleting them immediately.
+
+`language.linked_editing` selects matching HTML or XML opening and closing tag
+names when no language server can provide linked ranges. Editing either selected
+name updates both through the editor's normal multi-selection and undo behavior.
+
+Bash, zsh, and fish terminals automatically load Tarazed shell integration
+for command boundaries, collapsible output, exit status, and OSC 7
+working-directory tracking. Click a command status badge to fold its output.
+Set `terminal.shell_integration` to `false` to leave the shell untouched.
+New terminals inherit the active terminal's OSC 7 working directory. Profiles
+accept `command` (or `path` plus `args`) and `env`; Canopus always sets
+`CANOPUS=1` and `EDITOR="canopus --wait"` after merging profile variables.
 
 ## Configuration
 
@@ -103,14 +148,44 @@ Run `settings.open` from the command palette to edit project settings. User
 settings live at `$XDG_CONFIG_HOME/canopus/settings.jsonc` or
 `~/.config/canopus/settings.jsonc`.
 
+When enabled (the default), `.editorconfig` is read per file between user and
+project settings. `indent_style`, `indent_size`, `tab_width`,
+`trim_trailing_whitespace`, `insert_final_newline`, and `max_line_length` are
+supported. Set `editorconfig` to `false` to disable it. Project settings keep
+precedence over `.editorconfig`; malformed, oversized, or symlinked config
+files are ignored.
+
 ```jsonc
 {
   "theme": "auto",
   "font_size": 14,
   "vim_mode": false,
   "use_tabs": false,
+  "auto_pairs": [["(", ")"], ["[", "]"], ["{", "}"], ["\"", "\""], ["'", "'"]],
+  "diagnostics": { "inline": true, "inline_max_length": 80, "severity": "warning" },
+  "inlay_hints": { "enabled": true, "parameter_names": true, "types": true, "max_length": 30 },
+  "code_lens": { "enabled": true },
+  "bracket_colorization": true,
+  "indent_guides": { "enabled": true, "active": true },
+  "render_whitespace": "boundary",
+  "render_ideographic_space": true,
+  "sticky_scroll": { "enabled": true, "max_lines": 5 },
+  "breadcrumbs": { "enabled": true },
+  "minimap": { "enabled": false, "width": 100, "show_diagnostics": true },
+  "auto_save": "off",
+  "auto_save_delay": 1000,
+  "persistent_undo": { "enabled": true, "max_entries": 1000, "expire_days": 30 },
+  "format_on_save": false,
+  "code_actions_on_save": [],
+  "format_on_save_timeout": 2000,
+  "git": { "inline_blame": "off", "autofetch": false, "autofetch_interval": 180 },
+  "recovery": { "enabled": true, "interval": 5000 },
   "tabs": { "activate_on_close": "history", "reopen_history_limit": 20 },
-  "terminal": { "working_directory": "project", "scrollback_lines": 10000 },
+  "terminal": {
+    "working_directory": "project", "scrollback_lines": 10000, "shell_integration": true,
+    "profiles": { "bash": { "path": "/bin/bash", "args": ["--login"], "env": { "TERM_PROGRAM": "canopus" } } },
+    "default_profile": "bash"
+  },
   "dock": {
     "bottom": { "size": 280, "visible": false },
     "panels": { "terminal": { "size": 280, "visible": false } }
@@ -118,11 +193,52 @@ settings live at `$XDG_CONFIG_HOME/canopus/settings.jsonc` or
   "keymap": [
     { "context": "Editor && !vim_mode", "bindings": { "ctrl-k ctrl-s": "file.save" } }
   ],
-  "languages": { "ruby": { "tab_size": 2 } },
-  "language_servers": { "ruby": ["ruby-lsp"] }
+  "languages": { "ruby": { "tab_size": 2, "auto_pairs": [] } },
+  "language_servers": {
+    "ruby": [
+      { "command": ["ruby-lsp"], "features": ["completion", "definition", "hover", "formatting"] },
+      { "command": ["rubocop", "--lsp"], "features": ["diagnostics", "codeAction"] }
+    ]
+  },
+  "debug_adapters": {
+    "ruby": { "command": ["rdbg", "--open", "--stop-at-load"], "transport": "tcp" }
+  }
 }
 ```
 
+A legacy argument array such as `"ruby": ["ruby-lsp"]` still configures one
+server. With multiple servers, completion, diagnostics, and code actions are
+merged; workspace symbols are collected from every matching active server;
+other features use the first matching server in configuration order. Workspace
+symbol search falls back to bounded project-content search when no usable
+provider is active. Override `language.workspace_symbols` in `keymap` to change
+its Cmd-T / Ctrl-T binding.
+
+`render_whitespace` accepts `none`, `boundary`, `selection`, or `all`.
+`boundary` hides only single spaces between non-whitespace characters. Tabs use
+`→`, spaces use `·`, and ideographic spaces use `□`; the last remains visible
+independently when `render_ideographic_space` is enabled.
+
+`auto_pairs` replaces the opener/closer list for the current settings layer;
+set it to `[]` globally or for one language to disable automatic pairing and
+selection surrounding. Each opener and closer must be one Unicode grapheme.
+
+Sticky scroll keeps the declarations containing the first visible source byte
+above the editor body. It prefers cached LSP document symbols and falls back to
+cached Antares structure regions; `sticky_scroll.enabled` and
+`sticky_scroll.max_lines` can also be overridden per language.
+
+Breadcrumbs show the project-relative file, containing type, and callable above
+sticky scroll. Selecting an item opens its same-directory files or same-parent
+symbols in the palette. `breadcrumbs.enabled` can be overridden per language.
+
+The GUI-only minimap is disabled by default. When enabled, it reserves its
+configured width only in panes wide enough to keep the editor usable, reuses
+bounded low-resolution line textures across splits, and shows Git, search, and
+optionally diagnostic overview marks. Click or drag it to center that source
+position without moving the selection. All minimap options can be overridden
+per language.
+
 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. Dock and panel visibility and sizes are also
@@ -130,6 +246,24 @@ restored. Terminal session restoration, when enabled,
 starts fresh shells with the saved tab count and working directories and does
 not restore processes or scrollback.
 
+Dirty buffers are also written every five seconds to private, atomically
+replaced files under `.canopus/recovery/`. After an abnormal exit, the newest
+valid snapshot is offered at startup; normal exit removes this run's snapshot.
+Set `recovery.enabled` to `false` or change `recovery.interval` (milliseconds)
+in settings. Recovery files contain local unsaved text, so disable the feature
+for workspaces where even a mode-0600 local copy is unacceptable. Individual
+buffers over 10 MiB and snapshots over 64 MiB are not retained.
+
+Set `auto_save` to `after_delay` to save dirty named files after the debounce
+interval in `auto_save_delay` milliseconds, or to `on_focus_change` to save a
+file when switching away from it. Untitled, read-only, and conflicting files
+are skipped or reported without forcing a write.
+
+Persistent undo keeps up to `persistent_undo.max_entries` undo entries for
+clean regular files under `.canopus/undo/`. Records are project- and file
+identity-bound, expire after `expire_days`, and are ignored when corrupt or
+when the file changes. Dirty buffers remain in recovery storage instead.
+
 Settings are layered from defaults through user, project, explicit `--settings`,
 and language overrides. Invalid saved settings leave the previous valid values
 active. Keymap groups extend defaults; later matching bindings win, and `null`
@@ -139,6 +273,33 @@ Language servers are separate programs and are auto-detected or configured by
 argument array. See [Language servers](docs/lsp.md) for configuration and
 restart behavior.
 
+Debug launch definitions and the persistent, edit-aware breakpoint gutter
+are described in [Debug configurations](docs/debugging.md). `debug.start`
+selects and starts a configuration, and `debug.stop` ends the active session.
+When execution stops, the Debug panel provides safe stack navigation, lazy
+variables, per-stop watch evaluation (`debug.watch.add` /
+`debug.watch.remove`), and the breakpoint list. Variable expansion is restored
+by name path rather than adapter reference IDs.
+`debug.console.evaluate` accepts REPL input for the selected frame and
+`panel.debug_console` toggles ordered adapter output. Hovering a simple
+local, instance, class, or global variable while stopped evaluates it in the
+selected frame.
+Breakpoint files use an atomic rename
+for normal same-user workspace consistency; concurrent malicious workspace
+mutation is outside that guarantee.
+
+Project task definitions, variables, Output tabs, and reveal behavior are
+described in [Tasks](docs/tasks.md). `task.run` opens the task picker,
+`task.stop` stops the selected running Output tab, and `panel.output` toggles
+the panel. Single-line, multi-line, and watch problem matchers publish task
+output into the shared Problems panel and editor diagnostics.
+
+The [Test explorer](docs/testing.md) discovers Minitest and RSpec declarations
+with a bounded Alkaid walk and Prism AST inspection. `panel.test` opens the
+tree and `test.refresh` rescans it. Gutter buttons run static tests in bounded
+Task Output tabs and show running, passed, failed, or skipped state; selecting
+a failed test opens its reported failure line.
+
 Plugins require explicit trust and permissions:
 
 ```sh
@@ -146,15 +307,19 @@ canopus --plugin examples/plugins/word_count.rb \
   --trust-plugins --grant read_buffer
 ```
 
-The default separate process contains plugin crashes and timeouts, but it is not
-an OS sandbox. Trusted Ruby code retains the invoking user's filesystem and
-network privileges.
+The default separate process also requests Saiph's OS sandbox. Set
+`plugins.sandbox` to `"required"` to reject plugins when the host has no
+supported backend, or to `"off"` to retain the legacy process-only isolation.
+The legacy `process` permission is accepted as an alias for `exec`.
 
 ## Documentation
 
 - [Language servers](docs/lsp.md)
+- [Debug configurations](docs/debugging.md)
+- [Test explorer](docs/testing.md)
 - [Vim mode](docs/vim.md)
 - [Snippets](docs/snippets.md)
+- [Completion providers](docs/providers.md)
 - [Workspace edits](docs/workspace_edits.md)
 - [Packaging](docs/distribution.md)
 - [Profiling and local crash reports](docs/performance.md)
@@ -167,19 +332,26 @@ git clone https://github.com/noxdea/canopus.git
 cd canopus
 bundle install
 bundle exec rake test
-bundle exec rbs -I sig -r porrima -r thuban -r alhena -r antares -r denebola -r zaniah -r stringio -r strscan validate
+bundle exec rbs -I sig -r kochab -r porrima -r thuban -r alhena -r antares -r denebola -r zaniah -r sadr -r saiph -r rexml -r megrez -r tarazed -r alkaid -r stringio -r strscan validate
 bundle exec ruby tools/check_dependencies.rb test/type/smoke.rb
 ```
 
+Before component releases are available, use sibling checkouts with
+`SADR_PATH=../sadr SAIPH_PATH=../saiph MEGREZ_PATH=../megrez MENKAR_PATH=../menkar TARAZED_PATH=../tarazed ALKAID_PATH=../alkaid ANTARES_PATH=../antares bundle install`.
+
 Run `bundle exec rake bench` for performance checks. Contributions can be
 submitted through [GitHub issues and pull requests](https://github.com/noxdea/canopus/issues).
 
 ## Limits
 
-- Files larger than 100 MiB use a read-only UTF-8 path without wrapping or folding.
-- Large-file UTF-16 and legacy encodings are unsupported.
+- Files larger than 100 MiB use Denebola's read-only, UTF-8 `LazyRope` path with bounded page caching; wrapping and folding remain disabled.
+- Persistent undo records are limited to 16 MiB per file and 256 MiB per project.
+- Smaller text files use Menkar to detect UTF-8/16/32 and common legacy encodings; binary files are not opened as editable buffers.
+- Mixed line endings are shown as `mixed` in the status bar and can be normalized to LF, CRLF, or CR from the encoding actions.
 - Git support targets SHA-1 repositories and does not implement every index or object extension.
-- Desktop packages are unsigned and do not bundle Ruby or automatic updates.
+- The integrated terminal uses a POSIX PTY on macOS/Linux and ConPTY on 64-bit Windows.
+- Desktop packages are unsigned and do not bundle Ruby or automatic updates;
+  signed updates are available as an explicit `tools/update.rb` operation.
 
 ## License
 

data/assets/keymaps/emacs.jsonc

@@ -0,0 +1,5 @@
+{
+  "keymap": [
+    {"context": "", "bindings": {"ctrl-x ctrl-f": "file.find", "alt-x": "command.palette", "ctrl-x ctrl-s": "file.save"}}
+  ]
+}

data/assets/keymaps/jetbrains.jsonc

@@ -0,0 +1,5 @@
+{
+  "keymap": [
+    {"context": "", "bindings": {"shift-shift": "command.palette", "ctrl-shift-n": "file.find", "shift-f6": "language.rename"}}
+  ]
+}

data/assets/keymaps/sublime.jsonc

@@ -0,0 +1,5 @@
+{
+  "keymap": [
+    {"context": "", "bindings": {"ctrl-p": "file.find", "ctrl-shift-p": "command.palette", "ctrl-r": "language.rename"}}
+  ]
+}

data/assets/keymaps/vscode.jsonc

@@ -0,0 +1,5 @@
+{
+  "keymap": [
+    {"context": "", "bindings": {"ctrl-p": "file.find", "ctrl-shift-p": "command.palette", "f12": "language.definition"}}
+  ]
+}

data/docs/debugging.md

@@ -0,0 +1,143 @@
+# Debug configurations
+
+Canopus reads project launch configurations from `.canopus/launch.jsonc`. The
+file is JSON with comments and trailing commas, parsed by Kochab:
+
+```jsonc
+{
+  "configurations": [{
+    "name": "Run tests",
+    "type": "ruby",
+    "request": "launch",
+    "program": "${workspaceFolder}/bin/rake",
+    "args": ["test"],
+    "cwd": "${workspaceFolder}"
+  }]
+}
+```
+
+The supported substitutions are `${workspaceFolder}`, `${file}`,
+`${lineNumber}`, `${selectedText}`, and `${env:NAME}`. Substitution applies to
+all string values, including `program`, `args`, and `cwd`. A requested value
+must be available; unknown variables and missing environment entries are
+reported as configuration errors. Text inserted from a selection or environment
+entry is literal, so `${...}` inside that text is not expanded again. File,
+program, and working-directory paths must remain inside the project root.
+Adapter commands are accepted only as argument arrays, not as shell command
+strings.
+
+Adapters are selected by the configuration's `type` and configured as a global
+setting. `languages.*.debug_adapters` is rejected; language selection happens
+through each launch configuration's `type`:
+
+```jsonc
+{
+  "debug_adapters": {
+    "ruby": {
+      "command": ["rdbg", "--open", "--stop-at-load"],
+      "transport": "tcp"
+    }
+  }
+}
+```
+
+`transport` is `stdio` or `tcp`. Adapter commands use the same substitutions.
+At most 64 adapter types and 32 command arguments per adapter are accepted.
+Adapter type names are at most 128 bytes, each command argument is at most
+4,096 bytes and contains no control characters, and the complete adapter
+setting is at most 1 MiB. These byte limits are enforced at runtime in addition
+to the JSON schema's character limits.
+
+Canopus rejects oversized, deeply nested, or incorrectly typed configuration
+data before it can start an adapter. Expansion is limited to 1 MiB across one
+resolved launch or adapter, and captured environment data is limited to 1 MiB.
+If a project has a `Rakefile` but no launch configuration, the configuration
+loader offers a `Run tests` launch using `bin/rake test`. Debug sessions and
+their user interface are implemented separately from configuration loading.
+
+## Breakpoints
+
+The breakpoint registry stores project-relative paths, 1-based line numbers,
+optional conditions, hit conditions, log messages, and enabled state in
+`.canopus/breakpoints.json`. Version 1 files are loaded with breakpoints enabled
+and are written as version 2 on the next change. The versioned file is
+limited to 1 MiB and 10,000 entries. Paths must stay within the canonical
+workspace root; paths through outside symlinks are rejected. Breakpoints for
+files that are not currently open remain in the registry.
+
+Attached buffers update breakpoint lines after committed edits. Inserting ten
+lines before a breakpoint moves it down ten lines, deleting its complete source
+line removes it, and undo or redo restores the corresponding registry state.
+Tracked edits are coalesced and saved by one background writer; detach and
+close flush pending changes and surface write failures. The registry's `error`
+accessor exposes the latest background failure, and `flush` re-raises it.
+Changes are written through a sibling temporary file followed by `fsync` and
+an atomic rename.
+This provides normal same-user workspace consistency; concurrent malicious
+workspace mutation is outside its scope. Buffer attachment is an internal
+lifecycle operation. Left-click the gutter to add or remove a breakpoint.
+Right-click it to add or edit a condition, hit count, or log message, or to
+enable, disable, and remove the breakpoint. Disabled breakpoints use the muted
+gutter color; enabled breakpoints use the error color.
+
+## Sessions
+
+Run `debug.start` from the command palette. If the project has more than one
+launch configuration, Canopus opens a searchable configuration list. The
+adapter is initialized before enabled breakpoints are sent; Canopus then
+completes configuration and waits for the launch or attach response. Only one
+session is active per workspace. `debug.stop` closes the protocol session and
+its adapter process.
+
+The Ruby TCP adapter example above supports launch configurations and is started
+without a shell. Canopus assigns
+it a loopback port, passes the resolved `program` and `args` to rdbg, and then
+connects with Megrez. TCP attach is not supported; stdio adapters may implement
+attach through their launch configuration. On a stop event, the first stack frame is opened only if
+its canonical source path remains inside the workspace, and its line is
+highlighted. Continued and terminated events clear that highlight. Adapter
+startup and protocol failures are delivered through editor notifications.
+
+## Debug panel
+
+The `debug` panel opens automatically when execution stops and is also
+available through `panel.debug`. It shows the call stack, variables, watches,
+and the persistent breakpoint list. Selecting a stack frame changes the
+variable context and opens its source only when the canonical file remains
+inside the workspace. Breakpoint rows use the same checked source-opening
+path.
+
+Variable children are requested only when their tree row is expanded. The
+panel preserves expansion as scope and variable name paths (plus an ordinal
+for duplicate sibling names); it never stores adapter `variablesReference`
+values in tree state. On another stop or frame selection, Canopus resolves each
+saved name path again from fresh scopes before requesting children. Pending
+results from a continued, replaced, or closed session are discarded.
+
+Use `debug.watch.add` and `debug.watch.remove` from the command palette to edit
+the in-memory watch list. Watches are evaluated with DAP context `watch` for
+the selected frame on every stop and whenever the selected stack frame
+changes. Watch expressions are limited to 4 KiB and 100 entries. Panel
+visibility and size use the existing `dock.panels.debug` setting and session
+state; watch expressions themselves are not written to project files.
+
+## Debug console and hover
+
+`debug.console.evaluate` opens the existing input palette and evaluates the
+entered expression with DAP context `repl` in the selected stack frame.
+`panel.debug_console` toggles the bottom panel. Adapter output events retain
+their line breaks and arrival order and show bounded category and source-line
+metadata when it is valid. Source metadata is display-only and never opens an
+adapter-provided path. Finished sessions retain their history until the next
+session starts.
+
+While execution is stopped, hovering an ASCII local, instance, class, or
+global variable evaluates it with context `hover`. Bare names are checked
+against the selected frame's bounded DAP scopes first. Calls, members,
+constants, string and comment tokens, names within a string interpolation
+found in up to 256 cached rows or 4,096 tokens, indexing, operators, and names
+longer than 256 bytes are not evaluated. Hover and REPL requests are cancelled
+on continue, frame change, session replacement, termination, and close; late
+results are discarded.
+Console history is limited to 1,000 entries, individual adapter strings and
+expressions to 4 KiB, and concurrent REPL requests to 16.

data/docs/distribution.md

@@ -1,27 +1,58 @@
 # Packaging
 
 `tools/package.rb` creates a source-based macOS app, Linux launcher and desktop
-file, or Windows launcher and shortcut installer. The package includes Canopus
-sources and assets, but not Ruby, native binaries, or gem dependencies.
+file, or Windows launcher and shortcut installer. By default the package
+includes Canopus sources and assets but not Ruby or gem dependencies; a staged
+relocatable Ruby can be included explicitly with `--ruby-root`.
 
 ```sh
 ruby tools/package.rb --platform mac --output /tmp/Canopus.app --ruby /path/to/ruby
 ruby tools/package.rb --platform linux --output /tmp/canopus-linux --ruby /usr/bin/ruby
 ruby tools/package.rb --platform windows --output /tmp/canopus-windows --ruby ruby.exe
+ruby tools/package.rb --platform mac --output /tmp/Canopus-bundled.app --ruby-root /path/to/staged-ruby
 ruby tools/package_test.rb
 ```
 
-The output path must not exist and must be outside the source tree. Build for the
-Ruby executable available on the destination machine. Canopus requires CRuby
-3.1 or newer and its runtime gems installed for that Ruby. The installed package
-does not require Bundler.
+Packages can be signed after building with an RSA release key. The signer only
+stores a public key fingerprint and a signature over `manifest.json`; the
+private key stays outside the package and CI logs.
+
+```sh
+ruby tools/sign_package.rb --package /tmp/canopus-linux --private-key release.pem
+ruby tools/sign_package.rb --package /tmp/canopus-linux --verify --public-key release.pub
+```
+
+Verification also checks every SHA-256 entry in the manifest. This is a
+credential-free integrity check; macOS notarization and Windows Authenticode
+still require platform credentials and are release-environment work.
+
+The generated macOS app declares common text, Markdown, Ruby, JSON, and XML
+document types. Linux packages include `Install.sh` and `Uninstall.sh` for a
+per-user install under `~/.local/share/canopus` and register the desktop MIME
+associations. Windows packages include `Install.ps1` and `Uninstall.ps1`,
+which register a per-user `Canopus.Document` ProgID and OpenWith entries.
+
+Updates are explicit: `tools/update.rb` accepts a signed JSON feed containing
+the channel, platform, semver, HTTPS archive URL, size, SHA-256, and RSA
+signature. It downloads into a same-filesystem staging directory, rejects
+unsafe tar entries, verifies the archive hash, and atomically swaps the install
+directory with rollback if activation fails.
+
+The output path must not exist and must be outside the source tree. Without
+`--ruby-root`, build for the Ruby executable available on the destination
+machine. With `--ruby-root`, the directory must be a relocatable CRuby staging
+root containing `bin/ruby` (or `bin/ruby.exe`); it is copied into the package's
+`runtime/` directory and launchers use that relative executable. The staged root
+must include Canopus's production gems and must not contain symlinks. The
+installed package does not require Bundler.
 
 macOS's system Ruby is generally too old. Linux requires its Wayland/EGL/OpenGL
 or X11/GLX libraries, XKB, and `zenity` for file dialogs. Move a Linux package to
 its final location before installing its generated desktop file. On Windows, run
 `Create-Shortcut.ps1` from the package to create a shortcut.
 
-These packages are unsigned and do not bundle security updates for Ruby. Signing,
-notarization, automatic updates, and a relocatable Ruby runtime require separate
-platform-specific release work. See [ADR 005](adr/005-windows-runtime.md) for the
+Every package includes `manifest.json` with SHA-256 entries for its files. These
+packages are unsigned and do not bundle security updates for Ruby. Signing,
+notarization, and automatic updates require separate platform-specific release
+work. See [ADR 005](adr/005-windows-runtime.md) for the
 Windows/YJIT runtime decision.