feat(extensions): give command handlers the review selection

[benvinegar]

Item 2 from the extension-system roadmap: extension command handlers previously received no review selection, so a "copy current file path" or "open this hunk in my tool" command had to shadow-track the selection_changed lifecycle event into module state.

What changed

Contract (src/extension-api/types.ts, additive within apiVersion 1, still import-free):

• ExtensionReviewSelection { file: ExtensionDiffFile | null; hunkIndex: number | null }
• ExtensionCommandContext.selection — a snapshot built when the command fires: a handler that awaits still sees the selection it was run from. file is the same frozen read-only view sidebar components receive; since Hunk keeps the selection inside the visible files, it is null only when nothing is visible at all. hunkIndex is clamped against the file's real hunk count (guarding the one-frame window after a reload shrinks a file) and null for files with no hunks.

One pipeline, lazily: the toReadOnlyFileViews conversion moved out of ExtensionSidebarPane and now runs on demand behind a per-source cache in App — sidebar panes and command snapshots consume literally the same frozen objects, hidden sidebars and extension-free sessions never pay for the conversion, and the command callback stays identity-stable so the dispatch table, keymap, and Extensions menu don't rebuild on navigation keypresses. readMetadataHunkCount joins readMetadataChangeType in src/extensions/events.ts so knowledge of the opaque metadata shape stays in one module.

Works identically whether the command fires from its key or from the Extensions menu (both dispatch through the same run path).

Docs & release

• docs/extensions.md: ctx.selection semantics plus a typechecked example command (gated by check:pack alongside the other 16 examples).
• docs/extension-architecture.md: command-system note on the shared frozen-view pipeline.
• Changeset: minor.

Testing

• src/ui/lib/extensionSelection.test.ts: resolve/no-selection/not-visible cases, clamp high/low/NaN, zero-hunk file → null, frozen-ness and exact-object identity with the sidebar list.
• AppHost.extension-sidebar.test.tsx: a fixture command logs ctx.selection.file?.path + hunkIndex through real key dispatch; asserts the startup snapshot, then ]-navigation updates it.
• Verified: typecheck, bun test src/ui src/extensions src/lib (797 pass), check:pack, lint/format. PTY integration: green except two failures confirmed pre-existing on a main-equivalent tree in this container ("a command key opens an extension sidebar", "filter focus narrows the visible review stream").

An internal adversarial review pass confirmed ref-timing, callback-identity stability, and contract purity, and caught the eager-conversion perf regression fixed in the second commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JML2m7oy2sUbFftN7QoHhi

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ready	Preview	Jul 28, 2026 12:56pm

[greptile-apps]

Greptile Summary

Adds review-selection snapshots to extension command contexts.

• Introduces the public ExtensionReviewSelection contract and documents snapshot semantics.
• Shares lazily cached extension file views between sidebars and command dispatch.
• Resolves and clamps selected hunk indices from file metadata.
• Adds unit, component, integration, documentation, and release-note coverage.

Confidence Score: 3/5

The PR should not merge until command selection files are isolated from the mutable review metadata they promise not to expose.

The new command API hands extension handlers a top-level frozen object whose nested metadata and hunk array still alias the live review model, allowing the documented read-only boundary to be bypassed.

Files Needing Attention: src/ui/App.tsx, src/extensions/events.ts, and src/extension-api/types.ts

Important Files Changed

Filename	Overview
src/ui/App.tsx	Adds the shared lazy view cache and invocation-time selection snapshots, but exposes nested mutable model metadata through the new command context.
src/ui/lib/extensionSelection.ts	Resolves visible selected files and safely normalizes hunk indices against parsed hunk counts.
src/extensions/events.ts	Adds centralized hunk-count inspection; the existing shallow file-view conversion does not isolate nested metadata for the newly exposed command API.
src/extension-api/types.ts	Adds the command selection contract, whose mutation-isolation guarantee is stronger than the shallow-frozen runtime object provides.
src/ui/components/panes/ExtensionSidebarPane.tsx	Accepts host-produced file views so sidebars and command snapshots share exact object identities.
src/ui/lib/extensionSelection.test.ts	Covers selection resolution, clamping, null states, top-level freezing, and identity, but not nested mutation isolation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  R[Review controller state] --> C[Lazy frozen-view cache]
  C --> S[Extension sidebar props]
  C --> B[Selection snapshot builder]
  B --> K[Extension command context]
  R --> B

Loading

Prompt To Fix All With AI

### Issue 1
src/ui/App.tsx:515
**Nested metadata remains mutable**

When an extension command mutates nested data such as `ctx.selection.file.metadata.hunks`, the shallow-frozen file view writes through to the live review metadata, causing subsequent rendering, selection, and navigation to operate on extension-modified state despite the documented read-only contract.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix(ui): build extension selection snaps..." | Re-trigger Greptile}