# Solution Design: Authorship view in the rendered preview (F9)

| | |
| --- | --- |
| **Author(s)** | Ben Stull (with Claude) |
| **Status** | `draft` |
| **Version** | v0.1.0 |
| **Anchor** | Feature **F9** (to be captured, ~#27) — builds on F7 `#21` (rendered preview) + F3 `#6` (live attribution). Surfaced as friction during F8 (`#25`) testing: "the preview doesn't show the Claude-composed annotations." |

---

## 1. Problem & context

The F7 rendered track-changes preview (`src/trackChangesPreview.ts` +
`src/trackChangesModel.ts`) answers **"what changed since the F6 baseline?"** It
diffs `baselineText` vs the live buffer and renders author-*agnostic*
`added`/`removed`/`changed` marks. It has never read F3 attribution.

Two facts combine into the friction:

1. The F6 baseline **advances on every machine landing** (INV-18): when a Claude
   proposal is accepted, its text is folded *into* the baseline, so it then reads
   as **unchanged** in track-changes.
2. The preview has **no authorship axis** — it cannot say "Claude composed this
   span" vs "you did."

So a writer who accepts Claude's edits cannot *see* what Claude contributed in the
preview. F3 attribution already records exactly that (Claude=`agent` vs human
spans, char-precise), and F8 made attribution available on **any** authorable doc
(in-folder / out-of-folder / untitled) — the data exists; the preview just doesn't
show it.

**Goal:** add an **Authorship** mode to the preview that renders the current
document with each span colored by its F3 author — Claude (blue) vs you (green) —
inline and char-precise, reading attribution directly (baseline-independent), so
Claude's contributions are visible even after the baseline absorbs them.

## 2. Solution overview

The preview gains a **second mode**, switched by a **segmented control in the
webview header** (`[ Track changes | Authorship ]`); mode is remembered per panel,
default **Track changes** (today's behavior, unchanged).

- **Track changes mode** — unchanged (`renderTrackChanges(baselineText, current)`).
- **Authorship mode** — renders the **current buffer** (no baseline diff) via a new
  pure engine `renderAuthorship(currentText, authorSpans)`, wrapping each
  attributed span in `<span class="cw-by-claude">` / `<span class="cw-by-human">`.
  A header **legend** (● Claude / ● You) appears in this mode. Text with no
  attribution record renders plain.

The two modes are distinct renderings of different axes; authorship mode does **not**
combine with the baseline diff (no `ins`/`del`, no removed text — there is no diff).

## 3. Technical design

### 3.1 The render engine (pure, vscode-free — extends `trackChangesModel.ts`)

New export `renderAuthorship(currentText: string, spans: AuthorSpan[]): string`,
where `AuthorSpan = { start: number; end: number; author: "claude" | "human" }`
(char offsets into `currentText`, non-overlapping). Deterministic (INV-22 extends
to it): same inputs → identical HTML; no vscode, no DOM.

Algorithm:

1. **Block split with offsets.** Reuse `splitBlocks` but track each block's
   `[start, end)` char range in `currentText` (add the offsets to the `Block`
   shape, or a parallel `splitBlocksWithRanges`). Blank-line gaps between blocks
   are outside any block range (consistent with today's whitespace handling).
2. **Per block:**
   - **Prose block:** clip `spans` to the block's range, translate to block-local
     offsets, and inject paired **sentinel markers** at the local boundaries into
     the block's raw markdown — four Unicode Private-Use Area code points: `U+E000`
     (Claude-open) / `U+E001` (Claude-close), `U+E002` (human-open) / `U+E003`
     (human-close). PUA code points never appear in real content and markdown-it
     passes them through as plain text. Render the block with the existing
     markdown-it instance, then **post-process** the HTML: string-replace
     `U+E000`→`<span class="cw-by-claude">`, `U+E001`→`</span>`,
     `U+E002`→`<span class="cw-by-human">`, `U+E003`→`</span>`.
   - **Code / mermaid fence (atomic, INV-23 extends → INV-27):** never inject
     sentinels inside a fence. If any span overlaps the fence, wrap the rendered
     fence in a block div carrying the author class + a small badge
     (`Claude` / `You` / `mixed` when both authors overlap); else render plain.
3. Concatenate block HTML (same join as `renderTrackChanges`). Each block keeps
   the existing per-block `try/catch` → error chip, so a render failure degrades
   to a visible chip, never a throw.

**Known edge case (documented):** a sentinel placed immediately adjacent to active
emphasis markers (`**`, `_`) can perturb markdown-it's inline parsing for that
span. Spans from F3 fall on real edit boundaries, so this is rare; v1 accepts it
(the per-block chip prevents any hard failure) and covers the common cases with
tests. Snapping span boundaries to token-safe positions is a deferred refinement.

### 3.2 Data source & wiring

- **Spans come from F3.** `AttributionController` already maintains live spans as
  current-buffer char ranges with author kind (`getSpans(key)` → `RenderedSpan[]`,
  `authorKind: "human" | "agent"`). Add `spansFor(document): AuthorSpan[]` to
  `AttributionController` — it computes the document key internally
  (`this.keyOf(document)` via the F8 router) and maps `agent→"claude"`,
  `human→"human"`. This resolves the key mismatch (the preview keys panels by
  `document.uri.toString()`; attribution keys by `keyOf`).
- **Preview gains an attribution dependency.** `TrackChangesPreviewController`
  takes `AttributionController` in its constructor. In `extension.ts`, construct
  the authoring stack (router, guard, attribution) **before** the F7 controller
  so the dependency is available (a small, safe reorder — F8 already removed the
  no-root early return, so all controllers are constructed unconditionally).
- **Mode state & toggle.** The controller holds `mode: Map<key, "changes"|"authorship">`
  (default `"changes"`). `refresh(document)` renders the panel's current mode:
  track-changes (existing path) or authorship (`renderAuthorship(current,
  attribution.spansFor(document))`), posting `{type:"render", html, mode, epoch?,
  summary?, legend?}`. The webview header shows the segmented toggle; clicking
  posts `{type:"setMode", mode}` back; the controller updates the map and
  re-renders. Edits/baseline-changes re-render in the current mode.
- **Webview (`media/`):** add the segmented toggle to `#cw-header` and a
  `setMode` message; render the posted HTML into `#cw-body` as today; show/hide
  the epoch+summary (track-changes) vs the legend (authorship) per mode. CSS adds
  `.cw-by-claude` (blue) / `.cw-by-human` (green) + the badge/legend styles,
  themed via VS Code CSS variables (consistent with the existing preview CSS).

### 3.3 Invariants (additions)

- **INV-26 (authorship mode is baseline-independent):** authorship mode renders
  the **current buffer** colored by F3 author, reading `AttributionController`,
  never the F6 baseline. Track-changes mode is unchanged. The two are distinct
  modes, never combined.
- **INV-27 (fences stay atomic in authorship too):** a code/mermaid fence is never
  marked inline; an overlapping author span yields a **block-level** author badge
  (extends INV-23).
- **INV-28 (pure authorship render):** `renderAuthorship(currentText, spans)` is
  vscode-free and deterministic (extends INV-22) — spans are passed as data, so it
  unit-tests with no editor.
- INV-19/20/21 (read-only preview, sealed webview, no persistence/network) carry
  over: authorship mode reads attribution, never mutates the document, sidecar, or
  baseline; no new LLM/network/credential surface.

## 4. Scope

**In scope:** the Authorship mode + header toggle; `renderAuthorship` engine;
`AttributionController.spansFor`; the preview↔attribution wiring + `extension.ts`
reorder; webview toggle/legend/CSS; unit + host E2E + a manual-smoke addendum.

**Out of scope / non-goals:** combining authorship with the diff in one view
(rejected in design — two modes); marking removed text (no diff in authorship
mode); the "untracked / always-there" third author class (rejected — only Claude &
human are colored, unattributed renders plain); intra-emphasis sentinel-safety
hardening (deferred); any change to F3 attribution capture, the seam, persistence,
or the cross-rung contract.

## 5. Testing strategy

- **Unit (vitest, vscode-free):** `renderAuthorship` —
  - single Claude span / single human span → correct wrapper class;
  - two authors in one prose paragraph → exact inline boundaries;
  - span clipped at a block boundary (spans one block only);
  - a code fence and a mermaid fence overlapping a span → block-level badge,
    no inner sentinels (atomic);
  - adjacent same-author spans; a span covering a whole block;
  - empty `spans` → plain render (equals markdown-it of the source);
  - determinism (same inputs → identical HTML).
- **Host E2E (`@vscode/test-electron`, no LLM, extends the F7 suite):** open the
  preview on a markdown doc → land a Claude edit via the `proposeAgentEdit` seam +
  accept → set authorship mode → assert the posted model marks Claude's span as
  Claude-authored (and a human span as human). Assert track-changes mode still
  renders as before (regression).
- **Manual smoke (`docs/MANUAL-SMOKE-F9.md`):** the webview visuals — blue/green
  colors, the header toggle, the legend, a mixed-author paragraph, a Claude-authored
  mermaid fence badge — verified by eye (the sealed webview's rendering isn't
  covered by the E2E).

## 6. Delivery slices

- **SLICE-1** `renderAuthorship` + block-offset split in `trackChangesModel.ts`
  (the sentinel inject/post-process; atomic fences) + unit tests.
- **SLICE-2** `AttributionController.spansFor` + wire it into
  `TrackChangesPreviewController` (constructor dep, `extension.ts` reorder) +
  per-panel mode state + the `setMode` message.
- **SLICE-3** webview header toggle + legend + `.cw-by-*` CSS (`media/`).
- **SLICE-4** host E2E (authorship-mode assertion + track-changes regression) +
  `docs/MANUAL-SMOKE-F9.md` + README F9 note.

**Done =** authorship mode shows Claude's spans (blue) and yours (green) inline on
a markdown doc; the header toggle flips modes; code/mermaid fences get a block
badge; track-changes mode unchanged; unit + host E2E green; smoke performed once.