benstull/vscode-cowriting-plugin-content
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
43913dcbb992a34627240f530696aac51c0fe4be
vscode-cowriting-plugin-con…/specs/coauthoring-interactive-review.md
T

610 lines
37 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
status: graduated
---
# Solution Design: Interactive Track-Changes Review in the Markdown Preview (F10)
| | |
| --- | --- |
| **Author(s)** | Ben Stull (with Claude) |
| **Reviewers / approvers** | Ben Stull |
| **Status** | `draft` |
| **Version** | v0.1.0 |
| **Source artifacts** | Feature `benstull/vscode-cowriting-plugin#29` (F10, `type/feature`, `priority/P1`) · Epic `#1` (closed) · Capture session `vscode-cowriting-plugin-0028` (2026-06-11) · Brainstorming session `vscode-cowriting-plugin-0029` · Builds on (all shipped): F3 `#6` (live attribution), F4 `#12` (propose/accept), F6 `#17`/`#19` (baseline + diff view), F7 `#21`/`#22` (rendered preview + intra-diagram mermaid), F9 `#27` (authorship preview) · Parent specs (graduated): `coauthoring-inner-loop.md`, `coauthoring-attribution.md`, `coauthoring-propose-accept.md`, `coauthoring-diff-view.md`, `coauthoring-rendered-preview.md`, `2026-06-11-authorship-preview-design.md` · Lineage: `ben.stull/rfc-app#48` |
**Change log**
| Date | Version | Change | By |
| --- | --- | --- | --- |
| 2026-06-11 | v0.1.0 | Initial draft — brainstorming session 0029 (from the capture in session 0028, which followed the session-0027 ideation where the operator found the F6 two-pane diff + F3 attribution overlap confusing). | Ben Stull + Claude |
---
## 1. Business Context
### 1.1 Executive Summary
The plugin shipped its review signals as **several overlapping surfaces that
collide on the same text**: F6's two-pane red/green raw diff (`ctrl+alt+d`), F3's
in-editor attribution decorations (green human border / blue Claude fill), F4's
in-editor amber proposal threads, and F7/F9's rendered preview (two modes). In
manual testing the operator opened the F6 diff and saw F3's blue attribution
bleeding into it at the same time — *"I don't understand this."*
F10 resolves this into **one mental model: write on the left, review on the
right.** The editor becomes a **clean, zero-annotation** markdown pane. The
**rendered preview becomes the single review surface**, with an **annotations
on/off** toggle. With annotations **on**, the preview paints every change since
the F6 baseline in one visual language — **green = human-authored, blue =
LLM-authored, strikethrough = deleted** — and lets the human **accept (✓) or
reject (✗) Claude's pending proposals, and only those, right inside the
preview.** F10 is **mostly assembly** of shipped features (F3/F4/F6/F7/F9) plus
three new pieces: strip the editor decorations, collapse F9's two preview modes
into the one toggle, and make the preview interactive.
### 1.2 Background
The inner loop shipped F2–F5 (threads · attribution · propose/accept ·
cross-rung). F6 added the baseline + a native two-pane diff toggle (`#17`),
broadened to any file (`#19`). F7 added the rendered track-changes preview
(`#21`) with full mermaid support, refined by F7.1 intra-diagram mermaid diffing
(`#22`). F9 added an **Authorship** mode to that preview (`#27`), switched by a
segmented `[ Track changes | Authorship ]` header control — and F9 **explicitly
chose two separate modes, never combined** (F9 INV-26).
The friction the operator hit is the *multiplicity* of surfaces, not any one of
them: the two-pane raw diff is low-altitude for prose; the in-editor decorations
clutter the writing surface (the human authored most of the document, so
attribution paints everywhere); and there is no single place to answer "what
changed, who changed it, and do I keep the LLM's edits?" Capture session 0028
filed Feature `#29` locking the product vision (markdown-only; clean editor;
preview as the single review surface). This spec is the Solution Design for it.
### 1.3 Business Actors / Roles
- **Coauthor (human)** — the writer/engineer (PP-1); F10's sole user.
- **Coauthor (machine)** — Claude via `@cline/sdk`; not a user of F10, but its
proposals are what the human reviews in the preview, and its landings advance
the F6 baseline.
### 1.4 Problem Statement
A markdown writer reviewing a coauthoring session has **no single, intuitive
surface** that answers "what changed since the last coauthoring moment, who
changed it, and do I keep Claude's edits?" The signal is fragmented across a raw
two-pane diff, in-editor decorations, and a two-mode preview that shows changes
**or** authorship but never both, and never lets the human act on Claude's
proposals from inside the rendered view.
### 1.5 Pain Points
- **Surface collision** — F6's raw diff and F3's attribution paint the same text
simultaneously and read as noise ("I don't understand this").
- **Cluttered editor** — F3 attribution + F4 proposal threads decorate the
writing pane; since the human authored most of the document, attribution paints
nearly everywhere.
- **Two-pane raw diff is low-altitude for prose** — you read markdown source, not
the rendered document.
- **Changes XOR authorship** — F9's preview shows *what changed* (track-changes)
or *who authored* (authorship) but never both in one glance, and neither lets
you accept/reject from the rendered view.
### 1.6 Targeted Business Outcomes
One clean model: **write on the left, review on the right.** The editor is
distraction-free (zero annotations). The preview, with annotations on, shows
every change since the baseline in one visual language **and** lets the human
keep or revert Claude's proposals without leaving that pane — so "what did the
LLM change, and do I want it?" is answered **in place**, in the rendered
document, not in a raw diff or a cluttered editor.
### 1.7 Scope (business)
**In scope:** a clean (zero-annotation) markdown editor; the rendered preview as
the **single** review surface; an **annotations on/off** toggle (off = clean
rendered markdown, built-in-preview parity; on = the combined annotated view);
the unified per-author + strikethrough annotation language (green human / blue
LLM / struck deletions, reconstructed from the F6 baseline); **interactive
accept/reject of Claude's pending proposals from inside the preview** (✓/✗);
deprecating F6's two-pane view (command + keybinding hidden) and stripping the
editor's F3/F4 decorations; unit + host-E2E coverage; manual webview smoke.
**Out of scope (deferred, not forgotten):** **non-markdown review** (F6's
any-file reach `#19` is dropped *as a user goal* — see §6.7); the **repo rename**
to `vscode-markdown-cowriting-plugin` (the markdown-only identity is affirmed,
but the rename — Gitea repo, `app.json`, content repo, session-history paths — is
a separate deliberate gesture); preview→source **scroll-sync**; export / print /
copy-as-clean; **editing in the preview** beyond the ✓/✗ proposal controls;
intra-emphasis sentinel hardening (the F9 deferred refinement).
**Non-goals (firm):** any change to the **sidecar** persistence, the **F4
propose/accept model** (proposals stay pending-by-default — F10 surfaces and acts
on them, it does **not** change how Claude's edits enter the system), the
**cross-rung contract**, or `SCHEMA_VERSION`; a general-purpose markdown
previewer; a WYSIWYG editor; combining anything with the LLM/network/credential
surface (INV-8 untouched).
### 1.8 Assumptions · Constraints · Dependencies
- **Anchor:** Feature `#29` (F10). **Mostly assembly** of shipped features:
- **F6 baseline** (`#17`/`#19`) — kept as the **data layer** ("what changed
since when"; auto-advances at every machine landing, INV-18); F6's two-pane
*view* is deprecated as a user surface (command/keybinding hidden, code kept).
- **F7 render/diff engine** (`#21`/`#22`) — the rendered preview, block/word
diff, strikethrough deletions, atomic code/mermaid, and F7.1 intra-diagram
mermaid diff already exist and are reused.
- **F3 attribution** (`#6`) — kept as the **data layer** (`spansFor` — who
authored each span); its *in-editor decorations* are removed.
- **F4 propose/accept** (`#12`) — the accept/reject *logic*
(`ProposalController.accept`/`reject` → `applyAgentEdit`, the INV-9
`WorkspaceEdit` seam) already exists; F10 moves the *controls* into the
preview and removes the in-editor proposal threads.
- **F9 authorship preview** (`#27`) — its two preview modes **collapse** into
the one annotations on/off toggle; its PUA-sentinel author-coloring technique
is **reused** inside the new combined render; its standalone
`renderAuthorship` / segmented control are **superseded** (removed).
- **Constraint:** the preview is a **sealed webview** (strict CSP, local assets,
no network — F7 INV-21). Interactive ✓/✗ controls post messages to the
extension host, which applies/discards proposals via the F4 path; the webview
**never** edits the document directly.
- **Constraint:** deletions aren't in the live buffer — they are reconstructed by
diffing the buffer against the F6 baseline (the F7 engine already does this).
- No LLM, no network, no new credential surface (INV-8 untouched); nothing
persisted changes (`.threads/`, the contract, `SCHEMA_VERSION` all untouched).
### 1.9 Business Use Cases
- **BUC-1 (unified review)** Mid-session the writer opens the preview and sees the
rendered chapter with their own additions in green, their deletions struck, and
Claude's pending proposals as blue blocks carrying ✓/✗ — one glance answers
"what changed, who, and do I keep Claude's edits?"
- **BUC-2 (act in place)** The writer clicks ✓ on a Claude proposal in the
preview; the proposal lands in the document, the baseline advances, and the
blue block becomes ordinary (unmarked) text — without leaving the preview or
touching the editor.
- **BUC-3 (clean writing)** The writer works in the editor, which shows **no**
coauthoring decorations at all — a plain markdown surface — and flips
annotations **off** in the preview to read the document clean (built-in-preview
parity) when they want to.
---
## 2. Solution Proposal
The editor is stripped of **all** coauthoring decorations (F3 attribution tint,
F4 proposal threads), and F6's two-pane diff command/keybinding are hidden
(`when:false`); the F6 baseline store and `onDidChangeBaseline` event remain as
the data layer.
The preview's per-panel mode collapses from F9's `"changes" | "authorship"` to a
single **`"on" | "off"`** annotations toggle (default **on**):
- **Off** — plain `markdown-it` render of the current buffer, no marks (parity
with VS Code's built-in markdown preview).
- **On** — a **combined annotated render** produced by one new **pure,
vscode-free** engine, `renderReview(baselineText, currentText, authorSpans,
proposals)`, that overlays **two axes in a single pass**:
1. **Changes since the F6 baseline** — the F7 block + word diff of
`baselineText` vs `currentText`: additions and deletions, **author-colored**
via F3 `authorSpans` (human → green, agent → blue) using F9's PUA-sentinel
technique; deletions rendered **struck** (reconstructed from the baseline).
2. **Pending Claude proposals** — each F4 pending proposal rendered **inline at
its resolved anchor** as a **blue block** (the replaced text struck, the
proposed text shown) carrying a `data-proposal-id` and **✓/✗ buttons**.
The webview becomes **interactive**: clicking ✓/✗ posts `{type: "accept" |
"reject", proposalId}` to the host, which calls `ProposalController.accept` /
`reject` — accept runs the existing `applyAgentEdit` `WorkspaceEdit` seam and
advances the baseline (INV-18), reject discards the proposal; either way the host
re-renders. The webview never mutates the document (INV-20/21 hold). Everything
downstream of `(baseline, current, spans, proposals) → HTML` is a pure function
(INV-33), unit-testable with no vscode and no webview.
Because proposals are now **preview-only**, a small **status-bar indicator**
("N Claude proposals — open review", clickable to open the preview) signals
pending proposals when no preview is open (§6.5 PUC-6).
---
## 3. Product Personas
- **PP-1 Inner-loop coauthor** — the human markdown writer/engineer (as F2–F9);
the only persona F10 serves.
## 4. Product Use Cases
- **PUC-1 (clean editor)** Opening / editing a markdown document shows a plain
editor with **no** coauthoring decorations (no F3 tint, no F4 threads, no F6
diff). The writing surface is distraction-free.
- **PUC-2 (toggle annotations)** In the preview, a header switch flips
annotations **on** (combined annotated render) / **off** (clean rendered
markdown). Default on. Mode is remembered per panel.
- **PUC-3 (see who changed what)** With annotations on, the writer's additions
since the baseline render **green**, their deletions render **struck**, and
Claude's pending proposals render as **blue** blocks. One visual language.
- **PUC-4 (accept a proposal)** The writer clicks **✓** on a blue proposal → it
lands in the document via the F4 seam → the baseline advances → the block
re-renders as ordinary (unmarked) text. The editor reflects the new text, still
with no decorations.
- **PUC-5 (reject a proposal)** The writer clicks **✗** on a blue proposal → the
proposal is discarded → the block disappears on re-render → the document is
unchanged.
- **PUC-6 (proposal while no preview open)** Claude proposes while no preview is
open → a **status-bar item** ("N Claude proposals — open review") appears;
clicking it opens the preview where the proposals are reviewable. (No forced
auto-open — the writer stays in control of focus.)
- **PUC-7 (graceful edges)** Non-markdown active editor → the open command warns
and opens nothing (markdown-only). A malformed markdown/mermaid block → an
inline error chip for that block, the rest renders. No baseline yet → render
current doc with **no** change-marks (everything is "since opened") + a header
note; proposals (if any) still render with ✓/✗.
## 5. UX Layout
A webview in the editor column **beside** the source (`ViewColumn.Beside`). The
source editor stays fully editable but is now **visually clean** — no coauthoring
decorations. The preview is **read-only rendered output** except for the ✓/✗
proposal controls, which post intent (never edit the doc directly). With
annotations **on**:
- **Human additions** since baseline — soft green background (`cw-by-human` over
`<ins>`), themeable.
- **LLM-authored text** (already landed, attributed by F3) — soft blue
(`cw-by-claude`).
- **Deletions** — struck-through, muted (`<del class="cw-del">`), reconstructed
from the baseline.
- **Pending Claude proposal** — a **blue proposal block**: the text it would
replace shown struck, the proposed text shown, and a compact **✓ / ✗** control
pair in the block's corner (`data-proposal-id` on the block).
- **Atomic blocks** (code / mermaid) — diffed whole (INV-23) with F7.1
intra-diagram mermaid styling for changed flowchart/sequence diagrams; an
overlapping author span yields a block-level author badge (F9 INV-27).
- A compact **header bar**: the annotations **on/off** switch; in the on state, a
`Since <epoch>` label (reusing F6's epoch text) + a `+N −M · P proposals`
summary and the legend (● You · ● Claude · ✓/✗ = accept/reject Claude).
Colors derive from the active VS Code theme via webview CSS variables (light /
dark / high-contrast); proposal-block and ✓/✗ button styling are bespoke but
theme-variable-driven.
---
## 6. Technical Design
### 6.1 Invariants
Parent invariants INV-1..INV-31 carry over **except where F10 supersedes them**.
F10 adds:
- **INV-32 (single review surface; clean editor)** The rendered preview is the
**only** annotated review surface. The editor carries **zero** coauthoring
decorations: F3 attribution decorations, F4 in-editor proposal threads, and the
F6 two-pane diff are all removed from / hidden in the editor. (F3 `spansFor`,
F4 accept/reject logic, and the F6 baseline store remain as **data layers**.)
- **INV-33 (combined pure render)** The "on" render unifies two axes —
changes-since-baseline (author-colored additions + struck deletions) **and**
interactive pending proposals — in **one pass** of a pure, vscode-free,
DOM-free function `renderReview(baselineText, currentText, authorSpans,
proposals): string`: same inputs → identical HTML (extends INV-22). The "off"
render is the plain `markdown-it` of the current buffer.
- **INV-34 (✓/✗ act only on pending Claude proposals, via the F4 seam)**
Interactive controls appear **only** on pending Claude proposals (blocks
carrying `data-proposal-id`); human (green) changes carry no controls. ✓/✗ post
**intent** to the host; **all** document mutation goes through the existing F4
`ProposalController.accept`/`reject` → `applyAgentEdit` (`WorkspaceEdit`) seam
(INV-9). The webview never mutates the document, sidecar, or baseline
(INV-20/21 hold).
**Supersession (explicit):** F10 **reverses F9 INV-26** ("authorship mode is
baseline-independent and never combined with the diff"). F10 *combines* the
authorship axis with the change axis by design; F9's standalone authorship mode
and segmented control are removed. F9 INV-27 (atomic fences get a block-level
author badge) and INV-28 (pure authorship render) are **absorbed** into INV-33
(the combined render keeps fences atomic and stays pure).
### 6.2 High-level architecture
Three reused data layers + one new pure render path + an interactive webview.
```mermaid
flowchart LR
edit["source editor\n(clean — no decorations)"] -- onDidChangeTextDocument (debounced) --> ctl
base["F6 baseline\n(DiffViewController, INV-18)"] -- onDidChangeBaseline --> ctl["trackChangesPreview\n(vscode layer)"]
attr["F3 AttributionController\nspansFor(doc)"] -- author spans --> ctl
prop["F4 ProposalController\npending proposals"] -- onDidChangeProposals --> ctl
ctl -- "(baseline, current, spans, proposals)" --> model["renderReview\n(pure, vscode-free)\nblock+word diff · author sentinels · proposal blocks"]
model -- annotated HTML --> ctl
ctl -- postMessage{html, mode, summary} --> wv["webview\n(sealed CSP, local assets)\nmermaid.run() · ✓/✗ buttons"]
wv -- "postMessage{accept|reject, proposalId}" --> ctl
ctl -- "accept/reject" --> prop
prop -- "applyAgentEdit (WorkspaceEdit)" --> doc[(document)]
prop -- accept --> base
```
- **`trackChangesModel.ts`** (pure, vscode-free — INV-33) gains
**`renderReview(baselineText, currentText, authorSpans, proposals): string`**.
Internals: (1) the existing F7 `diffBlocks` over baseline/current → block ops;
(2) for changed/added **prose**, the existing word-level `<ins>`/`<del>`,
**then** author-color each `<ins>` (and live text) by intersecting `authorSpans`
via the F9 **PUA-sentinel** technique (refactored out of `renderAuthorship`
into a shared `colorByAuthor` helper); (3) **inject proposal blocks**: for each
proposal, resolve its anchor offset in `currentText`, emit a
`<div class="cw-proposal" data-proposal-id="…">` containing the struck
replaced-text and the proposed text + a `<span class="cw-actions">✓ ✗</span>`
placeholder rendered by the webview; (4) atomic code/mermaid unchanged (F7.1
reused). Off-mode calls a thin `renderPlain(currentText)` (markdown-it only).
- **`trackChangesPreview.ts`** (vscode layer) — `mode: Map<key, "on"|"off">`
(default `"on"`, replacing F9's `"changes"|"authorship"`); gains a
**`ProposalController` dependency** and subscribes to a F4
`onDidChangeProposals` event (additive, mirroring F6's `onDidChangeBaseline`)
alongside the existing edit + baseline triggers; on the new
`{accept|reject, proposalId}` inbound message, calls
`ProposalController.accept`/`reject` then re-renders; owns the **status-bar
item** (PUC-6).
- **Webview asset** (`media/preview.ts` + `.css`) — header **on/off** switch
(replacing the segmented control); **inbound** click handler on `.cw-actions`
buttons → `postMessage({accept|reject, proposalId})` (nonce-gated inline
script, CSP-safe); proposal-block + ✓/✗ button CSS; reuses the existing
`mermaid.run()` swap. Stays sealed (INV-21).
- **F3 `AttributionController`** — remove the `render()` `setDecorations` calls
and dispose the decoration types; **keep** `spansFor`. Retire/hide
`cowriting.toggleAttribution`.
- **F4 `ProposalController`** — remove the in-editor proposal-thread decorations
and the in-editor accept/reject codelens/commands' UI; **keep**
`accept`/`reject`/`propose`. Add `listProposals(document): ProposalView[]`
(anchor offset + replacement + id) and `onDidChangeProposals` for the preview.
- **F6 `DiffViewController`** — unchanged code; `cowriting.toggleDiffView` +
`ctrl+alt+d` set `when:false` in `package.json`.
### 6.3 Data model & ownership
**No new persisted artifact** (INV-20). F10 holds only in-memory webview panels
keyed by document URI + the per-panel on/off mode + the status-bar item. The
baseline is owned by F6; proposals by F4 (sidecar); attribution by F3. The only
on-the-wire models are transient:
```ts
// host → webview (transient HTML payload)
type RenderMsg = {
type: "render"; mode: "on" | "off"; html: string;
epoch?: string; summary?: { added: number; removed: number; proposals: number };
};
// webview → host (intent only — INV-34)
type ActionMsg =
| { type: "setMode"; mode: "on" | "off" }
| { type: "accept"; proposalId: string }
| { type: "reject"; proposalId: string };
// internal to renderReview (illustrative — not persisted)
type ProposalView = { id: string; anchorStart: number; anchorEnd: number; replacement: string };
```
### 6.4 Interfaces & contracts
- **`trackChangesModel`** (vscode-free): `renderReview(baselineText: string,
currentText: string, authorSpans: AuthorSpan[], proposals: ProposalView[]):
string` — annotated HTML for the on-state body; deterministic (INV-33).
`renderPlain(currentText: string): string` — off-state body. Exports
`colorByAuthor(html-or-blocks, spans)` (the salvaged F9 sentinel helper) for
unit tests. **Removes** the public `renderAuthorship` (superseded);
`renderTrackChanges` is retained internally / folded into `renderReview`.
- **`TrackChangesPreviewController`** (vscode layer): `show(document)`,
`refresh(document)` (debounced), `setMode(uriString, "on"|"off")` (test seam),
`getLastModel(uriString)` (test seam — the last computed block/proposal model,
so host E2E asserts marks without reading webview DOM). Constructor now takes
`AttributionController` **and** `ProposalController`.
- **`AttributionController`** (additive removal): `render()` no longer applies
editor decorations; `spansFor(document): AuthorSpan[]` unchanged.
- **`ProposalController`** (additive): `listProposals(document): ProposalView[]`;
`readonly onDidChangeProposals: vscode.Event<{ uri: string }>` fired on
propose/accept/reject. `accept`/`reject`/`applyAgentEdit` unchanged.
- **`DiffViewController`** (F6) — unchanged; only its `package.json`
command/keybinding `when` flips to `false`.
- **Commands / keybindings** (`package.json`): `cowriting.showTrackChangesPreview`
("Cowriting: Open Review Preview", `ctrl+alt+r`, `when: editorLangId ==
markdown`) — retitled, kept. `cowriting.toggleDiffView` + `ctrl+alt+d`,
`cowriting.toggleAttribution`, and the in-editor `cowriting.acceptProposal` /
`cowriting.rejectProposal` palette entries → `when:false` (hidden; the seams
stay for tests/programmatic use). Status-bar item registered in `extension.ts`.
### 6.5 Per–Product-Use-Case design
- **PUC-1 (clean editor):** delete `AttributionController.render`'s
`setDecorations` + decoration-type creation; remove F4's in-editor proposal
decorations. Editor shows plain text.
- **PUC-2 (toggle):** header switch → `{type:"setMode", mode}` → controller
updates the per-panel map → re-render. Off = `renderPlain`; on = `renderReview`.
- **PUC-3 (who changed what):** `renderReview` overlays the F7 baseline diff
(author-colored via F9 sentinels) + proposal blocks.
- **PUC-4 (accept):** `{type:"accept", id}` → `ProposalController.accept(state,
proposal)` → `applyAgentEdit` `WorkspaceEdit` (INV-9) → baseline advances
(INV-18) → `onDidChangeBaseline` + `onDidChangeProposals` → re-render (block now
ordinary text).
- **PUC-5 (reject):** `{type:"reject", id}` → `ProposalController.reject` →
proposal removed from sidecar → `onDidChangeProposals` → re-render (block gone);
document untouched.
- **PUC-6 (proposal while no preview):** on `onDidChangeProposals`, if no panel
is open for the doc, show/update a status-bar item with the pending count,
`command = cowriting.showTrackChangesPreview`. Hidden when count = 0 or a panel
is open.
- **PUC-7 (edges):** non-markdown → `showWarningMessage`, no panel. Per-block
`try/catch` → error chip (F7). No baseline → render with no change-marks + a
note; proposals still render.
### 6.6 Non-functional requirements & cross-cutting concerns
Render cost is O(document) on a debounced edit / proposal change — fine at
inner-loop scale (large-doc debounce/idle cap is the F7 tunable, not v1
critical). The webview stays **sealed** (INV-21): local assets, strict CSP with a
per-load nonce, no network; mermaid lives only in the webview bundle. The ✓/✗
buttons are host-rendered HTML with `data-proposal-id`; the nonce'd inline script
only reads those ids and posts intent (no eval, no remote). No telemetry, no LLM,
no credentials, nothing persisted.
### 6.7 Key decisions & alternatives considered
| Decision | Chosen | Alternatives rejected |
| --- | --- | --- |
| **Where Claude's reviewable changes come from** | **Pending F4 proposals surfaced in the preview** — keep propose-by-default; ✓ = F4 accept (apply + advance baseline), ✗ = F4 reject. | **Apply-then-review** (LLM edits land in the buffer; ✓/✗ pin/revert per span) — reverses F4 INV-10/11 and needs new per-span baseline machinery. **Both axes overlaid** (landed-LLM authorship + pending proposals + human diff) — richest but most rendering complexity; deferred. *(Operator decision, session 0029.)* |
| **Editor decoration scope** | **Fully clean** — strip F3 attribution **and** F4 proposal threads; proposals are **preview-only**. | **Strip F3 only, keep amber threads** — editor isn't truly "zero annotations"; two proposal surfaces to keep in sync. *(Operator decision, session 0029.)* |
| **F6 two-pane diff** | **Hide** command + `ctrl+alt+d` (`when:false`); keep the controller + baseline store. | **Delete the view code now** — larger, less reversible diff; a later cleanup PR can remove the dead view. *(Operator decision, session 0029.)* |
| **F9's two modes** | **Collapse** into one **on/off** toggle; on = combined render; off = plain markdown. Remove `renderAuthorship` + segmented control. | **Keep three modes** (changes / authorship / combined) — re-introduces the very surface-multiplicity F10 removes. |
| **Combined render approach** | **One pure `renderReview`** overlaying diff + author sentinels + proposal blocks (extends INV-22). | **Compose two HTML passes in the webview** — pushes logic into the sealed sandbox, loses unit-testability (INV-33). |
| **Proposal-while-no-preview** | **Status-bar indicator** (clickable to open). | **Force auto-open the preview** — hijacks focus, fights "write left, review right." *(Deferred decision — cheap to flip to auto-open.)* |
| **Deletion coloring** | **Neutral struck** (`cw-del`), per the issue's "strikethrough = deleted". | **Color the strikethrough by who deleted** — adds a fourth signal for marginal value. |
| **Non-markdown review** | **Dropped as a goal** (markdown-only product). | **Keep F6's any-file reach** — contradicts the locked product vision; rename to a markdown-specific identity is the eventual corollary (deferred). |
### 6.8 Testing strategy
- **Unit (vitest, vscode-free):** `renderReview` over fixtures — human addition
(green `<ins>`), human deletion (struck `cw-del`), a proposal **insert** (blue
`cw-proposal` block + `data-proposal-id` + ✓/✗ markup), a proposal **replace**
(struck old + proposed new in one block), mixed human+proposal in a paragraph,
an atomic code fence + a changed mermaid fence (F7.1 augmentation intact, no
inner sentinels), **off-mode** = plain markdown (`renderPlain` equals
markdown-it of source), determinism (same inputs → identical HTML). `colorByAuthor`
helper unit tests (salvaged F9 cases). Proposal-anchor resolution edge: an
unresolvable fingerprint → the proposal is rendered as a trailing block, never
dropped silently.
- **Host E2E (`@vscode/test-electron`, no LLM, extends the F7/F9 suite):** open a
markdown fixture → `cowriting.showTrackChangesPreview` → assert panel open +
`getLastModel` (opened baseline → no change-marks). Type → an `added` block,
author = human. `proposeAgentEdit` seam → `getLastModel` shows a proposal op
with id; **simulate `{type:"accept", id}`** → proposal applied, baseline
advanced, block now `unchanged`/ordinary; **`{type:"reject", id}`** → proposal
gone, document text unchanged. Assert the **editor has no decorations** (the F3
decoration types are not created / applied). Assert `toggleDiffView` is not in
the active command set (or its `when` is false). Non-markdown doc → command
warns, no panel. Status-bar item appears on a proposal with no panel open.
Webview DOM / real button clicks are **not** E2E-asserted (sealed sandbox) —
manual smoke.
- **Live smoke (manual — `docs/MANUAL-SMOKE-F10.md`):** open a markdown doc;
confirm the editor is clean (no tint/threads); edit prose (green ins / struck
del); ask Claude to edit a selection → a blue proposal block with ✓/✗ appears
in the preview; click ✓ (lands, mark clears) and ✗ on another (block vanishes,
doc unchanged); toggle annotations off (clean render) / on; verify the
status-bar indicator with no preview open; verify light/dark theming and that
`git status` shows nothing.
### 6.9 Failure modes, rollback & flags
`markdown-it`/`mermaid` throwing on a block → inline error chip (F7), preview
still renders. A proposal whose fingerprint no longer resolves → rendered as a
trailing "unanchored proposal" block with ✓/✗ (never silently dropped — INV-34
must remain actionable). Webview disposed → controller drops the panel + clears
the status-bar item; re-run the command to reopen. **No feature flag** — the
preview is a pure read-only view (INV-20); not opening it is the off state.
Rollback is reverting the PR with **zero** data migration (nothing persisted; the
F6 baseline, F4 sidecar, F3 attribution data are untouched, so the hidden/removed
UI can be restored). The clean-editor change is mostly deletion of decoration
calls — trivially reversible.
---
## 7. Delivery Plan
### 7.1 Approach / strategy
One planning-and-executing session (F10 = `#29`), plan written just-in-time from
this spec — the F2–F9 precedent. Host-E2E tier (a VS Code extension has no
browser/deploy stage); no LLM in CI. The webview's *visual* rendering and real
button clicks are verified by the manual smoke; the automated seams are the pure
render **model** and the host's accept/reject wiring.
### 7.2 Slicing plan
- **SLICE-1 — Clean editor.** Strip F3 attribution decorations
(`AttributionController.render`) + F4 in-editor proposal threads; hide
`toggleDiffView`/`ctrl+alt+d` + `toggleAttribution` (`when:false`). Host E2E:
no editor decorations. *(Mostly deletion.)*
- **SLICE-2 — Combined render engine.** `renderReview` + `renderPlain` in
`trackChangesModel.ts`; salvage `colorByAuthor` from `renderAuthorship`; remove
the public `renderAuthorship`; proposal-block emission + anchor resolution;
vitest suite (§6.8). Pure, vscode-free (INV-33).
- **SLICE-3 — Interactive controller + webview.** `ProposalController.listProposals`
+ `onDidChangeProposals`; wire `ProposalController` + `AttributionController`
into `TrackChangesPreviewController`; collapse mode to on/off; inbound
`accept`/`reject`/`setMode` handling + re-render; webview on/off switch + ✓/✗
click→postMessage + proposal/button CSS; status-bar indicator (PUC-6).
- **SLICE-4 — Tests & docs.** Host E2E (open / toggle / propose→accept→reject /
clean-editor / hidden-F6 / status-bar) + `docs/MANUAL-SMOKE-F10.md` + README
F10 section (and a note that F6/F9 user surfaces are superseded).
E2E are first-class plan tasks (handbook §9/§4); this app's required tier is host
E2E (the F2–F9 precedent).
### 7.3 Rollout / launch plan
Non-shippable (no marketplace publish). "Done" = `#29` acceptance: a clean
editor; the preview is the single review surface with an annotations on/off
toggle; on-state paints green human / blue LLM / struck deletions and renders
Claude's pending proposals with working ✓/✗ that land/discard via the F4 seam;
unit + host E2E green; live smoke performed once. The repo rename remains
deferred.
### 7.4 Risks & mitigations
| Risk | Mitigation |
| --- | --- |
| Proposals being preview-only hides pending work when no preview is open | Status-bar indicator (PUC-6); README documents "review happens in the preview"; auto-open is a cheap fallback if it proves insufficient |
| Overlaying author sentinels onto the diff's `<ins>`/`<del>` perturbs markdown-it inline parsing (F9's known edge) | Per-block `try/catch` → error chip (no hard failure); fences atomic; covered by the common-case tests; intra-emphasis hardening stays deferred |
| Proposal anchor can't be resolved at render time | Render as a trailing "unanchored proposal" block (never dropped); unit-tested |
| Removing F4's in-editor threads loses a familiar affordance | The ✓/✗ move to the preview (the single review surface by design); status-bar signals presence |
| Two reversed decisions (F9 INV-26; F6 any-file `#19`) confuse future readers | This spec records the supersession explicitly (§6.1, §6.7); README updated |
| Webview interactivity widens the attack surface | Nonce-gated inline script reads only `data-proposal-id` and posts intent; CSP unchanged; host validates the id against live proposals before acting (INV-34) |
---
## 8. Traceability matrix
| Requirement (#29) | Use case | Design | Slice |
| --- | --- | --- | --- |
| Editor carries no coauthoring decorations | PUC-1 | INV-32, §6.2 | SLICE-1 |
| Preview annotations on/off toggle (off = clean render) | PUC-2 | §6.2, §6.4 | SLICE-3 |
| One language: green human / blue LLM / struck deleted | PUC-3 | INV-33, §6.2 (renderReview) | SLICE-2 |
| ✓/✗ on Claude's changes only; ✓ keeps, ✗ reverts | PUC-4/5 | INV-34, §6.5 (F4 seam) | SLICE-2/3 |
| Accept/reject updates doc + preview consistently | PUC-4/5 | §6.5, INV-18 reuse | SLICE-3 |
| Deletions reconstructed from the F6 baseline | PUC-3 | F7 reuse, §6.2 | SLICE-2 |
| Deprecate F6 as a view; keep baseline data layer | — | §6.2, §6.7 | SLICE-1 |
| Markdown-only; no sidecar/contract/SCHEMA change | — | §1.7, INV-20 | all |
| Sealed webview, no network/LLM | — | INV-21, §6.6 | SLICE-3 |
| Unit + host E2E, no LLM in CI | — | §6.8 | SLICE-1..4 |
## 9. Open Questions & Decisions log
- **RESOLVED (session 0029, operator):** Claude's reviewable changes = **pending
F4 proposals surfaced in the preview** (propose-by-default kept; ✓ = F4 accept +
baseline advance, ✗ = F4 reject); editor decoration scope = **fully clean**
(strip F3 attribution **and** F4 proposal threads — proposals preview-only); F6
two-pane diff = **hidden** (`when:false`, code/baseline kept).
- **RESOLVED (this spec, autonomous — cheap to revisit):** proposal-while-no-preview
→ **status-bar indicator** (not forced auto-open); F9's dead `renderAuthorship`
/ segmented control → **removed** (the PUA-sentinel coloring salvaged into a
shared `colorByAuthor` helper); deletions → **neutral** strikethrough.
- **SUPERSEDED:** F9 INV-26 ("authorship never combined with the diff") — F10
combines them by design; F9's authorship mode + segmented control are removed.
F6's any-file review reach (`#19`) is dropped as a user goal (markdown-only).
- **OPEN → later:** the repo rename to `vscode-markdown-cowriting-plugin`
(deliberate, deferred); preview→source scroll-sync; intra-emphasis
sentinel-safety hardening; whether to eventually overlay *landed*-LLM authorship
(F9's old axis) in the on-state too (the "both axes" option, deferred); deleting
F6's two-pane view code in a later cleanup PR.
## 10. Glossary & References
- **Review preview** — the rendered markdown preview as the single review
surface: clean (off) or annotated (on). **Annotations on/off** — the per-panel
toggle replacing F9's two modes. **Combined render** — `renderReview`'s
single-pass overlay of changes-since-baseline (author-colored + struck) and
pending proposals. **Pending proposal** — an F4 propose-by-default edit, not yet
in the buffer, rendered blue with ✓/✗. **Baseline / epoch / advance** — as F6
(`coauthoring-diff-view.md`). **`spansFor`** — F3's author-span data layer
(`coauthoring-attribution.md`). **PUA sentinels / `colorByAuthor`** — F9's
author-coloring technique (`2026-06-11-authorship-preview-design.md`), salvaged
here.
- Feature `#29` (F10) · Epic `#1` · builds on F3 `#6`, F4 `#12`, F6 `#17`/`#19`,
F7 `#21`/`#22`, F9 `#27` · parent specs `coauthoring-inner-loop.md`,
`coauthoring-attribution.md`, `coauthoring-propose-accept.md`,
`coauthoring-diff-view.md`, `coauthoring-rendered-preview.md`,
`2026-06-11-authorship-preview-design.md` · capture session 0028 · lineage
`ben.stull/rfc-app#48`.
Reference in New Issue View Git Blame Copy Permalink