Hunk Extension Authoring Map

Rules that bite

Most extension bugs are one of these:

• Registering a surface does not show it. Panes need defaultOpen, replaces: "hunk:files", or a command that opens them. File views remain raw until selected from the View menu.
• A rejected file-view layout silently becomes raw diff. hunkRows needs one in-bounds, inclusive entry per parsed hunk at the same array index, and sourceRanges may not overlap on a side; invalid, oversized, cancelled, and throwing layouts warn once and fall back.
• Syntax paint stays declarative. File views declare complete codeDocuments and map exact symbolic spans with syntax; Hunk owns tokenization, theme colors, visible-window demand, resource limits, and plain fallback. Keep gutters and separators in non-syntax spans, and use sourceRanges separately for notes/navigation.
• Never bundle or vendor React. Hunk serves its own react and @opentui/* to extension files; a second copy means a second hooks dispatcher and the component fails to render. Import them normally. OpenTUI intrinsics (box, text, scrollbox) need no import.
• layout is a pure derivation of (file, width). A stateful view keeps painting its first answer until ctx.fileViews.refresh(viewId) — scope it with { fileId } when the state belongs to one file.
• Handler state must live outside the component. Panes unmount when closed; bridge module-level state into React with useSyncExternalStore and immutable snapshots (review-triage/index.tsx is the working version).
• Use ctx.review.snapshot() for complete saved-note state. note_created and note_edited are incremental UI events, not an authoritative collection. Snapshots include stale and orphaned saved notes, exclude drafts and static sidecar annotations, and should be re-read before irreversible async work; compare both generation and revision. review-note-navigator shows how to join stable note ids and file keys back to guarded navigation after awaiting a selector; file filters can still refuse hidden targets.
• Retained review controls expire on reload. An old handler cannot control replacement content: pane/navigation calls become inert, dialogs cancel, and workspace reads or not-yet-started writes return null/unavailable. A consented write already in progress reports its real outcome, holds graceful exit until it settles, and reconciles the active review on success. shutdown runs after revocation, so use it only to release extension-owned resources.
• A reload keeps your factory and renames the files. Factories re-run only after a trust grant or a cwd change, so module state survives — but a file's id encodes its position in the changeset, so a reload that adds or drops a file renumbers the rest. Key durable per-file state by path, or reconcile it on changeset_loaded. Pick one deliberately.
• Transforms must preserve metadata (spreading a file does), keep ids unique, and return a real changeset — otherwise the transform is skipped with a warning and the previous changeset carries forward.
• Chords are defaults. Users remap by command id in [keybindings]; built-ins win conflicts, refused one chord at a time. Bind the character shift produces ("!", not "shift+1").
• Keyboard modes are grammar, not behavior. Keep pending sequences and numeric prefixes in the extension, then call one public ctx.commands.execute after resolving an action. vim-navigation demonstrates counts, Ctrl chords, and a : key passed to a registered command whose host input dialog temporarily outranks the still-active mode.
• ctx.commands invokes Hunk, not other extensions. Probe with isEnabled("hunk.review.nextHunk"), then call execute(id, { count }) for an explicitly public built-in. Counts are positive whole numbers up to 10,000, applied atomically to movement; one-shot actions run once. Unknown, disabled, private, extension-owned, or stale commands return false.
• Repo config can set [extension.<id>] for a globally installed extension. Treat hunk.config as untrusted for anything exec-adjacent (binary paths, shell commands, module loading).
• ctx.workspace writes only apply to reloadable, unstaged working-tree reviews, by reviewed file id, inside the review root, with consent. Everything else returns { ok: false, reason } — check canWriteDocument first.
• File-view note placement is all-or-raw per file: an unbound or range-less visible note makes Hunk render the complete raw diff instead of guessing.
• Failures are contained, not sandboxed. A throwing factory is rolled back to zero registrations and a throwing handler is a warning naming the extension — containment against bugs, not against code that should not have been loaded.
• The API touches nothing outside the review. No clipboard, no filesystem, no process surface beyond ctx.workspace — an extension is ordinary code, so shell out for the rest. Never write to stdout: the renderer owns it. For the same reason hunk.log is collected as diagnostics and printed nowhere; ctx.notify is how a user hears from you.
• HunkExtensionUserError (detected structurally by name) buys the full treatment — message plus suggestions, no stack trace — only from a VCS adapter operation, which is where Hunk formats it for the CLI. From a command or event handler only the message survives, as a warning toast.

Verifying

Hunk's TUI needs a real terminal, and the review UI is the user's — do not launch hunk diff/hunk show to test, and do not reach for a pipe. No invocation applies extensions headlessly: hunk diff … | cat still starts the app and still takes the keyboard, so it hangs holding the user's terminal. Practical checks, in order of cost:

1. Typecheck. In a checkout, bun run typecheck covers examples/extensions/** via the hunkdiff/extension path mapping. Standalone, add hunkdiff as a dev dependency and run tsc --noEmit; for a .tsx extension also add react, @types/react (React ships no declarations of its own), @opentui/core, and @opentui/react as dev dependencies and set "jsx": "react-jsx" with "jsxImportSource": "@opentui/react", or every <box> and <text> is an untyped intrinsic. Types only — shipping those packages is the second-React bug.
2. Unit-test the logic. When parsing, matching, or formatting is worth testing, put it in helper modules with plain bun test coverage.
3. PTY integration. In a checkout, test/pty/extensions-integration.test.ts launches Hunk over a PTY with --extension <path> and asserts on rendered snapshots; extend it via test/pty/harness.ts and run bun run test:integration.
4. Hand it to the user to run: hunk diff --extension ./my-ext. --extension loads immediately with no trust prompt, so it is the iteration path. Ask them what the footer notices and toasts said.
5. Triage with --no-extensions to confirm a symptom belongs to an extension (bundled VCS backends, the built-in files pane, and the / content search stay loaded either way).

If it does not load

• No startup notice at all → a successful load is silent, so either it loaded and nothing opened it, or discovery never saw the file. Check the directory, the entry suffix, or the folder's package.json hunk.extensions paths.
• Notice naming the extension → id rejected (reserved, malformed, or already claimed), import failure, missing default export, or a throwing factory.
• Repo-local extension silently absent → the trust prompt was dismissed or denied; decisions are stored per repo root in ~/.config/hunk/state.json.
• Pane closes with a toast → the component threw; a second React copy is the usual cause.
• Pane or file view never appears → nothing opened it (no defaultOpen, no command), matches returned false, or the layout was rejected.
• Command never fires → its chord lost to a built-in or an earlier extension (a warning says so); it is still reachable from the Extensions menu and bindable by <id>.<commandId>.

Changing Hunk itself

Only when the work is in the hunk repo rather than in a user extension:

• Shipped VCS backends, hunk gh, the built-in files pane, and the / content search are bundled extensions, registering through the same public API. That dogfooding is deliberate — if the public contract cannot express something, that is a real gap, not a reason for a private path. default/vcs/ loads from VCS adapter resolution and must stay renderer-free; default/core/ loads session-owned CLI capabilities from private workspaces such as packages/hunk-gh; and default/ui/ holds process-cached rendering registrations.
• packages/hunk/src/extension-api/types.ts must stay import-free; declaration emission publishes whatever it reaches, and scripts/packaging/check-pack.ts fails the pack otherwise. Shapes shared with internal code are declared there and re-exported inward.
• New API surface means updating docs/extensions.md (its examples are typechecked as consumer code), the matching hand-written page under website/src/content/docs/docs/extend/ (only cli.md and config.md are generated), docs/extension-architecture.md if ownership moves, and a changeset.
• AGENTS.md and docs/extension-architecture.md own the rest of these rules.