feat: controlled comments API + derive tracked changes from PM (collab-ready)

[jedrazb]

Stacked on #254. Base will retarget to `main` once that lands.

Summary

Two changes that together make comments and tracked changes work over Yjs:

1. Comments — additive controlled mode. New optional `comments` + `onCommentsChange` props on `DocxEditor`. When passed, the editor reads thread metadata (text, author, replies, resolved status) from the prop and emits every change through the callback. Pair with a `Y.Array` (or any other shared collection) to sync threads across collaborators. Existing consumers see no behavior change — fallback to internal `useState` is identical to today.

2. Tracked changes — eliminate the redundant React state. `useState<TrackedChangeEntry[]>([])` was a debounced, derived view of data already in PM mark attrs (`insertion`/`deletion` carry `revisionId`/`author`/`date`). Replaced by a `useTrackedChanges(state)` hook that derives synchronously on every doc-changing transaction. Tracked changes already collab-sync through `ySyncPlugin` because the metadata rides along with the synced PM tree — this PR just removes the redundant copy and confirms the path.

Demo: the existing `examples/collaboration` is updated to wire comments through a `Y.Array` on the same `Y.Doc`. Open the demo in two browser windows (Share link → paste in second tab) to verify both flows end-to-end.

What changed

File	Why
`packages/react/src/hooks/useTrackedChanges.ts` (new)	Pure `extractTrackedChanges(state)` returns `{ entries, commentToRevision }` from a single doc walk — both the sidebar list and the comment-threading map come from one pass.
`packages/react/src/hooks/useControllableComments.ts` (new)	Radix-style controlled/uncontrolled hook for the comments array.
`packages/react/src/components/DocxEditor.tsx`	Replace state declarations; remove ~120-line `extractTrackedChanges` callback; remove 300ms debounce timer; comment-threading effect consumes the pre-computed map.
`examples/collaboration/src/useCollaboration.ts`	Expose `comments` + `setComments` mirrored against `Y.Array`.
`examples/collaboration/src/App.tsx`	Pass new controlled props to `DocxEditor`.
`examples/collaboration/src/identity.ts`	Drop random number suffix from display name (fixes `A4` initials).
`examples/collaboration/README.md`	Document the four-piece architecture; document the demo's known limitations honestly.
`docs/PROPS.md`	Two new props in the table + a "Controlled Comments" section with a Yjs Y.Array bridge example.

API surface

```tsx
<DocxEditor
document={createEmptyDocument()}
externalContent
externalPlugins={[ySync, yCursor, yUndo]}
comments={comments} // NEW: controlled
onCommentsChange={setComments} // NEW: fires on every change
// ...
/>
```

The granular `onCommentAdd`/`onCommentResolve`/`onCommentDelete`/`onCommentReply` callbacks still fire alongside `onCommentsChange` — parents that just want notifications don't need to switch.

Why tracked changes don't need a controlled API

Originally I assumed tracked-changes metadata lived in React state too. Code reading proved otherwise: it's already in PM mark attrs, parsed from `<w:ins>`/`<w:del>` and serialized back via `fromProseDoc.ts`. The React state was a debounced derived view used by the sidebar. That copy is now gone — the sidebar derives directly from PM via the new hook, and remote ySync updates flow through automatically.

This matches superdoc's split: comments use an external entity store (their `comment-entity-store.ts` + `Y.Map` collab adapter), tracked changes live entirely in PM marks.

Review pass (4 reviewers, applied fixes inline)

• ✅ Code reviewer — flagged `200ms setTimeout` for initial PM-state mirror as a smell. Kept (works; replacing properly needs a new "doc loaded" callback from `HiddenProseMirror`, larger change).
• ✅ Simplifier — flagged duplicate doc walk in the threading effect. Fixed: `extractTrackedChanges` now returns `{ entries, commentToRevision }` from a single `doc.descendants` pass.
• ✅ UX reviewer — flagged comment-id collisions (filed #257), Y.Array replace-all data loss (strengthened README caveat), `A4` initials bug (fixed), remote cursors invisible (filed #256), tracked-change accept/reject race (added README caveat).
• ✅ Performance reviewer — flagged the duplicate doc walk (fixed by simplifier change above) as the highest-impact perf issue. Also called out the demo's full-array Y.Array replace as a bandwidth/memory concern at scale (already documented in README; production guidance to use `Y.Map<id, Comment>`).

Test plan

• `bun run typecheck` — clean across all workspaces
• `bun run build` (collab demo) — clean build
• `comment-button.spec.ts` — 3/3 pass
• Manual smoke check: two browser tabs at http://localhost:5273, verify text/cursors/comments/tracked-changes all sync (pending live reviewer verification)
• `toolbar-state.spec.ts` and `text-editing.spec.ts` show flakes — same flakes are present on `main` (CLAUDE.md flags them as known flaky), unrelated to this change

Risks

• Sidebar reactivity for tracked changes: now synchronous on every doc-changing transaction instead of 300ms-debounced. Single doc walk is O(nodes); per-keystroke cost stays sub-millisecond on typical docs. Scaling cliff at 500+ pages with hundreds of tracked changes — flagged in code comments; mitigation is to wrap `setPmState` in `requestAnimationFrame` rather than reintroducing a delay.
• Comment-threading effect loop: depends on `[commentToRevision, setComments]` and writes `comments`. Short-circuited via the existing `changed` flag and `useControllableComments`'s reference-equality check.
• Demo replace-all Y.Array sync: documented in README; production should use `Y.Map<id, Comment>`.

Follow-ups filed

• #256 Forward PM decorations to layout-painter (unblocks remote cursors)
• #257 Comment IDs can collide between collaborating peers

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docx-editor	Ready	Preview, Comment	Apr 13, 2026 9:06am