vscode-cowriting-plugin/README.md

# vscode-cowriting-plugin

Non-shippable **proof-of-concept** (Feature #2 of Epic #1): a standalone VS Code
extension that drives **[`@cline/sdk`](https://www.npmjs.com/package/@cline/sdk)**
— validating Approach A (own coauthoring extension on the Cline SDK, no fork).

## What it does

Registers one command, **`Cowriting: Show Cline SDK Info`**, which loads
`@cline/sdk` and shows the SDK build version plus the agent's builtin tool
catalog (a pure, key-free SDK call) in a notification and the
"Cowriting (Cline SDK)" output channel.

Features shipped so far: F2 region-anchored threads (Feature #4), F3 live
human/Claude attribution (Feature #6), F4 propose/accept diff flow
(Feature #12), F5 cross-rung sidecar contract (Feature #14), F6 diff-view
data layer (Feature #17), and the **native-surfaces migration** (the
"Coediting Markdown with a Machine" Solution Design) — the current UI, replacing
the bespoke F7/F10/F11 review webview with VS Code's own chrome end to end. See
**How it works** below for the current experience; the F7/F9/F10/F11 sections
further down are kept as a **historical record** of the superseded webview (each
now says so up top).

## How it works

There is **no bespoke panel**. Every surface below is native VS Code chrome —
the editor title bar, status bar, Comments gutter, source control, diff editor,
and the built-in Markdown preview:

1. **Enter coediting.** Run **"✦ Coedit this Document with Claude"** (command
   palette, editor title menu, or editor/explorer context menu) on a Markdown
   document — it captures a **baseline** (a clean checkpoint: git HEAD if the
   file is tracked and clean, otherwise a snapshot) to measure future changes
   against. Until a document is entered, none of the surfaces below attach to
   it. **"Stop editing with Claude"** reverses it.
2. **Title bar + status bar are the everyday entry points.** Once coedited, the
   editor title bar carries **Review Changes**, **Ask Claude**, **Toggle
   Annotations**, and (in snapshot mode) **Mark Changes as Reviewed**; a
   `✦ Coediting · N changes` status-bar item shows the pending-change count and
   opens the review when clicked — no need to find the Source Control pane.
3. **Ask Claude is comments-first.** **"Ask Claude"** (editor title, or select
   text → right-click → "Ask Claude to Edit") opens a focused comment box on
   the native **Comments API** — on your selection, or a top-anchored
   whole-document thread with none selected. Claude replies in-thread and
   offers an edit; accepting the offer turns it into one or more pending
   proposals.
4. **Pending changes live in the buffer.** A proposal is **optimistically
   applied** straight into the editor (green/blue insertion tint, a struck
   deletion hint) with an inline **`✓ Keep` / `✗ Reject`** CodeLens above each
   changed block — and, once ≥2 proposals are pending, a top-of-file
   **`✓ Keep all (N)` / `✗ Reject all`** pair. Nothing is force-applied: a
   proposal whose target text changed underneath it is skipped, never guessed.
5. **Native diff answers "what changed?"** **Review Changes** (editor title, or
   `Ctrl+Alt+R` / `Cmd+Alt+R`) opens VS Code's own diff editor — baseline on the
   left, your live document on the right — with the platform's inline/side-by-side
   toggle, navigation, and accessibility for free. A Source Control gutter/viewlet
   entry (quick-diff change bars, "Open Changes") is a bonus home for git users,
   never the required path.
6. **The built-in Markdown preview is the annotated read.** "Open Preview to the
   Side" (or right-click a markdown file/tab → **"Open Cowriting Review
   Preview"**, `cowriting.openReviewPreview`) renders the document with
   authorship/change coloring **inside VS Code's own preview** — green = human,
   blue = Claude, strikethrough = deleted — toggled by **Toggle Annotations**
   (command or the title-bar eye icon). No separate webview, no separate
   persistence.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-native-surfaces.md`
(§5 UX Layout is the canonical source for this map). Migration plan:
[`docs/superpowers/plans/2026-07-01-native-surfaces-migration.md`](docs/superpowers/plans/2026-07-01-native-surfaces-migration.md).

## Architecture

- CommonJS extension bundled with esbuild (`src/extension.ts` → `out/extension.cjs`).
- `@cline/sdk` is ESM-only (Node ≥22) and uses `createRequire(import.meta.url)`,
  so it is **not** bundled — it is shipped in `node_modules` and loaded at
  runtime via dynamic `import()` from the vscode-free `src/cline.ts`.

## Run it (F5)

1. `npm install`
2. `npm run build`
3. Press **F5** (or Run → "Run Extension") to launch the Extension Development Host.
   It opens the committed **`sandbox/`** playground as its workspace (not the
   repo itself — VS Code won't open one folder in two windows, #8); start with
   `sandbox/playground.md`.
4. In the new window: **Cmd/Ctrl+Shift+P** → **"Cowriting: Show Cline SDK Info"**.

## F2 — Region-anchored threads (Feature #4)

Attach durable, region-anchored discussion threads to any document. Threads
render in the native VS Code **Comments** gutter and persist as git-native
sidecars under `.threads/<doc-path>.json` (plain, diffable JSON — no server).

- **Create:** select text → run **"Cowriting: Add Coauthoring Thread on Selection"**
  (or the Comments gutter "+").
- **Reply / Resolve:** use the native Comments reply box and the thread's
  Resolve/Reopen actions.
- **Survives edits, reload, and external change (`git pull`):** a hybrid anchor
  (durable content fingerprint + live offset tracking) re-resolves the thread.
  If the anchored text can't be confidently re-found, the thread is shown as
  **orphaned** at its last-known line — never silently moved.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-inner-loop.md`. No live
`@cline/sdk` turn and no credentials are involved in F2.

## F3 — Live human/Claude attribution (Feature #6)

> **Commands superseded (native-surfaces migration).** The attribution **data
> layer** below is current, but the Commands block is historical:
> `Cowriting: Toggle Attribution` was retired — authorship/change coloring now
> toggles via **Toggle Annotations** on a coedited document (How it works §6) —
> and "Ask Claude to Edit Selection" is palette-hidden; use **Ask Claude to
> Edit** (`Ctrl+Alt+E` / `Cmd+Alt+E`) or the comments-first **Ask Claude** (How
> it works §3). Kept below as a historical record.

As you and Claude coauthor, every span in the buffer carries an author: human
edits render with a subtle left border, Claude-authored spans with a background
tint. Text that predates tracking stays plain — the honest record. Edits that
touch a boundary (split, merge, partial overwrite) are handled char-precisely.

Attribution is persisted git-natively in the same `.threads/` sidecars
(`attributions[]`, sharing the same `anchors` fingerprints as F2 threads). On
reload, fingerprints re-resolve spans against the current document; spans that
can't be confidently re-found are **orphaned** (status-bar count + "Cowriting
Attribution" output channel) rather than silently moved or discarded.

**Commands**

- **`Cowriting: Ask Claude to Edit Selection`** — select text → enter an
  instruction → a live `@cline/sdk` turn runs on the built-in `claude-code`
  provider (rides your local Claude Code Pro/Max login; the extension stores no
  credentials). As of F4 the turn ends in a **proposal** (see below); accepted
  text lands as a Claude-attributed span.
- **`Cowriting: Toggle Attribution`** — show/hide attribution decorations.
- `cowriting.applyAgentEdit` _(palette-hidden)_ — the single machine-edit
  ingress seam. Tests drive this directly so CI requires no LLM.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-attribution.md`.

## F4 — Propose/accept diff flow (Feature #12)

Claude's edits arrive as **pending proposals** — propose-by-default, the
document never changes without your say-so. A proposal renders two ways at
once: an **amber tint** on the target range, and a "Claude proposes" comment
thread showing a fenced `diff` of current → proposed text with two actions:

- **✓ Accept Proposal** — applies the replacement through the `applyAgentEdit`
  seam, so it lands Claude-attributed (F3) — and the proposal disappears.
- **✗ Reject Proposal** — the document is untouched; the proposal disappears.

Pending proposals persist git-natively in the same sidecar (`proposals[]`,
sharing the F2/F3 `anchors` fingerprints), survive reload, and re-anchor as
surrounding text changes. If the **target text itself** changes, the proposal
goes **stale** (status-bar count, accept disabled — never applied by guess);
undo the change and it becomes decidable again. `cowriting.proposeAgentEdit`
_(palette-hidden)_ is the programmatic propose ingress E2E drives — no LLM in
CI.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-propose-accept.md`.
Live smoke: [`docs/MANUAL-SMOKE-F4.md`](docs/MANUAL-SMOKE-F4.md).

## F5 — Cross-rung format + round-trip (Feature #14)

The `.threads/` sidecar is the **published cross-rung contract**: any rung of
the ladder (this editor → Gitea substrate → rfc-app) reads and writes the same
record per the contract; git push/pull is the transport, no re-homing ever.

- **Normative contract (INV-14):**
  `vscode-cowriting-plugin-content/specs/coauthoring-sidecar-contract.md` —
  format changes land there first, then schema, then code.
- **Machine-checkable half:**
  [`schemas/coauthoring-sidecar.schema.json`](schemas/coauthoring-sidecar.schema.json);
  validate any sidecar from any rung with
  `node scripts/validate-sidecar.mjs <file>`. The unit suite validates every
  serialized artifact — contract drift fails CI.
- **Identity crosses rungs:** `Provenance.email` (git's own join key —
  populated from the workspace git config when available) and
  `agent.onBehalfOf` (who the machine acted for).
- **Writers preserve unknown fields (INV-15):** rewriting a sidecar never
  destroys another rung's data — unknown keys survive, after known keys,
  sorted.
- **Newer-major sidecars are read-only (INV-16):** the editor renders what it
  understands, warns once, and writes nothing (the store refuses as a
  backstop).
- **Deterministic merge (INV-17):** `src/mergeArtifacts.ts` — union-by-id,
  documented tie-breaks, every resolved divergence surfaced in `conflicts`.
- **The round-trip is proven, not asserted:**
  [`scripts/crossrung-reply.mjs`](scripts/crossrung-reply.mjs) is a
  self-contained conforming foreign writer (the Gitea-rung stand-in); host E2E
  drives editor-thread → stand-in reply → external-change → the reply renders
  in the thread.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-cross-rung-format.md`.

## F6 — Diff-view toggle (Feature #17, #19) — SUPERSEDED

> **Superseded.** The two-pane `Ctrl+Alt+D` toggle this section describes was
> deleted in #34; only the baseline **data layer** survived, now serving the
> native diff editor (`Ctrl+Alt+R` / "Review Changes" — How it works §5) and the
> built-in preview annotations (§6). The native-surfaces migration's Task 2
> additionally **retired INV-18** (machine-landing auto-advance): a landed
> Claude edit stays a visible change until "Mark Changes as Reviewed" (the
> renamed "Pin Diff Baseline to Now"), it no longer auto-clears. Kept below as a
> historical record.

**`Ctrl+Alt+D`** (the same chord on macOS — not `Cmd`; or **Cowriting: Toggle
Diff View**) flips the focused document into a native `vscode.diff` against a
**coauthoring baseline** — the readonly baseline on the left, your **live,
editable** document on the right (so you keep writing inside the diff; toggling
again closes it). The diff answers "what did *I* change?" in one keystroke
instead of git archaeology.

- **Works on any file (#19):** any document you can edit — a file inside or
  outside the workspace folder, or an **untitled** scratch buffer. Only a
  non-text-editor focus warns. (Untitled buffers diff in-memory; saving makes
  the baseline persist.)
- **Machine-factored baseline (INV-18):** the baseline initializes when a doc
  is first seen and **advances automatically at every machine landing** (every
  successful `applyAgentEdit` seam apply — INV-9). So text Claude landed never
  shows as a change; everything the diff shows is operator-authored by
  construction — no attribution filtering.
- **Pin on demand:** **Cowriting: Pin Diff Baseline to Now** resets the
  baseline to the current buffer for a deliberate "review my next pass" epoch;
  the diff tab title names the epoch (`opened` / `Claude landed` / `pinned`).
- **Pure view, repo-free (INV-19):** the baseline snapshot lives in VS Code
  **global** extension storage, keyed by a hash of the document URI, **never**
  the repo — `.threads/`, the cross-rung contract (INV-14..17), and
  `SCHEMA_VERSION` are untouched. Storage-unavailable degrades to in-memory
  baselines + one warning.
- **No LLM in CI:** host E2E (`test/e2e/suite/diffView.test.ts`) drives the same
  programmatic seam ingress (propose + accept) the F4 suite uses.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-diff-view.md`.
Live smoke: [`docs/MANUAL-SMOKE-F6.md`](docs/MANUAL-SMOKE-F6.md).

## F7 — Rendered track-changes preview (Feature #21) — SUPERSEDED

> **Superseded (Task 8, native-surfaces migration).** The bespoke webview this
> section describes was deleted; its authorship/change coloring lives on
> **inside VS Code's own built-in Markdown preview** — see **How it works** §6
> above. Kept below as a historical record of the pre-migration design. (The
> `Ctrl+Alt+R` chord below now opens the native **Review Changes** diff; the
> annotated preview opens via **Open Cowriting Review Preview**, no chord.)

**`Ctrl+Alt+R`** (or **Cowriting: Open Track-Changes Preview**) opens a
read-only webview **beside** a **Markdown** editor that renders the document and
marks what changed since the F6 baseline — the "track changes" / "suggesting
mode" altitude rather than a raw-text split-diff:

- **Prose** additions are highlighted (`<ins>`), deletions struck (`<del>`),
  refined to the word.
- **Code and mermaid fences** are diffed **whole** (atomic, INV-23): a changed or
  added one renders fully with a small **"changed"** badge; a removed one renders
  struck. Mermaid fences render as **diagrams** (mermaid runs in the webview).
  Intra-diagram node/edge diffing is deferred (#22).
- It **updates live** as you and Claude edit (debounced), and **re-bases** when
  Claude lands an edit (baseline advances, INV-18) or you pin — so accepted text
  drops its marks. It **reuses the F6 baseline** and adds **no** persistence
  (pure read-only, INV-20).
- The webview is **sealed** (INV-21): local bundled assets only, strict CSP with
  a per-load nonce, no network/CDN, no LLM. Mermaid is bundled into the
  **webview** asset only, never the extension-host bundle.
- The render engine (`src/trackChangesModel.ts`) is a **pure, vscode-free**
  function (INV-22), unit-tested with no editor and no webview; host E2E
  (`test/e2e/suite/trackChangesPreview.test.ts`) drives the same programmatic
  propose/accept seam with no LLM.

F7 is **markdown-only**; for any other file (incl. code), use F6's diff toggle
(`Ctrl+Alt+D`). The webview's visual rendering (mermaid, theming) is verified by
the manual smoke, not the sealed-sandbox E2E.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-rendered-preview.md`.
Live smoke: [`docs/MANUAL-SMOKE-F7.md`](docs/MANUAL-SMOKE-F7.md).

## F9 — Authorship view in the preview (Feature ~#27) — SUPERSEDED

> **Superseded (Task 8, native-surfaces migration).** The F7 webview this mode
> lived in was deleted; the built-in preview's annotations (How it works §6)
> always show authorship + change coloring together — there is no separate
> mode toggle. Kept below as a historical record.

The rendered preview (F7) gains a second mode, switched by a `[ Track changes |
Authorship ]` toggle in its header. **Authorship** mode re-renders the current
document with each span colored by its F3 author — Claude (blue) vs you (green),
inline and char-precise — with a legend. Unlike track-changes (which diffs against
the F6 baseline, and so hides Claude's text once the baseline advances past a
landing), authorship reads F3 attribution directly, so Claude's contributions stay
visible. Code/mermaid fences carry a block-level author badge (atomic). Read-only,
sealed webview, no new persistence (INV-26..28).

Design: `docs/superpowers/specs/2026-06-11-authorship-preview-design.md`.
Live smoke: [`docs/MANUAL-SMOKE-F9.md`](docs/MANUAL-SMOKE-F9.md).

## F8 — Out-of-workspace authoring (Feature #25)

"Ask Claude to Edit Selection" (and F2 threads / F3 attribution / F4
propose-accept) now work on **any** document the editor shows — saved in the
workspace folder, saved outside it, or untitled — matching the already-universal
F6 diff and F7 preview. Authoring is no longer gated to in-workspace files, and
the commands are live even with **no folder open**.

Persistence is **hybrid** (one `SidecarStore` abstraction, routed per-document):

- an **in-workspace** file keeps its committable `.threads/<repo-rel>.json`
  sidecar, **byte-for-byte unchanged** (INV-2) — the only home the F5 cross-rung
  contract ever sees;
- an **out-of-workspace** file or **untitled** buffer stores its coauthoring
  artifact in VS Code **global storage** keyed by `sha256(uri)` (the same home
  and key F6's baseline uses, INV-19/24); untitled buffers are **in-memory
  only** (lost on reload/save).

A global-storage artifact is **not a committed file**, so it is **never
cross-rung-shareable** (INV-25), and renaming/moving the file **orphans** its
artifact (the key is the URI hash) — both stated as design contract, not
discovered later. Routing leaves the in-workspace path untouched, so rollback is
a plain PR revert with zero data migration.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-out-of-workspace.md`.
Live smoke: [`docs/MANUAL-SMOKE-F8.md`](docs/MANUAL-SMOKE-F8.md).

## F10 — Interactive review: write left / review right (Feature #29) — SUPERSEDED

> **Superseded (Task 8, native-surfaces migration).** The editor is no longer
> "zero-annotation" — pending proposals now render optimistically applied
> in-buffer with `✓ Keep`/`✗ Reject` CodeLens (F12), and review happens across
> the native diff editor + built-in preview, not one dedicated webview. See
> **How it works** above. Kept below as a historical record. (The `Ctrl+Alt+R`
> chord below now opens the native **Review Changes** diff, not this panel.)

A clean, **zero-annotation editor** on the left; the rendered preview on the
right as the **single interactive review surface**. The editor carries no
attribution tint, no in-editor proposal threads, and no diff — all review lives
in the preview, toggled by the **Annotations** switch in its header (on by
default). Open it via `Ctrl+Alt+R`, the editor title-bar button, or
**right-click a markdown file in the Explorer / its editor tab →
"Open Cowriting Review Panel"** (#41) — the right-click acts on the clicked
document, opening it first if needed.

In the on-state the preview shows **green = human / blue = Claude /
strikethrough = deleted**, and surfaces each of Claude's pending F4 proposals as
a blue `cw-proposal` block with **✓ / ✗** buttons: **✓** accepts (the
replacement lands Claude-attributed via the seam and the baseline advances past
it), **✗** rejects (the block vanishes, the document untouched). With no preview
open, a status-bar indicator shows the pending-proposal count and opens the
review when clicked. Toggle **Annotations** off for clean rendered markdown.
Read-only, sealed webview, no new persistence (INV-32..34).

F6's two-pane diff and F9's authorship view are **retained only as data layers**
(the baseline the preview diffs against; the F3 attribution that colors it) —
they are no longer separate user surfaces.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-interactive-review.md`.
Live smoke: [`docs/MANUAL-SMOKE-F10.md`](docs/MANUAL-SMOKE-F10.md).

## F11 — Preview toolbar as the primary interaction surface (Feature #43) — SUPERSEDED

> **Superseded (Task 8, native-surfaces migration).** The webview toolbar this
> section describes was deleted; its two controls moved to native chrome —
> **Pin baseline** is now **"Mark Changes as Reviewed"** in the editor title
> bar, and **Ask Claude** is the comments-first ask (How it works §3). Kept
> below as a historical record.

The review preview's **header toolbar** becomes the cockpit for the inner loop.
Beside the existing **Annotations** switch it gains two controls:

- **⌖ Pin baseline** — pins the previewed document's review baseline to now and
  clears the change-marks (homes the previously-orphaned `pinDiffBaseline`
  command, which is reachable from the palette again too).
- **✦ Ask Claude…** — one **adaptive** button. Its label flips on the preview's
  selection: **Edit Selection** when text is selected in the rendered preview,
  **Edit Document** otherwise. Clicking it opens a host input box for the
  instruction (the LLM turn and prompt stay host-side — the sealed webview gains
  no LLM/credential surface), then surfaces the result as F4 proposals — **one**
  for a selection (mapped back to its source block-union), or **one per changed
  hunk** for a whole-document rewrite (`diffToHunks`), each independently ✓/✗-able.

The pure render layer emits `data-src-start`/`data-src-end` on every block in
**both** modes (INV-36); the webview's only mapping duty is walking a selection
to its nearest `data-src` ancestor. Right-clicking a markdown tab → **Open Review
Preview** is the minimal gateway making the surface reachable end to end (#41/#42
expand it). Edit controls are disabled on a non-authorable doc (reading stays
allowed). No new model, no new persistence — pin via the F6 store, edits via the
F4 propose/accept seam with F3 attribution (INV-35..37).

Design: [`docs/superpowers/specs/2026-06-12-f11-preview-toolbar-interaction-surface.md`](docs/superpowers/specs/2026-06-12-f11-preview-toolbar-interaction-surface.md).
Live smoke: [`docs/MANUAL-SMOKE-F11.md`](docs/MANUAL-SMOKE-F11.md).

## Develop

- `npm run watch` — rebuild on change.
- `npx vitest run` — unit suite (SDK driver, schema, store, anchorer, thread
  mutations, attribution split/merge).
- `npm run test:e2e` — `@vscode/test-electron` host E2E
  (create → reply → resolve → persist → reload → re-anchor → orphan; drives
  `cowriting.applyAgentEdit` directly — no LLM required).
- `npm run smoke:live` — scripted live-turn smoke test for F3; requires Claude
  Code installed and signed in. See
  [`docs/MANUAL-SMOKE-F3.md`](docs/MANUAL-SMOKE-F3.md).
- `npm run typecheck` — type-check without emit.