docs: author-colored track-changes design + implementation plan

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 13:32:34 -07:00
parent 126d71fa06
commit 94b1a9b0c2
3 changed files with 980 additions and 0 deletions
@@ -0,0 +1,150 @@
+# Author-colored track changes (both panes) — design
+
+**Date:** 2026-06-26
+**Status:** Design approved; ready for implementation planning
+**Mockups:** `.superpowers/brainstorm/15095-1782504559/content/panes-states-v2.html`
+
+## Problem
+
+Today the plugin uses two unrelated color systems:
+
+- **The diff** (proposed/changed text in both panes) uses *semantic* colors —
+  green = added, red = removed — regardless of who made the change.
+- **Authorship** (F3) uses *author* colors (blue = Claude, green = human) but
+  only as a flat tint in the **preview** pane, and only on committed text, not
+  as a diff.
+
+So you cannot look at a change and immediately see **who** made it. The product
+goal is an experience like two humans collaborating in a track-changes document
+(Google Docs suggesting mode / Word track changes): every edit is a diff, and a
+glance tells you both *what changed* and *who changed it*.
+
+## The model
+
+Every change is rendered as a diff — insertions **and** deletions — where:
+
+- **Style encodes the operation:** underline = inserted, strikethrough = removed.
+- **Color encodes the author.**
+
+|        | Added            | Removed                |
+| ------ | ---------------- | ---------------------- |
+| Human  | green underline  | red strikethrough      |
+| Claude | blue underline   | purple strikethrough   |
+
+Human keeps today's exact green/red. Claude gets blue/purple (blue is already
+Claude's established attribution hue; purple reads as a removal without colliding
+with human red).
+
+**Color means "changed since the pinned baseline,"** not "authored forever." Once
+a change is accepted and the baseline re-pins, its marks clear and the text
+returns to plain. This preserves the existing pin→clean behavior (#48): a pinned,
+zero-diff document renders with no annotation.
+
+### Concrete colors
+
+Carry the existing human values; add Claude's pair. (Final hex values are a
+polish detail for implementation; these are the design intent.)
+
+- Human added: `#3fb950` underline, bg `rgba(63,185,80,0.14)`
+- Human removed: `#f85149` strikethrough, bg `rgba(248,81,73,0.11)`
+- Claude added: `#58a6ff` underline, bg `rgba(88,166,255,0.15)`
+- Claude removed: `#bc8cff` strikethrough, bg `rgba(188,140,255,0.13)`
+
+Each change run is a subtle author-hued background tint **plus** a solid 2px
+underline (insert) or strikethrough (delete) in the full author color — the solid
+line carries the signal even where backgrounds are faint.
+
+## Both panes (decision A)
+
+Author-colored track changes appear in **both** the main editor pane and the
+rendered preview pane.
+
+- **Main editor pane:** gains full inline track-changes for *all*
+  changes-since-baseline — human and Claude, committed and pending — not just
+  pending proposals. **This reverses INV-32** ("editor fully clean") from F10:
+  the editor was deliberately kept clean, with all who-wrote-what coloring living
+  only in the preview. We are intentionally undoing that.
+- **Rendered preview pane:** shows the same model (it already renders a diff +
+  authorship; this unifies them so ins/del runs are author-colored rather than
+  semantically colored).
+
+Pending Claude proposals keep their Accept/Reject affordance in both panes —
+CodeLens (`✓ Accept ▾ / ✗ Reject ▾`) in the editor, buttons in the preview.
+
+## States (must all render correctly)
+
+Base states: human-added, human-removed, Claude-added, Claude-removed.
+
+**Overlap** — a single span both authors touched — stacks both marks:
+
+- Human added it, Claude is removing it → green underline **+** purple strikethrough.
+- Claude added it, human is removing it → blue underline **+** red strikethrough.
+
+Block-level: a whole added block carries the author's add treatment (left border +
+tint); a whole removed block carries the author's remove treatment (struck + tint).
+
+Resting state: unchanged-since-baseline text renders plain. After Accept + re-pin,
+changed text returns to plain.
+
+## Architecture
+
+The core change is **fusing the currently-separate semantic-diff and authorship
+systems** so that every inserted/deleted run carries its author, and rendering
+colors by that author rather than by add/remove semantics.
+
+Components affected (per the current code map):
+
+- **`src/trackChangesModel.ts`** — `renderReview` / `renderOp` /
+  `wordMergedMarkdown` / `colorByAuthor`. Today `<ins>`/`<del>` are emitted with
+  semantic green/red classes independent of author. Change: ins/del runs become
+  author-aware and emit author-colored classes; overlap emits a stacked-mark
+  class.
+- **`src/editorProposalController.ts`** — today only pending proposals decorate,
+  using semantic `ThemeColor`s. Change: per-author/op `TextEditorDecorationType`s
+  (human-add/human-del/claude-add/claude-del + overlap), and decorate **all**
+  changes-since-baseline, not just proposals (the INV-32 reversal).
+- **`src/attributionController.ts`** — supplies the per-character/per-run author
+  spans the diff needs to attribute insertions (and, see below, deletions).
+- **`media/preview.css`** — recolor: keep human green/red, add Claude
+  blue/purple, encode underline=insert / strikethrough=delete, add overlap
+  (stacked-mark) classes for both directions.
+
+## Open technical question (for the plan / tech-design stage)
+
+**Deletion authorship.** Removed text is no longer in the buffer, so the renderer
+must know *who deleted it* to color the strikethrough.
+
+- For **pending proposals**, the deleter is trivially Claude (the proposal owns
+  the deletion).
+- For **committed deletions** (baseline → current), we must confirm the F3 seam /
+  attribution model carries the **deleting actor**. F3 attributes
+  *current-buffer* characters; deleted characters are gone. If the seam's edit
+  events carry the actor that performed each removal, we attribute from that; if
+  not, deriving deletion authorship is the main thing the implementation plan has
+  to solve. Until resolved, a safe fallback is to color committed deletions by the
+  **turn actor** that produced the diff hunk.
+
+This is the one genuinely open architectural item; everything else is
+presentation.
+
+## Out of scope (YAGNI)
+
+- More than two authors / arbitrary per-collaborator palettes. Two roles
+  (human, Claude) only.
+- User-configurable colors / theme settings. Ship one good scheme.
+- Changing accept/reject *mechanics* — this is purely how changes are
+  **visualized**; the F4 proposal lifecycle is unchanged.
+- Per-word authorship inside an accepted, re-pinned (plain) document.
+
+## Testing
+
+- **Unit (pure render):** `trackChangesModel` renders each state to the expected
+  author-colored markup — the four base states, both overlap directions, block
+  add/remove, and resting/plain. Reuse the existing pure-render test pattern.
+- **Editor decorations:** the decoration plan produces the right per-author/op
+  ranges, including the INV-32-reversal (committed changes now decorate) and
+  stacked overlap ranges.
+- **Host E2E:** open a co-edited doc, assert both panes show author-colored
+  marks; accept a proposal + re-pin → marks clear (pin→clean preserved).
+- Update/replace any test that asserts the **old** semantic green=add/red=remove
+  classes or the INV-32 clean-editor behavior.