vscode-cowriting-plugin/docs/superpowers/plans/2026-06-11-f7-rendered-track-changes-preview.md

# F7 Rendered Track-Changes Preview Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a read-only webview that renders a markdown document beside its source editor and marks what changed since the F6 baseline (prose `<ins>`/`<del>`, atomic code/mermaid "changed" badge), updating live as the human and Claude edit.

**Architecture:** A pure, vscode-free render engine (`trackChangesModel.ts`) turns `(baselineText, currentText)` into annotated HTML via a block-level diff (LCS over normalized blocks) + word-level prose refinement, with code/mermaid fences kept atomic. A vscode-layer controller (`trackChangesPreview.ts`) owns one sealed webview panel per markdown document, reads the F6 baseline from the reused `DiffViewController`, and posts HTML on open / debounced edit / baseline-epoch change. The webview asset (`media/preview.ts` → `out/media/preview.js`, a separate esbuild bundle) swaps in the HTML and runs `mermaid.run()` over `.mermaid` blocks. The document, sidecar, and baseline are never mutated (INV-20).

**Tech Stack:** TypeScript, VS Code extension API (webview), `markdown-it` + `diff` (host bundle), `mermaid` (webview bundle only), esbuild (two entries), vitest (unit), `@vscode/test-electron` + mocha (host E2E). No LLM anywhere; no network/CDN (INV-21).

**Spec:** `vscode-cowriting-plugin-content/specs/coauthoring-rendered-preview.md` (F7, #21). Invariants INV-20..23.

---

## File Structure

- **Create** `src/trackChangesModel.ts` — pure render engine (INV-22/23). Exports `splitBlocks`, `diffBlocks`, `renderTrackChanges`, types `Block`/`BlockOp`. No vscode, no DOM.
- **Create** `test/trackChangesModel.test.ts` — vitest unit suite for the engine.
- **Create** `media/preview.ts` — webview client: receives `{type:"render", html, epoch, summary}`, swaps `innerHTML`, runs `mermaid.run()`, per-block error chips. Bundles `mermaid`.
- **Create** `media/preview.css` — theme-aware marks (`ins`, `del`, `.cw-added/removed/changed`, `.cw-badge`, `.cw-error`).
- **Create** `src/trackChangesPreview.ts` — `TrackChangesPreviewController` (vscode layer): one panel per markdown doc, sealed CSP shell, debounced refresh, test seam.
- **Create** `test/e2e/suite/trackChangesPreview.test.ts` — host E2E (auto-globbed by `runTest.ts`).
- **Create** `test/e2e/fixtures/workspace/docs/preview.md` — markdown fixture (prose + mermaid + code + a `TARGET` sentence).
- **Create** `test/e2e/fixtures/workspace/docs/notes.txt` — non-markdown fixture (markdown-guard test).
- **Create** `docs/MANUAL-SMOKE-F7.md` — manual smoke script (§6.8).
- **Modify** `src/diffViewController.ts` — additive `onDidChangeBaseline` event fired on every `capture()`.
- **Modify** `src/extension.ts` — construct `TrackChangesPreviewController` (workspace-independent, like F6), add to `CowritingApi`.
- **Modify** `esbuild.mjs` — second entry building `media/preview.ts` → `out/media/preview.js` (IIFE, browser, bundles mermaid).
- **Modify** `package.json` — `markdown-it` + `diff` + `mermaid` deps, `@types/markdown-it` + `@types/diff` devDeps, command + keybinding contributions.
- **Modify** `README.md` — F7 section.

---

## Task 1: Add dependencies and types

**Files:**
- Modify: `package.json`

- [ ] **Step 1: Add runtime + dev dependencies**

Edit `package.json`. In `"dependencies"` add `markdown-it`, `diff`, `mermaid`; in `"devDependencies"` add `@types/markdown-it`, `@types/diff`. Result:

```json
  "dependencies": {
    "@cline/sdk": "0.0.46",
    "diff": "^7.0.0",
    "markdown-it": "^14.1.0",
    "mermaid": "^11.0.0"
  },
  "devDependencies": {
    "@types/diff": "^7.0.0",
    "@types/markdown-it": "^14.1.0",
    "@types/mocha": "^10.0.7",
    "@types/node": "^22.0.0",
    "@types/vscode": "^1.90.0",
    "@vscode/test-electron": "^2.4.0",
    "ajv": "^8.20.0",
    "esbuild": "^0.23.0",
    "glob": "^11.0.0",
    "mocha": "^10.7.0",
    "typescript": "^5.5.0",
    "vitest": "^2.0.0"
  }
```

- [ ] **Step 2: Install**

Run: `npm install`
Expected: lockfile updates, `node_modules/markdown-it`, `node_modules/diff`, `node_modules/mermaid` present, exit 0.

- [ ] **Step 3: Commit**

```bash
git add package.json package-lock.json
git commit -m "feat(f7): add markdown-it + diff + mermaid deps (#21)"
```

---

## Task 2: Block splitting (`splitBlocks`)

**Files:**
- Create: `src/trackChangesModel.ts`
- Test: `test/trackChangesModel.test.ts`

- [ ] **Step 1: Write the failing test**

Create `test/trackChangesModel.test.ts`:

```ts
import { describe, it, expect } from "vitest";
import { splitBlocks } from "../src/trackChangesModel";

describe("splitBlocks", () => {
  it("splits prose paragraphs on blank lines, dropping empties", () => {
    const blocks = splitBlocks("# Heading\n\nFirst para.\n\nSecond para.\n");
    expect(blocks.map((b) => b.type)).toEqual(["prose", "prose", "prose"]);
    expect(blocks[0].raw).toBe("# Heading");
    expect(blocks[2].raw).toBe("Second para.");
  });

  it("keeps a fenced code block whole and tags it `code`", () => {
    const text = "Intro.\n\n```ts\nconst a = 1;\n\nconst b = 2;\n```\n\nOutro.\n";
    const blocks = splitBlocks(text);
    expect(blocks.map((b) => b.type)).toEqual(["prose", "code", "prose"]);
    expect(blocks[1].raw).toBe("```ts\nconst a = 1;\n\nconst b = 2;\n```");
  });

  it("tags a mermaid fence `mermaid`", () => {
    const blocks = splitBlocks("```mermaid\nflowchart LR\n  a-->b\n```\n");
    expect(blocks).toHaveLength(1);
    expect(blocks[0].type).toBe("mermaid");
  });

  it("normalizes the key (whitespace-collapsed) for matching", () => {
    const blocks = splitBlocks("Hello    world\n");
    expect(blocks[0].key).toBe("hello world");
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: FAIL — `splitBlocks` not exported / module missing.

- [ ] **Step 3: Write minimal implementation**

Create `src/trackChangesModel.ts`:

```ts
/**
 * trackChangesModel — F7 pure, vscode-free render engine (spec §6.2, INV-22/23).
 *
 * `renderTrackChanges(baselineText, currentText)` returns the annotated HTML body
 * for the preview webview: a block-level diff (LCS over normalized blocks) with
 * word-level `<ins>`/`<del>` refinement inside changed PROSE blocks, and CODE /
 * MERMAID fences kept ATOMIC (INV-23 — never word-refined, never partially
 * rendered). Deterministic: same inputs → identical HTML (INV-22). No vscode, no
 * DOM — `markdown-it` and `diff` are libraries; mermaid runs later in the webview.
 */
import MarkdownIt from "markdown-it";
import { diffArrays, diffWords } from "diff";

export type BlockType = "prose" | "code" | "mermaid";

export interface Block {
  /** Verbatim source of the block (no surrounding blank lines). */
  raw: string;
  /** Normalized match key: lowercased, whitespace-collapsed. */
  key: string;
  type: BlockType;
}

function normalize(raw: string): string {
  return raw.trim().replace(/\s+/g, " ").toLowerCase();
}

function makeBlock(raw: string, type: BlockType): Block {
  return { raw, key: normalize(raw), type };
}

/** Split markdown into top-level blocks; fenced code/mermaid stay whole. */
export function splitBlocks(text: string): Block[] {
  const lines = text.split(/\r?\n/);
  const blocks: Block[] = [];
  let buf: string[] = [];
  const flushProse = () => {
    const raw = buf.join("\n");
    if (raw.trim()) blocks.push(makeBlock(raw, "prose"));
    buf = [];
  };
  let i = 0;
  while (i < lines.length) {
    const line = lines[i];
    const fence = line.match(/^(\s*)(`{3,}|~{3,})(.*)$/);
    if (fence) {
      flushProse();
      const marker = fence[2][0]; // ` or ~
      const info = fence[3].trim().split(/\s+/)[0].toLowerCase();
      const fenceLines = [line];
      i++;
      while (i < lines.length) {
        fenceLines.push(lines[i]);
        const closed = lines[i].trim().startsWith(marker.repeat(3));
        i++;
        if (closed) break;
      }
      blocks.push(makeBlock(fenceLines.join("\n"), info === "mermaid" ? "mermaid" : "code"));
      continue;
    }
    if (line.trim() === "") {
      flushProse();
      i++;
      continue;
    }
    buf.push(line);
    i++;
  }
  flushProse();
  return blocks;
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: PASS (4 tests).

- [ ] **Step 5: Commit**

```bash
git add src/trackChangesModel.ts test/trackChangesModel.test.ts
git commit -m "feat(f7): block splitter for the render engine (#21)"
```

---

## Task 3: Block diff (`diffBlocks`)

**Files:**
- Modify: `src/trackChangesModel.ts`
- Test: `test/trackChangesModel.test.ts`

- [ ] **Step 1: Write the failing test**

Append to `test/trackChangesModel.test.ts`:

```ts
import { diffBlocks } from "../src/trackChangesModel";

describe("diffBlocks", () => {
  const kinds = (base: string, cur: string) => diffBlocks(base, cur).map((o) => o.kind);

  it("unchanged doc → all unchanged", () => {
    const doc = "Alpha.\n\nBravo.\n";
    expect(kinds(doc, doc)).toEqual(["unchanged", "unchanged"]);
  });

  it("a pure addition → an added op", () => {
    const ops = diffBlocks("Alpha.\n", "Alpha.\n\nBravo.\n");
    expect(ops.map((o) => o.kind)).toEqual(["unchanged", "added"]);
  });

  it("a pure deletion → a removed op", () => {
    const ops = diffBlocks("Alpha.\n\nBravo.\n", "Alpha.\n");
    expect(ops.map((o) => o.kind)).toEqual(["unchanged", "removed"]);
  });

  it("a prose modification → a non-atomic changed op", () => {
    const ops = diffBlocks("The quick fox.\n", "The slow fox.\n");
    expect(ops).toHaveLength(1);
    expect(ops[0].kind).toBe("changed");
    expect(ops[0].kind === "changed" && ops[0].atomic).toBe(false);
  });

  it("a code-fence change → an ATOMIC changed op (INV-23)", () => {
    const base = "```ts\nconst a = 1;\n```\n";
    const cur = "```ts\nconst a = 2;\n```\n";
    const ops = diffBlocks(base, cur);
    expect(ops).toHaveLength(1);
    expect(ops[0].kind).toBe("changed");
    expect(ops[0].kind === "changed" && ops[0].atomic).toBe(true);
  });

  it("a mermaid-fence change → an ATOMIC changed op", () => {
    const base = "```mermaid\nflowchart LR\n a-->b\n```\n";
    const cur = "```mermaid\nflowchart LR\n a-->c\n```\n";
    const ops = diffBlocks(base, cur);
    expect(ops[0].kind).toBe("changed");
    expect(ops[0].kind === "changed" && ops[0].atomic).toBe(true);
  });

  it("a reorder → removed + added (not changed)", () => {
    const ops = diffBlocks("One.\n\nTwo.\n", "Two.\n\nOne.\n");
    // Two. matches (unchanged), One. moves: one removed + one added.
    const k = ops.map((o) => o.kind).sort();
    expect(k).toContain("unchanged");
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: FAIL — `diffBlocks` not exported.

- [ ] **Step 3: Write minimal implementation**

Append to `src/trackChangesModel.ts`:

```ts
export type BlockOp =
  | { kind: "unchanged"; block: Block }
  | { kind: "added"; block: Block }
  | { kind: "removed"; block: Block }
  | { kind: "changed"; block: Block; before: Block; atomic: boolean };

/**
 * Diff two block sequences. Matching is by normalized key (jsdiff `diffArrays`);
 * adjacent removed-then-added runs are paired element-wise into `changed` ops, the
 * surplus staying `removed` / `added`. A `changed` op is ATOMIC (INV-23) when
 * either side is a code/mermaid fence — rendered whole, never word-refined.
 */
export function diffBlocks(baselineText: string, currentText: string): BlockOp[] {
  const before = splitBlocks(baselineText);
  const after = splitBlocks(currentText);
  const changes = diffArrays(
    before.map((b) => b.key),
    after.map((b) => b.key),
  );

  const ops: BlockOp[] = [];
  let bi = 0; // index into `before`
  let ci = 0; // index into `after`
  for (let n = 0; n < changes.length; n++) {
    const ch = changes[n];
    const count = ch.count ?? ch.value.length;
    if (!ch.added && !ch.removed) {
      for (let k = 0; k < count; k++) ops.push({ kind: "unchanged", block: after[ci++] });
      bi += count;
      continue;
    }
    if (ch.removed) {
      const next = changes[n + 1];
      const addCount = next?.added ? (next.count ?? next.value.length) : 0;
      const paired = Math.min(count, addCount);
      for (let k = 0; k < paired; k++) {
        const beforeBlk = before[bi++];
        const afterBlk = after[ci++];
        const atomic = beforeBlk.type !== "prose" || afterBlk.type !== "prose";
        ops.push({ kind: "changed", block: afterBlk, before: beforeBlk, atomic });
      }
      for (let k = paired; k < count; k++) ops.push({ kind: "removed", block: before[bi++] });
      for (let k = paired; k < addCount; k++) ops.push({ kind: "added", block: after[ci++] });
      if (next?.added) n++; // consumed the paired added run
      continue;
    }
    // a lone added run (no preceding removed)
    for (let k = 0; k < count; k++) ops.push({ kind: "added", block: after[ci++] });
  }
  return ops;
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: PASS (all diffBlocks tests + Task 2 tests).

- [ ] **Step 5: Commit**

```bash
git add src/trackChangesModel.ts test/trackChangesModel.test.ts
git commit -m "feat(f7): block-level diff with atomic fences (#21)"
```

---

## Task 4: Render to annotated HTML (`renderTrackChanges`)

**Files:**
- Modify: `src/trackChangesModel.ts`
- Test: `test/trackChangesModel.test.ts`

- [ ] **Step 1: Write the failing test**

Append to `test/trackChangesModel.test.ts`:

```ts
import { renderTrackChanges } from "../src/trackChangesModel";

describe("renderTrackChanges", () => {
  it("wraps each block in a cw-blk div with its kind class", () => {
    const html = renderTrackChanges("Alpha.\n", "Alpha.\n\nBravo.\n");
    expect(html).toContain('class="cw-blk cw-unchanged"');
    expect(html).toContain('class="cw-blk cw-added"');
  });

  it("emits inline <ins>/<del> for a prose modification", () => {
    const html = renderTrackChanges("The quick fox.\n", "The slow fox.\n");
    expect(html).toContain("<ins>");
    expect(html).toContain("<del>");
    expect(html).toContain("cw-changed");
  });

  it("renders a changed CODE fence atomically: cw-changed, no inline ins/del", () => {
    const html = renderTrackChanges("```ts\nconst a = 1;\n```\n", "```ts\nconst a = 2;\n```\n");
    expect(html).toContain("cw-changed");
    expect(html).not.toContain("<ins>");
    expect(html).not.toContain("<del>");
    expect(html).toContain("cw-badge");
  });

  it("emits <pre class=\"mermaid\"> for a mermaid fence + a changed badge", () => {
    const html = renderTrackChanges(
      "```mermaid\nflowchart LR\n a-->b\n```\n",
      "```mermaid\nflowchart LR\n a-->c\n```\n",
    );
    expect(html).toContain('<pre class="mermaid">');
    expect(html).toContain("a--&gt;c"); // current source, escaped
    expect(html).toContain("cw-badge");
  });

  it("unchanged doc renders with no marks", () => {
    const html = renderTrackChanges("Alpha.\n", "Alpha.\n");
    expect(html).not.toContain("cw-added");
    expect(html).not.toContain("cw-removed");
    expect(html).not.toContain("cw-changed");
  });

  it("is deterministic (same inputs → identical HTML) (INV-22)", () => {
    const a = renderTrackChanges("X.\n\nY.\n", "X.\n\nZ.\n");
    const b = renderTrackChanges("X.\n\nY.\n", "X.\n\nZ.\n");
    expect(a).toBe(b);
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: FAIL — `renderTrackChanges` not exported.

- [ ] **Step 3: Write minimal implementation**

Append to `src/trackChangesModel.ts`:

```ts
const md = new MarkdownIt({ html: true, linkify: false, breaks: false });
// mermaid fences → <pre class="mermaid">SRC</pre> for client-side rendering; all
// other fences fall through to markdown-it's default (escaped <pre><code>).
const defaultFence = md.renderer.rules.fence!.bind(md.renderer.rules);
md.renderer.rules.fence = (tokens, idx, options, env, self) => {
  const info = tokens[idx].info.trim().split(/\s+/)[0].toLowerCase();
  if (info === "mermaid") {
    return `<pre class="mermaid">${md.utils.escapeHtml(tokens[idx].content.replace(/\n$/, ""))}</pre>\n`;
  }
  return defaultFence(tokens, idx, options, env, self);
};

/** Build a markdown string with inline <ins>/<del> from a word-level prose diff. */
function wordMergedMarkdown(beforeRaw: string, afterRaw: string): string {
  return diffWords(beforeRaw, afterRaw)
    .map((part) => {
      if (part.added) return `<ins>${part.value}</ins>`;
      if (part.removed) return `<del>${part.value}</del>`;
      return part.value;
    })
    .join("");
}

function safeRender(src: string): string {
  try {
    return md.render(src);
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    return `<div class="cw-error">Could not render this block: ${md.utils.escapeHtml(message)}</div>`;
  }
}

function renderOp(op: BlockOp): string {
  let cls: string;
  let inner: string;
  let badge = "";
  switch (op.kind) {
    case "unchanged":
      cls = "cw-unchanged";
      inner = safeRender(op.block.raw);
      break;
    case "added":
      cls = "cw-added";
      inner = safeRender(op.block.raw);
      if (op.block.type !== "prose") badge = '<span class="cw-badge">added</span>';
      break;
    case "removed":
      cls = "cw-removed";
      inner = safeRender(op.block.raw);
      break;
    case "changed":
      cls = "cw-changed";
      if (op.atomic) {
        inner = safeRender(op.block.raw); // the NEW block, whole (INV-23)
        badge = '<span class="cw-badge">changed</span>';
      } else {
        inner = safeRender(wordMergedMarkdown(op.before.raw, op.block.raw));
      }
      break;
  }
  return `<div class="cw-blk ${cls}">${badge}${inner}</div>`;
}

export interface RenderOptions {
  /** Counts of changed/added/removed blocks, for the header summary. */
  // (reserved; callers derive counts from diffBlocks)
}

/** Pure entry point: annotated HTML body for the preview (INV-22). */
export function renderTrackChanges(baselineText: string, currentText: string): string {
  return diffBlocks(baselineText, currentText).map(renderOp).join("\n");
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: PASS (all render tests).

- [ ] **Step 5: Commit**

```bash
git add src/trackChangesModel.ts test/trackChangesModel.test.ts
git commit -m "feat(f7): render annotated track-changes HTML (#21)"
```

---

## Task 5: Error-chip fallback (PUC-6) made testable

**Files:**
- Modify: `src/trackChangesModel.ts`
- Test: `test/trackChangesModel.test.ts`

**Why:** `safeRender` already catches render errors, but `markdown-it` almost never throws on real input, so the catch is untested. Add a tiny, honest seam: an exported `renderBlockHtml(op, render)` that takes the per-block markdown renderer as a parameter (defaulting to the module's `safeRender`). The unit test injects a renderer that throws for one block to prove the chip appears AND the rest still renders.

- [ ] **Step 1: Write the failing test**

Append to `test/trackChangesModel.test.ts`:

```ts
import { renderTrackChanges as renderWith } from "../src/trackChangesModel";

describe("error chip (PUC-6)", () => {
  it("a block whose render throws becomes an error chip; the rest still renders", () => {
    const throwing = (src: string) => {
      if (src.includes("BOOM")) throw new Error("kaboom");
      return `<p>${src}</p>`;
    };
    const html = renderWith("Good one.\n\nBOOM here.\n", "Good one.\n\nBOOM here.\n", { render: throwing });
    expect(html).toContain("cw-error");
    expect(html).toContain("kaboom");
    expect(html).toContain("<p>Good one.</p>"); // the healthy block still rendered
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: FAIL — `renderTrackChanges` takes only 2 args / `opts.render` ignored.

- [ ] **Step 3: Write minimal implementation**

In `src/trackChangesModel.ts`, replace the `RenderOptions` block and the `safeRender`/`renderOp`/`renderTrackChanges` definitions so the per-block renderer is injectable:

```ts
export interface RenderOptions {
  /** Per-block markdown→HTML renderer (test seam). Defaults to the bundled markdown-it. */
  render?: (src: string) => string;
}

function defaultRender(src: string): string {
  return md.render(src);
}

function chip(message: string): string {
  return `<div class="cw-error">Could not render this block: ${md.utils.escapeHtml(message)}</div>`;
}

function renderOp(op: BlockOp, render: (src: string) => string): string {
  const safe = (src: string): string => {
    try {
      return render(src);
    } catch (err) {
      return chip(err instanceof Error ? err.message : String(err));
    }
  };
  let cls: string;
  let inner: string;
  let badge = "";
  switch (op.kind) {
    case "unchanged":
      cls = "cw-unchanged";
      inner = safe(op.block.raw);
      break;
    case "added":
      cls = "cw-added";
      inner = safe(op.block.raw);
      if (op.block.type !== "prose") badge = '<span class="cw-badge">added</span>';
      break;
    case "removed":
      cls = "cw-removed";
      inner = safe(op.block.raw);
      break;
    case "changed":
      cls = "cw-changed";
      if (op.atomic) {
        inner = safe(op.block.raw);
        badge = '<span class="cw-badge">changed</span>';
      } else {
        inner = safe(wordMergedMarkdown(op.before.raw, op.block.raw));
      }
      break;
  }
  return `<div class="cw-blk ${cls}">${badge}${inner}</div>`;
}

export function renderTrackChanges(
  baselineText: string,
  currentText: string,
  opts: RenderOptions = {},
): string {
  const render = opts.render ?? defaultRender;
  return diffBlocks(baselineText, currentText).map((op) => renderOp(op, render)).join("\n");
}
```

Delete the now-unused standalone `safeRender` function.

- [ ] **Step 4: Run test to verify it passes**

Run: `npx vitest run test/trackChangesModel.test.ts`
Expected: PASS (error-chip test + all prior tests).

- [ ] **Step 5: Typecheck + full unit suite**

Run: `npm run typecheck && npm test`
Expected: PASS, no type errors.

- [ ] **Step 6: Commit**

```bash
git add src/trackChangesModel.ts test/trackChangesModel.test.ts
git commit -m "feat(f7): per-block error-chip fallback (PUC-6, #21)"
```

---

## Task 6: Webview asset (CSS + client JS) and second esbuild entry

**Files:**
- Create: `media/preview.css`
- Create: `media/preview.ts`
- Modify: `esbuild.mjs`

- [ ] **Step 1: Create the stylesheet**

Create `media/preview.css`:

```css
/* F7 track-changes preview — theme-aware via VS Code webview CSS variables. */
body {
  font-family: var(--vscode-font-family);
  font-size: var(--vscode-font-size);
  color: var(--vscode-foreground);
  background: var(--vscode-editor-background);
  padding: 0 1.2rem 2rem;
  line-height: 1.5;
}
#cw-header {
  position: sticky;
  top: 0;
  background: var(--vscode-editor-background);
  border-bottom: 1px solid var(--vscode-panel-border);
  padding: 0.5rem 0;
  font-size: 0.85em;
  opacity: 0.85;
  display: flex;
  gap: 1rem;
}
#cw-summary .cw-add { color: var(--vscode-gitDecoration-addedResourceForeground); }
#cw-summary .cw-del { color: var(--vscode-gitDecoration-deletedResourceForeground); }
.cw-blk { position: relative; }
ins, .cw-added {
  background: var(--vscode-diffEditor-insertedTextBackground, rgba(0, 255, 0, 0.15));
  text-decoration: none;
}
del, .cw-removed {
  background: var(--vscode-diffEditor-removedTextBackground, rgba(255, 0, 0, 0.15));
  text-decoration: line-through;
  opacity: 0.7;
}
.cw-changed { outline: 2px solid var(--vscode-diffEditor-insertedTextBackground, rgba(0, 255, 0, 0.25)); outline-offset: 2px; }
.cw-badge {
  position: absolute;
  top: 0;
  right: 0;
  font-size: 0.7em;
  padding: 0 0.4em;
  border-radius: 3px;
  background: var(--vscode-badge-background);
  color: var(--vscode-badge-foreground);
}
.cw-error {
  border: 1px solid var(--vscode-inputValidation-errorBorder);
  background: var(--vscode-inputValidation-errorBackground);
  color: var(--vscode-errorForeground);
  padding: 0.3rem 0.6rem;
  border-radius: 3px;
  font-size: 0.85em;
}
pre.mermaid { text-align: center; background: transparent; }
pre.mermaid[data-cw-error] { color: var(--vscode-errorForeground); }
```

- [ ] **Step 2: Create the client script**

Create `media/preview.ts`:

```ts
/**
 * F7 preview webview client (sealed sandbox, INV-21). Receives annotated HTML
 * from the extension host and swaps it in; runs mermaid over `.mermaid` blocks
 * (mermaid needs a DOM, so it runs here, not in the host). Bundled by esbuild as
 * a standalone IIFE → out/media/preview.js, so mermaid never enters the host
 * bundle. No network, no LLM.
 */
import mermaid from "mermaid";

interface RenderMessage {
  type: "render";
  html: string;
  epoch: string;
  summary: { added: number; removed: number; changed: number };
}

const body = document.getElementById("cw-body")!;
const header = document.getElementById("cw-epoch")!;
const summary = document.getElementById("cw-summary")!;

function themeFor(): "dark" | "default" {
  return document.body.classList.contains("vscode-dark") ||
    document.body.classList.contains("vscode-high-contrast")
    ? "dark"
    : "default";
}

async function renderMermaid(): Promise<void> {
  const nodes = Array.from(body.querySelectorAll<HTMLElement>("pre.mermaid"));
  if (nodes.length === 0) return;
  mermaid.initialize({ startOnLoad: false, theme: themeFor(), securityLevel: "strict" });
  try {
    await mermaid.run({ nodes });
  } catch {
    // mermaid.run already marks failed nodes; ensure a visible chip per failure.
    for (const n of nodes) {
      if (!n.querySelector("svg")) n.setAttribute("data-cw-error", "true");
    }
  }
}

window.addEventListener("message", (event: MessageEvent<RenderMessage>) => {
  const msg = event.data;
  if (msg?.type !== "render") return;
  body.innerHTML = msg.html;
  header.textContent = `Track changes since ${msg.epoch}`;
  summary.innerHTML =
    `<span class="cw-add">+${msg.summary.added + msg.summary.changed}</span> ` +
    `<span class="cw-del">−${msg.summary.removed + msg.summary.changed}</span>`;
  void renderMermaid();
});
```

- [ ] **Step 3: Add the second esbuild entry**

In `esbuild.mjs`, add a third options object after `liveTurnOptions`, and build it. Insert:

```js
/** @type {import('esbuild').BuildOptions} */
const previewOptions = {
  entryPoints: ["media/preview.ts"],
  outfile: "out/media/preview.js",
  bundle: true,
  // The webview is a browser context; mermaid is bundled IN (and ONLY in) this
  // asset so it never bloats the extension-host bundle (the @cline/sdk size
  // discipline). No externals — everything is shipped to the sealed webview.
  platform: "browser",
  format: "iife",
  target: "es2020",
  sourcemap: true,
  logLevel: "info",
};
```

Then update the watch and build blocks to include it:

```js
if (watch) {
  const ctx = await context(options);
  const ctxLive = await context(liveTurnOptions);
  const ctxPreview = await context(previewOptions);
  await Promise.all([ctx.watch(), ctxLive.watch(), ctxPreview.watch()]);
  console.log("esbuild: watching…");
} else {
  await build(options);
  await build(liveTurnOptions);
  await build(previewOptions);
  console.log("esbuild: build complete → out/extension.cjs + out/liveTurn.mjs + out/media/preview.js");
}
```

- [ ] **Step 4: Build to verify the webview bundle compiles**

Run: `npm run build`
Expected: build complete; `out/media/preview.js` exists (mermaid bundled, a few MB).

- [ ] **Step 5: Commit**

```bash
git add media/preview.ts media/preview.css esbuild.mjs
git commit -m "feat(f7): sealed webview asset + esbuild preview bundle (#21)"
```

---

## Task 7: Additive `onDidChangeBaseline` event on the F6 controller

**Files:**
- Modify: `src/diffViewController.ts`

- [ ] **Step 1: Add the emitter and public event**

In `src/diffViewController.ts`, after the existing `onDidChangeEmitter` field (line ~28), add:

```ts
  /** F7 (additive): fires on every baseline capture (open / advance / pin) so
   *  the track-changes preview refreshes without polling. Mirrors the internal
   *  content-provider change signal but carries the real document URI. */
  private readonly onDidChangeBaselineEmitter = new vscode.EventEmitter<{ uri: string }>();
  readonly onDidChangeBaseline = this.onDidChangeBaselineEmitter.event;
```

- [ ] **Step 2: Fire it on capture, and dispose it**

In the constructor's `this.disposables.push(...)` list, add `this.onDidChangeBaselineEmitter,` alongside `this.onDidChangeEmitter,`.

In `capture(...)`, after the existing `this.onDidChangeEmitter.fire(this.baselineUri(document));` line, add:

```ts
    this.onDidChangeBaselineEmitter.fire({ uri: key });
```

- [ ] **Step 3: Typecheck**

Run: `npm run typecheck`
Expected: PASS.

- [ ] **Step 4: Commit**

```bash
git add src/diffViewController.ts
git commit -m "feat(f7): additive onDidChangeBaseline event on DiffViewController (#21)"
```

---

## Task 8: `TrackChangesPreviewController` (vscode layer)

**Files:**
- Create: `src/trackChangesPreview.ts`

- [ ] **Step 1: Write the controller**

Create `src/trackChangesPreview.ts`:

```ts
/**
 * TrackChangesPreviewController — F7 vscode layer (spec §6.2/§6.4). Owns one
 * sealed webview panel per markdown document, beside the source editor. On open /
 * debounced edit / F6 baseline-epoch change it reads the baseline (from the
 * reused DiffViewController) + the live buffer, runs the pure render engine, and
 * posts the HTML. Pure read-only: never mutates the document, sidecar, or
 * baseline (INV-20). The webview is sealed: local assets only, strict CSP,
 * per-load nonce, no network (INV-21).
 */
import * as path from "node:path";
import { randomBytes } from "node:crypto";
import * as vscode from "vscode";
import type { DiffViewController } from "./diffViewController";
import { renderTrackChanges, diffBlocks, type BlockOp } from "./trackChangesModel";

const VIEW_TYPE = "cowriting.trackChangesPreview";
const DEBOUNCE_MS = 150;

export class TrackChangesPreviewController implements vscode.Disposable {
  private readonly disposables: vscode.Disposable[] = [];
  private readonly panels = new Map<string, vscode.WebviewPanel>();
  private readonly lastModel = new Map<string, BlockOp[]>();
  private readonly debounces = new Map<string, NodeJS.Timeout>();

  constructor(
    private readonly diffView: DiffViewController,
    private readonly extensionUri: vscode.Uri,
  ) {
    this.disposables.push(
      vscode.commands.registerCommand("cowriting.showTrackChangesPreview", () =>
        this.show(vscode.window.activeTextEditor?.document),
      ),
      vscode.workspace.onDidChangeTextDocument((e) => this.onEdit(e.document)),
      this.diffView.onDidChangeBaseline(({ uri }) => this.refreshByUri(uri)),
    );
  }

  private isMarkdown(document: vscode.TextDocument): boolean {
    return document.languageId === "markdown";
  }

  /** Open or reveal the preview for a markdown document (PUC-1). */
  show(document: vscode.TextDocument | undefined): void {
    if (!document || !this.isMarkdown(document)) {
      void vscode.window.showWarningMessage(
        "Cowriting: open a Markdown document to use the track-changes preview (F6 covers other files).",
      );
      return;
    }
    const key = document.uri.toString();
    const existing = this.panels.get(key);
    if (existing) {
      existing.reveal(vscode.ViewColumn.Beside);
      this.refresh(document);
      return;
    }
    const name = path.basename(document.uri.path) || "untitled";
    const panel = vscode.window.createWebviewPanel(
      VIEW_TYPE,
      `Track changes: ${name}`,
      { viewColumn: vscode.ViewColumn.Beside, preserveFocus: true },
      {
        enableScripts: true,
        retainContextWhenHidden: false,
        localResourceRoots: [vscode.Uri.joinPath(this.extensionUri, "out", "media")],
      },
    );
    panel.webview.html = this.shellHtml(panel.webview);
    panel.onDidDispose(() => {
      this.panels.delete(key);
      this.lastModel.delete(key);
    }, null, this.disposables);
    this.panels.set(key, panel);
    this.refresh(document);
  }

  private onEdit(document: vscode.TextDocument): void {
    const key = document.uri.toString();
    if (!this.panels.has(key)) return;
    const pending = this.debounces.get(key);
    if (pending) clearTimeout(pending);
    this.debounces.set(
      key,
      setTimeout(() => {
        this.debounces.delete(key);
        this.refresh(document);
      }, DEBOUNCE_MS),
    );
  }

  private refreshByUri(uri: string): void {
    const doc = vscode.workspace.textDocuments.find((d) => d.uri.toString() === uri);
    if (doc) this.refresh(doc);
  }

  /** Recompute the model + post HTML to the panel (no-op if no panel). */
  refresh(document: vscode.TextDocument): void {
    const key = document.uri.toString();
    const panel = this.panels.get(key);
    if (!panel) return;
    const baseline = this.diffView.getBaseline(key);
    const baselineText = baseline?.text ?? document.getText(); // no baseline → no marks
    const current = document.getText();
    const ops = diffBlocks(baselineText, current);
    this.lastModel.set(key, ops);
    const summary = {
      added: ops.filter((o) => o.kind === "added").length,
      removed: ops.filter((o) => o.kind === "removed").length,
      changed: ops.filter((o) => o.kind === "changed").length,
    };
    const epoch = this.epochLabel(baseline);
    void panel.webview.postMessage({
      type: "render",
      html: renderTrackChanges(baselineText, current),
      epoch,
      summary,
    });
  }

  private epochLabel(
    baseline: { reason: string; capturedAt: string } | undefined,
  ): string {
    if (!baseline) return "opened (no baseline yet)";
    const time = new Date(baseline.capturedAt).toLocaleTimeString();
    switch (baseline.reason) {
      case "machine-landing":
        return `Claude landed ${time}`;
      case "pinned":
        return `pinned ${time}`;
      default:
        return `opened ${time}`;
    }
  }

  private shellHtml(webview: vscode.Webview): string {
    const nonce = randomBytes(16).toString("base64");
    const scriptUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this.extensionUri, "out", "media", "preview.js"),
    );
    const styleUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this.extensionUri, "out", "media", "preview.css"),
    );
    // Sealed CSP (INV-21): no network. 'unsafe-inline' style is required only for
    // mermaid's dynamically injected <style> tags; scripts are nonce-gated and
    // strictly local (no remote/CDN script source).
    const csp =
      `default-src 'none'; ` +
      `img-src ${webview.cspSource} data:; ` +
      `font-src ${webview.cspSource}; ` +
      `style-src ${webview.cspSource} 'unsafe-inline'; ` +
      `script-src 'nonce-${nonce}';`;
    return `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta http-equiv="Content-Security-Policy" content="${csp}" />
  <link href="${styleUri}" rel="stylesheet" />
  <title>Track changes</title>
</head>
<body>
  <div id="cw-header">
    <span id="cw-epoch">Track changes</span>
    <span id="cw-summary"></span>
  </div>
  <div id="cw-body"></div>
  <script nonce="${nonce}" src="${scriptUri}"></script>
</body>
</html>`;
  }

  // ---- test seam (§6.4) ----
  isOpen(uriString: string): boolean {
    return this.panels.has(uriString);
  }
  getLastModel(uriString: string): BlockOp[] | undefined {
    return this.lastModel.get(uriString);
  }

  dispose(): void {
    for (const t of this.debounces.values()) clearTimeout(t);
    for (const p of this.panels.values()) p.dispose();
    for (const d of this.disposables) d.dispose();
  }
}
```

- [ ] **Step 2: Typecheck**

Run: `npm run typecheck`
Expected: PASS.

- [ ] **Step 3: Commit**

```bash
git add src/trackChangesPreview.ts
git commit -m "feat(f7): TrackChangesPreviewController (sealed webview, test seam) (#21)"
```

---

## Task 9: Wire into the extension + package.json contributions

**Files:**
- Modify: `src/extension.ts`
- Modify: `package.json`

- [ ] **Step 1: Add the command + keybinding to package.json**

In `package.json` → `contributes.commands`, add (after `cowriting.pinDiffBaseline`):

```json
      {
        "command": "cowriting.showTrackChangesPreview",
        "title": "Cowriting: Open Track-Changes Preview",
        "category": "Cowriting"
      }
```

In `contributes.keybindings`, add (after the `toggleDiffView` binding):

```json
      {
        "command": "cowriting.showTrackChangesPreview",
        "key": "ctrl+alt+r",
        "when": "editorLangId == markdown"
      }
```

- [ ] **Step 2: Construct and export the controller**

In `src/extension.ts`:

(a) Add the import after the `DiffViewController` import:

```ts
import { TrackChangesPreviewController } from "./trackChangesPreview";
```

(b) Extend the `CowritingApi` interface:

```ts
export interface CowritingApi {
  threadController: ThreadController;
  attributionController: AttributionController;
  proposalController: ProposalController;
  versionGuard: VersionGuard;
  diffViewController: DiffViewController;
  trackChangesPreviewController: TrackChangesPreviewController;
}
```

(c) Right after `context.subscriptions.push(diffViewController);` (the F6 construction, ~line 57), construct F7 (workspace-independent, like F6 — its command must exist with or without a folder):

```ts
  // --- F7: rendered track-changes preview (Feature #21) — workspace-INDEPENDENT ---
  // Like F6, F7 works on any markdown doc (incl. untitled / out-of-folder), so it
  // is constructed regardless of an open folder and its command is always live.
  // It reuses the F6 baseline (INV-20) and adds no persistence.
  const trackChangesPreviewController = new TrackChangesPreviewController(
    diffViewController,
    context.extensionUri,
  );
  context.subscriptions.push(trackChangesPreviewController);
```

(d) In the with-root `return { ... }` statement at the end of `activate`, add the controller:

```ts
  return {
    threadController,
    attributionController,
    proposalController,
    versionGuard,
    diffViewController,
    trackChangesPreviewController,
  };
```

(The no-root early `return undefined;` stays as-is — the command is already registered by the controller constructed above, so it exists without a folder.)

- [ ] **Step 3: Typecheck + build**

Run: `npm run typecheck && npm run build`
Expected: PASS; `out/extension.cjs` and `out/media/preview.js` rebuilt.

- [ ] **Step 4: Commit**

```bash
git add src/extension.ts package.json
git commit -m "feat(f7): register showTrackChangesPreview command + keybinding, wire controller (#21)"
```

---

## Task 10: Host E2E fixtures + suite

**Files:**
- Create: `test/e2e/fixtures/workspace/docs/preview.md`
- Create: `test/e2e/fixtures/workspace/docs/notes.txt`
- Create: `test/e2e/suite/trackChangesPreview.test.ts`

- [ ] **Step 1: Create the markdown fixture**

Create `test/e2e/fixtures/workspace/docs/preview.md`:

```markdown
# Preview fixture

A target sentence Claude will rewrite via the seam.

Some stable prose that does not change during the test run.

```mermaid
flowchart LR
  a --> b
```

```ts
const stable = true;
```
```

(Note: the fixture file literally contains the nested ``` fences shown above.)

- [ ] **Step 2: Create the non-markdown fixture**

Create `test/e2e/fixtures/workspace/docs/notes.txt`:

```
Plain text, not markdown — F7 must refuse this (F6 covers it instead).
```

- [ ] **Step 3: Write the E2E suite**

Create `test/e2e/suite/trackChangesPreview.test.ts`:

```ts
import * as assert from "assert";
import * as path from "path";
import * as vscode from "vscode";
import type { CowritingApi } from "../../../src/extension";

const WS = process.env.E2E_WORKSPACE!;
const DOC_REL = "docs/preview.md";
const docUri = () => vscode.Uri.file(path.join(WS, DOC_REL)).toString();

async function openDoc(rel = DOC_REL): Promise<vscode.TextDocument> {
  const uri = vscode.Uri.file(path.join(WS, rel));
  const doc = await vscode.workspace.openTextDocument(uri);
  await vscode.window.showTextDocument(doc);
  return doc;
}
async function getApi(): Promise<CowritingApi> {
  const ext = vscode.extensions.getExtension("benstull.vscode-cowriting-plugin")!;
  const api = (await ext.activate()) as CowritingApi;
  assert.ok(api?.trackChangesPreviewController, "extension exports trackChangesPreviewController");
  return api;
}
const settle = () => new Promise((r) => setTimeout(r, 400));
const kinds = (api: CowritingApi) =>
  (api.trackChangesPreviewController.getLastModel(docUri()) ?? []).map((o) => o.kind);

// Order-dependent (F2–F6 pattern): later tests consume earlier state.
suite("F7 track-changes preview (host E2E — markdown only, programmatic seam, no LLM)", () => {
  const TARGET = "A target sentence Claude will rewrite via the seam.";
  const REPLACEMENT = "A SENTENCE CLAUDE REWROTE via the seam.";

  test("open on a markdown doc → panel open, opened baseline shows no changes (PUC-1)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    assert.strictEqual(api.trackChangesPreviewController.isOpen(docUri()), false, "no panel yet");
    await vscode.commands.executeCommand("cowriting.showTrackChangesPreview");
    await settle();
    assert.strictEqual(api.trackChangesPreviewController.isOpen(docUri()), true, "panel open");
    const model = api.trackChangesPreviewController.getLastModel(docUri());
    assert.ok(model && model.length > 0, "a model was computed");
    assert.ok(
      model!.every((o) => o.kind === "unchanged"),
      "baseline == buffer at open → every block unchanged",
    );
    // sanity: the active tab is a webview of our view type
    void doc;
  });

  test("typing produces a changed/added block (PUC-2)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const edit = new vscode.WorkspaceEdit();
    // append a brand-new paragraph at the end
    const end = doc.positionAt(doc.getText().length);
    edit.insert(doc.uri, end, "\n\nA freshly typed paragraph.\n");
    assert.ok(await vscode.workspace.applyEdit(edit), "operator edit applied");
    await settle();
    assert.ok(
      kinds(api).some((k) => k === "added" || k === "changed"),
      "an added/changed block appears after typing",
    );
  });

  test("accepting a proposal advances the baseline; the landed block goes unchanged (PUC-3, INV-18)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    const start = doc.getText().indexOf(TARGET);
    assert.ok(start >= 0, "fixture contains the target sentence");
    const id = await vscode.commands.executeCommand<string>("cowriting.proposeAgentEdit", {
      uri: doc.uri.toString(),
      start,
      end: start + TARGET.length,
      newText: REPLACEMENT,
      model: "sonnet",
      sessionId: "e2e-f7",
      turnId: "turn-f7-1",
    });
    assert.ok(id, "propose returns an id");
    assert.ok(await api.proposalController.acceptById(DOC_REL, id!), "accept applies via the seam");
    await settle();
    // The baseline advanced to include REPLACEMENT, so the buffer == baseline for
    // that block → it is NOT marked. Confirm the replacement is not flagged as a change.
    const model = api.trackChangesPreviewController.getLastModel(docUri()) ?? [];
    const replacementMarked = model.some(
      (o) => o.kind !== "unchanged" && o.block.raw.includes("CLAUDE REWROTE"),
    );
    assert.ok(!replacementMarked, "the just-landed text renders unmarked (baseline advanced)");
  });

  test("pin resets the baseline to now → preview shows no marks (PUC-4)", async () => {
    const doc = await openDoc();
    const api = await getApi();
    await vscode.commands.executeCommand("cowriting.pinDiffBaseline");
    await settle();
    assert.ok(
      kinds(api).every((k) => k === "unchanged"),
      "after pin, every block is unchanged (baseline == buffer)",
    );
    void doc;
  });

  test("a non-markdown doc → command warns and opens no panel (PUC-6, markdown-only)", async () => {
    const txt = await openDoc("docs/notes.txt");
    const api = await getApi();
    const key = txt.uri.toString();
    assert.notStrictEqual(txt.languageId, "markdown", "fixture is not markdown");
    await vscode.commands.executeCommand("cowriting.showTrackChangesPreview");
    await settle();
    assert.strictEqual(api.trackChangesPreviewController.isOpen(key), false, "no panel for non-markdown");
  });
});
```

- [ ] **Step 4: Build E2E + run**

Run: `npm run pretest:e2e && npm run test:e2e`
Expected: the new suite passes alongside the existing F2–F6 suites; both workspace and no-workspace passes complete (the no-workspace pass exercises the F2 stubs only — F7's command exists but isn't invoked there). Exit 0.

If the E2E electron download/run is not available in this environment, build at minimum (`npm run pretest:e2e`) to confirm the suite compiles, and note the run in the transcript for the manual smoke / CI.

- [ ] **Step 5: Commit**

```bash
git add test/e2e/suite/trackChangesPreview.test.ts test/e2e/fixtures/workspace/docs/preview.md test/e2e/fixtures/workspace/docs/notes.txt
git commit -m "test(f7): host E2E for the track-changes preview (#21)"
```

---

## Task 11: Manual smoke doc + README section

**Files:**
- Create: `docs/MANUAL-SMOKE-F7.md`
- Modify: `README.md`

- [ ] **Step 1: Write the manual smoke script**

Create `docs/MANUAL-SMOKE-F7.md` following the §6.8 "Live smoke" script. Content:

```markdown
# Manual smoke — F7 rendered track-changes preview (#21)

The webview's *visual* rendering (mermaid, theming) is verified here, not in the
automated host E2E (the webview is a sealed sandbox — §6.8). Run once per change
that touches F7.

## Setup

1. `npm run build`
2. Launch the Extension Development Host (F5 in VS Code, or the Run panel).
3. Open a folder and a markdown document containing prose, a `mermaid` fenced
   diagram, and a `ts` code fence (e.g. copy `test/e2e/fixtures/workspace/docs/preview.md`).

## Steps

1. **Open the preview.** Run **"Cowriting: Open Track-Changes Preview"** (or
   `Ctrl+Alt+R`). A preview opens beside the editor, rendering the document.
   Header reads `Track changes since opened …`, summary `+0 −0`. The mermaid
   diagram renders as a diagram; the code fence renders as highlighted code.
2. **Edit prose.** In the source editor, change a word in a paragraph. The
   preview updates (≈150 ms): the old word struck (`<del>`), the new word
   highlighted (`<ins>`); summary increments.
3. **Edit the mermaid.** Change `a --> b` to `a --> c`. The preview re-renders the
   **new** diagram with a **"changed"** badge at its top-right.
4. **Ask Claude + accept.** Select the target sentence → "Ask Claude to Edit
   Selection" → accept the proposal. The accepted text **drops its marks** (the
   baseline advanced; PUC-3).
5. **Pin.** Run "Cowriting: Pin Diff Baseline to Now". All marks clear (baseline
   == now; PUC-4).
6. **Theme.** Toggle light/dark (`Ctrl+K Ctrl+T`). Marks and the diagram restyle
   to the theme.
7. **Cleanliness.** `git status` shows nothing changed by the preview (INV-20).

## Pass criteria

All seven steps behave as described; no console errors in the webview devtools;
nothing written to the document, sidecar, or repo.
```

- [ ] **Step 2: Add a README F7 section**

In `README.md`, add a section describing F7 (mirroring how F6 is documented):

```markdown
## F7 — Rendered track-changes preview (#21)

`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: prose additions highlighted / deletions struck,
and code/mermaid fences shown whole with a "changed" badge (intra-diagram mermaid
diffing is deferred — #22). It updates live as you and Claude edit, and re-bases
when Claude lands an edit or you pin (reusing the F6 baseline — it adds no
persistence). Mermaid renders fully. F7 is **markdown-only**; for any other file,
use F6's diff toggle (`Ctrl+Alt+D`). Manual smoke: `docs/MANUAL-SMOKE-F7.md`.
```

- [ ] **Step 3: Commit**

```bash
git add docs/MANUAL-SMOKE-F7.md README.md
git commit -m "docs(f7): manual smoke script + README section (#21)"
```

---

## Task 12: Full verification

**Files:** (none — verification only)

- [ ] **Step 1: Typecheck**

Run: `npm run typecheck`
Expected: PASS, no errors.

- [ ] **Step 2: Unit suite**

Run: `npm test`
Expected: all vitest suites pass, including `trackChangesModel.test.ts`.

- [ ] **Step 3: Build**

Run: `npm run build`
Expected: `out/extension.cjs`, `out/liveTurn.mjs`, `out/media/preview.js` all produced.

- [ ] **Step 4: Host E2E**

Run: `npm run test:e2e`
Expected: all suites (F2–F7) green. (If electron is unavailable locally, record that the suite compiles and defer the run to CI / manual smoke — note it in the transcript.)

- [ ] **Step 5: Confirm the repo is clean of preview side effects**

Run: `git status`
Expected: only intended source/doc changes; nothing written under `.threads/` or the workspace by the preview (INV-20).

---

## Self-Review (completed during planning)

**Spec coverage:**
- Rendered preview beside editable source (PUC-1) → Task 8 (`show`, `ViewColumn.Beside`), Task 9 (command).
- Marks since F6 baseline (PUC-2/3), epoch follows machine / pin → Task 7 (`onDidChangeBaseline`), Task 8 (`refresh`), Task 10 (E2E PUC-3/4).
- Full mermaid support (PUC-5) → Task 4 (`<pre class="mermaid">`), Task 6 (`mermaid.run()`).
- Mermaid change = whole-diagram badge (INV-23) → Task 3 (atomic), Task 4 (badge).
- Prose inline ins/del (PUC-2) → Task 4 (`wordMergedMarkdown`).
- Live update on edit + epoch (PUC-2/3/4) → Task 8 (debounce + event sub).
- Pure read-only, no sidecar/contract impact (INV-20) → Task 8 (reads only), Task 12 step 5.
- Sealed webview, no network/LLM, local mermaid (INV-21) → Task 6 (browser bundle), Task 8 (CSP/nonce/localResourceRoots).
- Deterministic testable model (INV-22) → Tasks 2–5 (vscode-free, determinism test).
- Atomic non-prose blocks (INV-23) → Task 3 (atomic flag), Task 4 (no word diff for atomic).
- Graceful edges (PUC-6): non-markdown warn → Task 8/10; error chip → Task 5; no baseline → Task 8 (`baselineText ?? getText()`).
- Unit + host E2E, no LLM in CI (§6.8) → Tasks 2–5 (unit), Task 10 (E2E).

**Placeholder scan:** none — every code step shows complete code.

**Type consistency:** `Block`/`BlockOp` defined in Task 2/3 and consumed unchanged in Tasks 4/5/8; `renderTrackChanges(baselineText, currentText, opts?)`, `diffBlocks`, `getBaseline(uriString)` (existing F6), `onDidChangeBaseline({uri})`, `isOpen`/`getLastModel` consistent across tasks.
```