@startsimpli/ui 0.4.141 → 0.4.143

package/src/components/track-changes/extension.ts

@@ -0,0 +1,724 @@
+/**
+ * The CodeMirror 6 half of the track-changes editor (bd startsim-sjuai;
+ * design startsim-xyn25 section d). Headless: everything here is state, so it
+ * is tested on `EditorState` with no DOM.
+ *
+ * ── THE MODEL ───────────────────────────────────────────────────────────────
+ * The editor holds two things about the stored string:
+ *
+ *   BASE     the field's value at the version the host loaded. Every server
+ *            offset (blame, suggestions, comments) is an offset into BASE.
+ *   CHANGES  one ChangeSet, BASE → the document on screen, composed from every
+ *            local transaction.
+ *
+ * In EDITING mode CHANGES is the reviewer's unsaved typing; the host saves the
+ * document and echoes it back as the new BASE. In SUGGESTING mode CHANGES IS
+ * THE PROPOSAL: the document is the proposed copy, BASE is never written, and
+ * each change renders as an insert or a struck deletion. The proposal is the
+ * whole document text, which is exactly what the design posts
+ * (`{field, base_version, proposed}`).
+ *
+ * Every decoration is DERIVED from (BASE annotations, CHANGES, mode) on each
+ * update rather than mapped incrementally, so there is one source of truth for
+ * where a mark sits and nothing can drift. A span's text typed locally is cut
+ * out of it: a reviewer's unsaved words are never credited to whoever wrote
+ * the sentence around them.
+ *
+ * ── THE ROUND-TRIP RULE ─────────────────────────────────────────────────────
+ * By default CodeMirror splits lines on CRLF and CR and joins them with LF, so
+ * loading a CRLF value and saving it would rewrite every line ending, and
+ * blame would credit the saver with all of it: the exact hazard the design
+ * measured against rich editors. `lineSeparator: '\n'` makes LF the only
+ * separator, so a CR stays a character of its line and the string survives
+ * byte for byte.
+ */
+import {
+  Annotation,
+  ChangeSet,
+  EditorSelection,
+  EditorState,
+  Facet,
+  Prec,
+  StateEffect,
+  StateField,
+  Text,
+  Transaction,
+  type Extension,
+  type TransactionSpec,
+} from '@codemirror/state';
+import { Decoration, EditorView, WidgetType, keymap, type Command } from '@codemirror/view';
+
+import type { ActorKind } from '../ActorIdentity';
+import { describeBlame, describeLocal, describeSuggestion, describeThread } from './describe';
+import { anchorFor } from './normalize';
+import type { BlameSpan, CommentThread, SelectionAnchor, Suggestion } from './types';
+import { wordChanges } from './word-diff';
+
+export const LINE_SEPARATOR = '\n';
+
+export function textOf(value: string): Text {
+  return Text.of(value.split(LINE_SEPARATOR));
+}
+
+function changesOf(from: string, to: string): ChangeSet {
+  return ChangeSet.of(wordChanges(from, to), from.length, LINE_SEPARATOR);
+}
+
+/* -------------------------------------------------------------------------- */
+/*  State                                                                     */
+/* -------------------------------------------------------------------------- */
+
+export interface Tracking {
+  base: Text;
+  changes: ChangeSet;
+}
+
+/** Replace BASE and CHANGES outright (load, rebase, mode switch). */
+export const resetTracking = StateEffect.define<Tracking>();
+
+/** Marks a transaction the editor made itself, not the reviewer: it is never
+ *  reported to the host as an edit and never starts a proposal post. */
+export const internalChange = Annotation.define<boolean>();
+
+const trackingField = StateField.define<Tracking>({
+  create: (s) => ({ base: s.doc, changes: ChangeSet.empty(s.doc.length) }),
+  update(value, tr) {
+    for (const e of tr.effects) if (e.is(resetTracking)) return e.value;
+    if (!tr.docChanged) return value;
+    return { base: value.base, changes: value.changes.compose(tr.changes) };
+  },
+});
+
+export const setSuggesting = StateEffect.define<boolean>();
+
+const suggestingField = StateField.define<boolean>({
+  create: () => false,
+  update(value, tr) {
+    for (const e of tr.effects) if (e.is(setSuggesting)) return e.value;
+    return value;
+  },
+});
+
+/** Which kinds of mark are drawn. whwxd.3's show/hide toggle drives this. */
+export interface MarkVisibility {
+  blame?: boolean;
+  suggestions?: boolean;
+  comments?: boolean;
+}
+
+/** Server annotations in BASE coordinates, already normalized to UTF-16. */
+export interface AnnotationsInput {
+  blame: BlameSpan[];
+  suggestions: Suggestion[];
+  threads: CommentThread[];
+  /** Whose open suggestions are this reviewer's own. In suggesting mode they
+   *  are loaded into the proposal so that the next post (which supersedes the
+   *  author's own open set) carries them forward instead of dropping them. */
+  currentActorSub: string | null;
+  show?: MarkVisibility;
+}
+
+export const setAnnotations = StateEffect.define<AnnotationsInput>();
+
+/** BASE moved from one value to another; carry the annotations across it
+ *  until the host reloads them for the new version. */
+const mapBase = StateEffect.define<ChangeSet>();
+
+const EMPTY_ANNOTATIONS: AnnotationsInput = { blame: [], suggestions: [], threads: [], currentActorSub: null };
+
+function mapRange<T extends { from: number; to: number }>(r: T, c: ChangeSet): T | null {
+  const from = c.mapPos(r.from, 1);
+  const to = Math.max(from, c.mapPos(r.to, -1));
+  if (r.to > r.from && to <= from) return null;
+  return { ...r, from, to };
+}
+
+const annotationsField = StateField.define<AnnotationsInput>({
+  create: () => EMPTY_ANNOTATIONS,
+  update(value, tr) {
+    let next = value;
+    for (const e of tr.effects) {
+      if (e.is(setAnnotations)) next = e.value;
+      else if (e.is(mapBase)) {
+        const c = e.value;
+        next = {
+          ...next,
+          blame: next.blame.flatMap((s) => mapRange(s, c) ?? []),
+          suggestions: next.suggestions.flatMap((s) =>
+            s.anchorState === 'orphaned' ? [s] : (mapRange(s, c) ?? []),
+          ),
+          threads: next.threads.map((t) => {
+            if (t.from == null || t.to == null) return t;
+            const m = mapRange({ from: t.from, to: t.to }, c);
+            return m ? { ...t, ...m } : { ...t, from: null, to: null, anchorState: 'orphaned' as const };
+          }),
+        };
+      }
+    }
+    return next;
+  },
+});
+
+/** The mark the reviewer last moved to (by keyboard or by the rail). */
+export const setExplicitActive = StateEffect.define<string | null>();
+
+const explicitActiveField = StateField.define<string | null>({
+  create: () => null,
+  update(value, tr) {
+    for (const e of tr.effects) if (e.is(setExplicitActive)) return e.value;
+    return value;
+  },
+});
+
+/* -------------------------------------------------------------------------- */
+/*  Marks                                                                     */
+/* -------------------------------------------------------------------------- */
+
+export type MarkKind = 'blame' | 'suggestion' | 'comment' | 'local';
+
+/** One thing drawn over the text, in DOCUMENT coordinates. `from === to` for
+ *  a pure insert suggestion or a local deletion (there is no text to cover). */
+export interface TrackMark {
+  id: string;
+  kind: MarkKind;
+  from: number;
+  to: number;
+  /** The accessible sentence, also the tooltip. */
+  description: string;
+  /** `self` for the reviewer's own local proposal. */
+  actorKind: ActorKind | 'self';
+  /** Stable per author, for the tint. */
+  authorKey: string;
+  /** Suggestion / local: text that would be inserted. */
+  inserted?: string;
+  /** Local deletion: the base text no longer in the document. */
+  deleted?: string;
+  source: BlameSpan | Suggestion | CommentThread | null;
+}
+
+const KIND_ORDER: Record<MarkKind, number> = { suggestion: 0, local: 0, comment: 1, blame: 2 };
+
+function byPosition(a: TrackMark, b: TrackMark) {
+  return a.from - b.from || KIND_ORDER[a.kind] - KIND_ORDER[b.kind] || a.to - b.to;
+}
+
+/** Cut `[from, to)` around locally inserted ranges. */
+function subtract(from: number, to: number, holes: Array<[number, number]>): Array<[number, number]> {
+  const out: Array<[number, number]> = [];
+  let start = from;
+  for (const [hf, ht] of holes) {
+    if (ht <= start || hf >= to) continue;
+    if (hf > start) out.push([start, hf]);
+    start = Math.max(start, ht);
+  }
+  if (start < to) out.push([start, to]);
+  return out;
+}
+
+export function computeMarks(state: EditorState): TrackMark[] {
+  const { base, changes } = state.field(trackingField);
+  const suggesting = state.field(suggestingField);
+  const ann = state.field(annotationsField);
+  const show = { blame: true, suggestions: true, comments: true, ...ann.show };
+  const marks: TrackMark[] = [];
+
+  const inserted: Array<[number, number]> = [];
+  changes.iterChanges((fromA, toA, fromB, toB, text) => {
+    if (toB > fromB) inserted.push([fromB, toB]);
+    if (!suggesting) return;
+    const deleted = base.sliceString(fromA, toA, LINE_SEPARATOR);
+    const ins = text.sliceString(0, text.length, LINE_SEPARATOR);
+    marks.push({
+      id: `local:${fromB}`,
+      kind: 'local',
+      from: fromB,
+      to: toB,
+      description: describeLocal(deleted, ins),
+      actorKind: 'self',
+      authorKey: 'self',
+      inserted: ins,
+      deleted,
+      source: null,
+    });
+  });
+
+  if (show.blame) {
+    for (const s of ann.blame) {
+      const m = mapRange(s, changes);
+      if (!m) continue;
+      const pieces = subtract(m.from, m.to, inserted);
+      pieces.forEach(([from, to], i) => {
+        marks.push({
+          id: pieces.length > 1 ? `${s.id}#${i}` : s.id,
+          kind: 'blame',
+          from,
+          to,
+          description: describeBlame(s),
+          actorKind: s.author ? s.author.kind : 'unknown',
+          authorKey: s.author ? s.author.sub || s.author.label : '',
+          source: s,
+        });
+      });
+    }
+  }
+
+  if (show.suggestions) {
+    for (const s of ann.suggestions) {
+      if (s.status !== 'open' || s.anchorState === 'orphaned') continue;
+      // Suggesting mode: the reviewer's own open suggestions ARE the local
+      // proposal (see enterSuggesting); drawing them twice would double them.
+      if (suggesting && ann.currentActorSub && s.author.sub === ann.currentActorSub) continue;
+      const m = mapRange(s, changes);
+      if (!m) continue;
+      marks.push({
+        id: s.id,
+        kind: 'suggestion',
+        from: m.from,
+        to: m.to,
+        description: describeSuggestion(s),
+        actorKind: s.author.kind,
+        authorKey: s.author.sub || s.author.label,
+        inserted: s.replacement,
+        source: s,
+      });
+    }
+  }
+
+  if (show.comments) {
+    for (const t of ann.threads) {
+      if (t.resolved || t.anchorState === 'orphaned' || t.from == null || t.to == null) continue;
+      const m = mapRange({ from: t.from, to: t.to }, changes);
+      if (!m) continue;
+      const root = t.comments[0]?.author;
+      marks.push({
+        id: t.id,
+        kind: 'comment',
+        from: m.from,
+        to: m.to,
+        description: describeThread(t),
+        actorKind: root?.kind ?? 'unknown',
+        authorKey: root ? root.sub || root.label : '',
+        source: t,
+      });
+    }
+  }
+
+  return marks.sort(byPosition);
+}
+
+const marksFacet = Facet.define<TrackMark[], TrackMark[]>({ combine: (v) => v[0] ?? [] });
+
+function covers(m: TrackMark, head: number, docLength: number): boolean {
+  if (m.kind === 'blame') return m.from <= head && (head < m.to || (head === m.to && head === docLength));
+  return m.from <= head && head <= m.to;
+}
+
+function computeActive(state: EditorState): TrackMark | null {
+  const marks = state.facet(marksFacet);
+  const head = state.selection.main.head;
+  const explicit = state.field(explicitActiveField);
+  if (explicit) {
+    const m = marks.find((x) => x.id === explicit);
+    if (m && covers(m, head, state.doc.length)) return m;
+  }
+  let best: TrackMark | null = null;
+  for (const m of marks) {
+    if (!covers(m, head, state.doc.length)) continue;
+    if (
+      !best ||
+      KIND_ORDER[m.kind] < KIND_ORDER[best.kind] ||
+      (KIND_ORDER[m.kind] === KIND_ORDER[best.kind] && m.to - m.from < best.to - best.from)
+    ) {
+      best = m;
+    }
+  }
+  return best;
+}
+
+const activeFacet = Facet.define<TrackMark | null, TrackMark | null>({ combine: (v) => v[0] ?? null });
+
+/* -------------------------------------------------------------------------- */
+/*  Read access                                                               */
+/* -------------------------------------------------------------------------- */
+
+export const marksOf = (s: EditorState) => s.facet(marksFacet);
+export const activeMarkOf = (s: EditorState) => s.facet(activeFacet);
+export const trackingOf = (s: EditorState) => s.field(trackingField);
+export const isSuggesting = (s: EditorState) => s.field(suggestingField);
+export const annotationsOf = (s: EditorState) => s.field(annotationsField);
+/** The suggesting-mode proposal: the whole document text. */
+export const proposedText = (s: EditorState) => s.doc.toString();
+
+/* -------------------------------------------------------------------------- */
+/*  Transitions (pure: each returns a spec for the caller to dispatch)        */
+/* -------------------------------------------------------------------------- */
+
+const INTERNAL = [internalChange.of(true), Transaction.addToHistory.of(false)];
+
+/**
+ * The stored value is now `value`. Three cases:
+ *
+ * - it equals BASE: nothing to do (returns null);
+ * - `ownEcho` (editing mode): the host saved text this editor produced, so it
+ *   becomes BASE and whatever was typed since stays as unsaved CHANGES. The
+ *   document is NOT touched, which is what stops a lagging echo from
+ *   re-inserting text the reviewer already has;
+ * - otherwise it is EXTERNAL (an accept, another reviewer, a restore): the
+ *   difference is applied as a change, rebased over local CHANGES, so local
+ *   typing or a proposal survives and every mark maps instead of collapsing.
+ */
+export function rebaseOnto(
+  state: EditorState,
+  value: string,
+  opts: { ownEcho?: boolean } = {},
+): TransactionSpec | null {
+  const { base, changes } = state.field(trackingField);
+  const baseStr = base.sliceString(0, base.length, LINE_SEPARATOR);
+  if (value === baseStr) return null;
+  const moved = changesOf(baseStr, value);
+  const doc = state.doc.toString();
+  const suggesting = state.field(suggestingField);
+
+  if (!suggesting && (opts.ownEcho || value === doc)) {
+    return {
+      effects: [resetTracking.of({ base: textOf(value), changes: changesOf(value, doc) }), mapBase.of(moved)],
+      annotations: INTERNAL,
+    };
+  }
+
+  const docChange = moved.map(changes);
+  const local = changes.map(moved, true);
+  return {
+    changes: docChange,
+    effects: [resetTracking.of({ base: textOf(value), changes: local }), mapBase.of(moved)],
+    annotations: INTERNAL,
+  };
+}
+
+/**
+ * Enter suggesting mode. The document must equal BASE (no unsaved typing),
+ * which the component guarantees by disabling the switch until it does.
+ * The reviewer's own open suggestions are loaded into the proposal.
+ */
+/**
+ * The reviewer's own open suggestions, split three ways:
+ * - `placed`: carried into the proposal;
+ * - `orphaned`: cannot be placed, but the server KEEPS them open on the next
+ *   full-text post (`kept_orphaned`, start-simpli-api #508), so nothing is lost;
+ * - `overlapping`: live, but overlapping an earlier one of the reviewer's own,
+ *   so the proposal cannot carry both and the next post SUPERSEDES them. The
+ *   component warns about these rather than dropping them silently.
+ */
+export function ownSuggestions(state: EditorState): {
+  placed: Suggestion[];
+  orphaned: Suggestion[];
+  overlapping: Suggestion[];
+} {
+  const ann = state.field(annotationsField);
+  const placed: Suggestion[] = [];
+  const orphaned: Suggestion[] = [];
+  const overlapping: Suggestion[] = [];
+  if (!ann.currentActorSub) return { placed, orphaned, overlapping };
+  const base = state.field(trackingField).base;
+  const own = ann.suggestions
+    .filter((s) => s.status === 'open' && s.author.sub === ann.currentActorSub)
+    .sort((a, b) => a.from - b.from);
+  let end = -1;
+  for (const s of own) {
+    if (s.anchorState === 'orphaned' || s.to > base.length) orphaned.push(s);
+    else if (s.from < end) overlapping.push(s);
+    else {
+      placed.push(s);
+      end = s.to;
+    }
+  }
+  return { placed, orphaned, overlapping };
+}
+
+export function enterSuggesting(state: EditorState): TransactionSpec[] {
+  const { placed: own } = ownSuggestions(state);
+  const specs: TransactionSpec[] = [
+    {
+      effects: [setSuggesting.of(true), resetTracking.of({ base: state.doc, changes: ChangeSet.empty(state.doc.length) })],
+      annotations: INTERNAL,
+    },
+  ];
+  const picked = own.map((s) => ({ from: s.from, to: s.to, insert: s.replacement }));
+  if (picked.length) specs.push({ changes: picked, annotations: INTERNAL });
+  return specs;
+}
+
+/** Leave suggesting mode: the document returns to BASE, untouched. */
+export function leaveSuggesting(state: EditorState): TransactionSpec {
+  const { base, changes } = state.field(trackingField);
+  return {
+    changes: changes.invert(base),
+    effects: [setSuggesting.of(false), resetTracking.of({ base, changes: ChangeSet.empty(base.length) })],
+    annotations: INTERNAL,
+  };
+}
+
+/** Which marks the change navigation visits. Authorship spans have their own
+ *  keys, because stepping through every span of a blog to reach the next
+ *  suggestion is not navigation. */
+export const isChangeOrComment = (m: TrackMark) => m.kind !== 'blame';
+export const isAuthorship = (m: TrackMark) => m.kind === 'blame';
+
+function selectMark(m: TrackMark): TransactionSpec {
+  return {
+    selection: m.to > m.from ? EditorSelection.range(m.from, m.to) : EditorSelection.cursor(m.from),
+    effects: [setExplicitActive.of(m.id), EditorView.scrollIntoView(m.from, { y: 'center' })],
+    userEvent: 'select.track-changes',
+  };
+}
+
+/** Move to the next (`dir` 1) or previous (-1) mark, wrapping. */
+export function moveToMark(
+  state: EditorState,
+  dir: 1 | -1,
+  filter: (m: TrackMark) => boolean = isChangeOrComment,
+): TransactionSpec | null {
+  const list = state.facet(marksFacet).filter(filter);
+  if (!list.length) return null;
+  const active = state.facet(activeFacet);
+  const at = active ? list.findIndex((m) => m.id === active.id) : -1;
+  let i: number;
+  if (at >= 0) i = (at + dir + list.length) % list.length;
+  else {
+    const head = state.selection.main.head;
+    if (dir > 0) {
+      i = list.findIndex((m) => m.from >= head);
+      if (i < 0) i = 0;
+    } else {
+      i = -1;
+      for (let k = list.length - 1; k >= 0; k--) {
+        if (list[k].from < head) {
+          i = k;
+          break;
+        }
+      }
+      if (i < 0) i = list.length - 1;
+    }
+  }
+  return selectMark(list[i]);
+}
+
+/** Select a mark by id (the rail's "show me this one"). */
+export function focusMark(state: EditorState, id: string): TransactionSpec | null {
+  const m = state.facet(marksFacet).find((x) => x.id === id);
+  return m ? selectMark(m) : null;
+}
+
+const run =
+  (dir: 1 | -1, filter: (m: TrackMark) => boolean): Command =>
+  (view) => {
+    const spec = moveToMark(view.state, dir, filter);
+    if (!spec) return false;
+    view.dispatch(spec);
+    return true;
+  };
+
+export interface TrackKeys {
+  nextChange?: string;
+  prevChange?: string;
+  nextAuthor?: string;
+  prevAuthor?: string;
+}
+
+/** F8 is "next problem" in most editors and is free in CodeMirror's default
+ *  keymap (Alt-ArrowUp/Down are move-line, so they are not used). */
+export const DEFAULT_KEYS: Required<TrackKeys> = {
+  nextChange: 'F8',
+  prevChange: 'Shift-F8',
+  nextAuthor: 'Alt-F8',
+  prevAuthor: 'Shift-Alt-F8',
+};
+
+/* -------------------------------------------------------------------------- */
+/*  Rendering                                                                 */
+/* -------------------------------------------------------------------------- */
+
+const HUES = 8;
+
+function hueOf(key: string): number {
+  let h = 0;
+  for (let i = 0; i < key.length; i++) h = (h * 31 + key.charCodeAt(i)) >>> 0;
+  return h % HUES;
+}
+
+function attrs(m: TrackMark): Record<string, string> {
+  return {
+    'data-tc-id': m.id,
+    'data-tc-kind': m.kind,
+    'data-actor-kind': m.actorKind,
+    title: m.description,
+  };
+}
+
+class TextWidget extends WidgetType {
+  constructor(
+    readonly tag: 'ins' | 'del',
+    readonly text: string,
+    readonly cls: string,
+    readonly m: TrackMark,
+  ) {
+    super();
+  }
+  eq(other: TextWidget) {
+    return other.tag === this.tag && other.text === this.text && other.cls === this.cls && other.m.id === this.m.id;
+  }
+  toDOM() {
+    const el = document.createElement(this.tag);
+    el.className = this.cls;
+    el.textContent = this.text;
+    for (const [k, v] of Object.entries(attrs(this.m))) el.setAttribute(k, v);
+    return el;
+  }
+  ignoreEvent() {
+    return false;
+  }
+}
+
+function decorationsFor(marks: TrackMark[], active: TrackMark | null, explicit: string | null) {
+  const out = [];
+  for (const m of marks) {
+    // An authorship span covers whole paragraphs and the cursor is always in
+    // one, so it is outlined only when navigated to, never merely by typing.
+    const on = active?.id === m.id && (m.kind !== 'blame' || explicit === m.id) ? ' cm-tc-active' : '';
+    const a = attrs(m);
+    if (m.kind === 'blame') {
+      const tint = m.actorKind === 'unknown' ? 'cm-tc-unknown' : `cm-tc-a${hueOf(m.authorKey)}`;
+      const machine = m.actorKind === 'machine' ? ' cm-tc-machine' : '';
+      out.push(Decoration.mark({ class: `cm-tc-blame ${tint}${machine}${on}`, attributes: a }).range(m.from, m.to));
+    } else if (m.kind === 'comment') {
+      out.push(Decoration.mark({ tagName: 'mark', class: `cm-tc-comment${on}`, attributes: a }).range(m.from, m.to));
+    } else if (m.kind === 'suggestion') {
+      if (m.to > m.from) {
+        out.push(Decoration.mark({ tagName: 'del', class: `cm-tc-sugg-del${on}`, attributes: a }).range(m.from, m.to));
+      }
+      if (m.inserted) {
+        out.push(
+          Decoration.widget({ widget: new TextWidget('ins', m.inserted, `cm-tc-sugg-ins${on}`, m), side: 1 }).range(m.to),
+        );
+      }
+    } else {
+      if (m.deleted) {
+        out.push(
+          Decoration.widget({ widget: new TextWidget('del', m.deleted, `cm-tc-local-del${on}`, m), side: -1 }).range(m.from),
+        );
+      }
+      if (m.to > m.from) {
+        out.push(Decoration.mark({ tagName: 'ins', class: `cm-tc-local-ins${on}`, attributes: a }).range(m.from, m.to));
+      }
+    }
+  }
+  return Decoration.set(out, true);
+}
+
+/**
+ * Colours come from the theme contract with fallbacks, NOT Tailwind classes:
+ * decorations are created at runtime, so a standalone app's Tailwind purge
+ * never sees these class names. Author tints are eight hues, overridable per
+ * tenant with `--tc-author-0` … `--tc-author-7` (HSL channels, like the
+ * contract). Deletions use the destructive token at low strength: it is a
+ * proposal, not an error, so it must not read as an incident. A machine span
+ * is dashed (shape, not colour, carries the meaning), and an unknown span is
+ * a quiet dotted underline: calm, because it is the common case today.
+ */
+// No greens, reds, oranges or yellows: green and red mean "inserted" and
+// "deleted" here and yellow means "commented", so an author tint near any of
+// them would say something false (an orange author read as a deletion in the
+// browser harness).
+const AUTHOR_DEFAULTS = [
+  '217 91% 60%',
+  '271 81% 56%',
+  '330 81% 60%',
+  '189 94% 43%',
+  '245 58% 51%',
+  '292 84% 61%',
+  '200 60% 40%',
+  '230 25% 45%',
+];
+
+const theme = EditorView.baseTheme({
+  '.cm-tc-blame': { textDecorationLine: 'underline', textDecorationThickness: '2px', textUnderlineOffset: '3px' },
+  ...Object.fromEntries(
+    AUTHOR_DEFAULTS.map((hsl, i) => [
+      `.cm-tc-a${i}`,
+      {
+        textDecorationColor: `hsl(var(--tc-author-${i}, ${hsl}))`,
+        backgroundColor: `hsl(var(--tc-author-${i}, ${hsl}) / 0.08)`,
+      },
+    ]),
+  ),
+  '.cm-tc-machine': { textDecorationStyle: 'dashed' },
+  '.cm-tc-unknown': {
+    textDecorationStyle: 'dotted',
+    textDecorationThickness: '1px',
+    textDecorationColor: 'hsl(var(--muted-foreground, 215 16% 47%) / 0.6)',
+  },
+  '.cm-tc-comment': {
+    backgroundColor: 'hsl(var(--tc-comment, 48 96% 53%) / 0.25)',
+    color: 'inherit',
+    borderBottom: '2px solid hsl(var(--tc-comment, 48 96% 53%) / 0.8)',
+  },
+  '.cm-tc-sugg-del, .cm-tc-local-del': {
+    textDecorationLine: 'line-through',
+    color: 'hsl(var(--destructive, 0 72% 51%))',
+    backgroundColor: 'hsl(var(--destructive, 0 72% 51%) / 0.08)',
+  },
+  '.cm-tc-sugg-ins, .cm-tc-local-ins': {
+    textDecorationLine: 'underline',
+    textDecorationColor: 'hsl(var(--success, 142 71% 36%))',
+    backgroundColor: 'hsl(var(--success, 142 71% 36%) / 0.12)',
+  },
+  '.cm-tc-active': { outline: '2px solid hsl(var(--ring, 217 91% 60%))', outlineOffset: '1px', borderRadius: '2px' },
+});
+
+export interface TrackChangesConfig {
+  keys?: TrackKeys;
+}
+
+/** Everything the track-changes editor adds to a CodeMirror state. */
+export function trackChanges(config: TrackChangesConfig = {}): Extension {
+  const keys = { ...DEFAULT_KEYS, ...config.keys };
+  return [
+    EditorState.lineSeparator.of(LINE_SEPARATOR),
+    trackingField,
+    suggestingField,
+    annotationsField,
+    explicitActiveField,
+    marksFacet.compute([trackingField, suggestingField, annotationsField], computeMarks),
+    activeFacet.compute(['selection', marksFacet, explicitActiveField], computeActive),
+    EditorView.decorations.compute([marksFacet, activeFacet, explicitActiveField], (s) =>
+      decorationsFor(s.facet(marksFacet), s.facet(activeFacet), s.field(explicitActiveField)),
+    ),
+    Prec.high(
+      keymap.of([
+        { key: keys.nextChange, run: run(1, isChangeOrComment) },
+        { key: keys.prevChange, run: run(-1, isChangeOrComment) },
+        { key: keys.nextAuthor, run: run(1, isAuthorship) },
+        { key: keys.prevAuthor, run: run(-1, isAuthorship) },
+      ]),
+    ),
+    theme,
+  ];
+}
+
+/**
+ * The selection as an anchor in BASE (stored-string) coordinates, which is
+ * what a comment is anchored to on the server. Unsaved typing or a local
+ * proposal before the selection does not shift it. `null` when nothing is
+ * selected or the selection is only locally typed text (it has no stored
+ * characters to anchor to).
+ */
+export function selectionAnchorOf(state: EditorState): SelectionAnchor | null {
+  const sel = state.selection.main;
+  if (sel.empty) return null;
+  const { base, changes } = state.field(trackingField);
+  const inv = changes.invertedDesc;
+  const from = inv.mapPos(sel.from, 1);
+  const to = inv.mapPos(sel.to, -1);
+  if (to <= from) return null;
+  return anchorFor(base.sliceString(0, base.length, LINE_SEPARATOR), from, to);
+}