vscode-cowriting-plugin/docs/superpowers/plans/2026-06-12-f11-preview-toolbar.md

# Implementation Plan: F11 — Preview Toolbar as the Primary Interaction Surface (#43)

**Spec:** `docs/superpowers/specs/2026-06-12-f11-preview-toolbar-interaction-surface.md`
**Anchor:** Feature `benstull/vscode-cowriting-plugin#43` (F11, `type/feature`, `priority/P1`)
**Session:** vscode-cowriting-plugin-0037

This plan transcribes the spec's §7.2 slicing plan into concrete, file-level
tasks. Each slice is independently green (unit + host E2E) before the next. Host
E2E is this app's required tier (no browser/deploy stage — a VS Code extension);
no LLM in CI (edit turns stubbed). The webview's visual rendering, the adaptive
label, and the selection→source DOM lookup are manual-smoke only.

---

## SLICE-1 — Pin baseline button + reachability *(the immediate win)*

Homes the orphaned `cowriting.pinDiffBaseline` command and gives the writer a
reachable Pin control in the preview toolbar.

**Tasks**

1. **Host message routing** (`src/trackChangesPreview.ts`): extract the inline
   `onDidReceiveMessage` body into a private `handleWebviewMessage(document, m)`
   method; add a `pinBaseline` branch that calls `this.diffView.pin(document)`
   (the *previewed* document — not `activeTextEditor`). The existing
   `onDidChangeBaseline` subscription already re-renders with cleared marks.
2. **Test seam**: add `receiveMessage(uriString, m)` that resolves the doc and
   calls `handleWebviewMessage`, so host E2E can simulate the raw webview message
   and exercise the real routing.
3. **Webview** (`media/preview.ts` + `.css`): add a `⌖ Pin baseline` button in
   `#cw-header`; click → `postMessage({ type: "pinBaseline" })`; theme-aware CSS.
4. **Shell HTML** (`shellHtml`): add the `<button id="cw-pin">` to the header row.
5. **Reachability** (`package.json`): flip `cowriting.pinDiffBaseline`'s
   `commandPalette` `when` from `false` to `editorLangId == markdown`.

**Host E2E** (`test/e2e/suite/trackChangesPreview.test.ts` or new f11 suite):
open a markdown fixture with a divergent baseline → some block marked; simulate
`{type:"pinBaseline"}` via `receiveMessage` → `getLastModel` shows every block
`unchanged` (marks cleared) and `getBaseline(key).reason === "pinned"`.

**Unit:** none new (pure layer untouched this slice).

---

## SLICE-2 — Block-offset emission *(INV-36 data layer)*

Shared pure helper wrapping each rendered block with `data-src-start`/`-end`
(source char offsets from `BlockWithRange`) in **both** `renderReview` and
`renderPlain`. vscode-free, DOM-free, deterministic (extends INV-22/33). No UI.

**Tasks**

1. `src/trackChangesModel.ts`: a shared internal helper that prepends
   `data-src-start="N" data-src-end="M"` to each block's wrapping element, routed
   from both render paths using the existing `splitBlocksWithRanges` offsets.
2. Skip blocks with no live-source range (deletion-only / proposal blocks).

**Unit** (`test/trackChangesModel.test.ts`): `data-src-start/end` present and
correct on every block for both modes (offsets equal `BlockWithRange` ranges);
determinism (same inputs → identical HTML).

---

## SLICE-3 — Edit Document button + hunk path *(INV-37 document half)*

**Tasks**

1. `src/trackChangesModel.ts`: pure `diffToHunks(currentText, rewrittenText):
   Array<{ start; end; replacement }>` — vscode-free, deterministic.
2. `src/trackChangesPreview.ts`: `runEditAndPropose(document, target, instruction)`
   private routine; `askClaude`/`document` branch → host `showInputBox` →
   `runEditTurn` over full text → `diffToHunks` → one F4 `propose()` per hunk.
3. `package.json`: register `cowriting.editDocument` (document-scoped), routed
   through `runEditAndPropose({kind:"document"})`; for `#42` reuse.
4. Webview: `✦ Ask Claude to Edit Document` button (no-selection state) →
   `postMessage({ type: "askClaude", scope: "document" })`.

**Unit:** `diffToHunks` over fixtures (single hunk → one range; multi-hunk →
disjoint ranges + correct replacements; unchanged → zero hunks; whole-doc
replacement → one full-range hunk).

**Host E2E:** simulate `{askClaude, scope:"document"}` with a stubbed multi-hunk
rewrite → **N** proposals matching the hunks.

---

## SLICE-4 — Adaptive Edit Selection *(INV-37 selection half; INV-36 consumer)*

**Tasks**

1. Webview: `selectionchange` listener flips the Ask-Claude label (Edit Selection
   ⇆ Edit Document); selection→nearest-`data-src` ancestor resolution →
   `postMessage({ type:"askClaude", scope:"selection", start, end })`.
2. Host: `askClaude`/`selection` branch → `runEditAndPropose({kind:"range",
   start, end})` → one `runEditTurn` → one F4 `propose()` over the block-union.
3. Edge: selection resolving to no live block → fall back to document scope.

**Host E2E:** simulate `{askClaude, scope:"selection", start, end}` with a stubbed
edit turn → exactly **one** proposal over the resolved range, anchored inline.

---

## SLICE-5 — Gateway, edges, tests & docs

**Tasks**

1. `package.json`: add `cowriting.showTrackChangesPreview` to `editor/title` with
   `when: editorLangId == markdown` (minimal right-click gateway).
2. Non-authorable disabling: Pin + Ask-Claude controls render disabled when
   `!isAuthorable(document)`; annotations toggle stays active.
3. Host E2E: gateway command opens the panel; controls inert on non-authorable.
4. `docs/MANUAL-SMOKE-F11.md` (live smoke script per spec §6.8).
5. README F11 section.

---

## Done = #43 acceptance (spec §7.3)

Preview toolbar hosts annotations checkbox + Pin baseline + single adaptive
Ask-Claude (Edit Selection ⇆ Edit Document) routing through existing F4/F3/F6;
edits surface as proposals (one for a selection, per-hunk for a document
rewrite); a right-click entry opens the preview; the pin command is no longer
orphaned; unit + host E2E green; live smoke performed once.