feat(review): add provider-neutral comments, suggestions, and revision review surface

[seonghobae]

Buyer-visible product gap

Protected Inkspan main@3b38ead2d00f44eb578d0689087b9293b3dabe1e promises an author-and-reviewer product and already exposes revision-scoped ProseMirror selection evidence plus a W3C TextPositionSelector projection. However, the protected public package does not expose a provider-neutral review surface for comment threads, suggestion mode, accept/reject operations, or revision comparison.

This leaves embedding buyers to rebuild the hardest editor-review interactions themselves even though Inkspan already owns the deterministic editor transaction and revision-evidence boundaries needed to implement them safely.

This is deliberately not a request for Inkspan to become an annotation database, identity provider, notification service, tenant store, or collaboration authorization server. Those remain host-owned as defined by docs/PRD.md, docs/TRD.md, and ARCHITECTURE.md.

Product evidence

• docs/PRD.md lists authors and reviewers as users and makes review/annotation operations revision-scoped, while assigning durable annotation identifiers, bodies, authorization, persistence, and cross-revision re-anchoring to the host.
• README.md exposes selection and text-position evidence but no review distribution surface.
• W3C Web Annotation defines an interoperable Annotation/Body/Target model and selector/state mechanisms suitable for comments attached to exact resource segments: https://www.w3.org/TR/annotation-model/
• Current editor products treat comments, tracked changes, and revision history as a coherent review workflow rather than isolated position metadata. Official references:
  • https://tiptap.dev/docs/tracked-changes/guides/comments-integration
  • https://ckeditor.com/docs/ckeditor5/latest/features/collaboration/track-changes/track-changes.html
  • https://ckeditor.com/docs/ckeditor5/latest/features/collaboration/revision-history/revision-history.html

These references are product/standards evidence, not permission to copy proprietary implementations.

Required ownership boundary

Inkspan owns:

• deterministic current-revision decorations and editor transactions;
• accessible comment/suggestion interaction surfaces;
• a React-free, versioned review contract and validation layer;
• accept/reject operations that emit exact before/after revision transition evidence;
• fail-closed handling of stale, malformed, over-limit, or unsupported review inputs;
• optional adapters to host-supplied collaboration state without provider lock-in.

The embedding host owns:

• actor identity, authentication, authorization, tenant policy, moderation, notifications, persistence, retention, legal hold, audit storage, and encryption;
• durable annotation/thread IDs and comment bodies;
• cross-revision re-anchoring policy and conflict resolution;
• collaboration provider admission and room authorization.

Smallest credible vertical slice

1. Add a public @contextualwisdomlab/cwl-editor/review subpath with versioned, bounded schemas for:
   • comment target metadata;
   • comment/thread presentation state;
   • insert/delete suggestion records;
   • review operation results and stable error codes.
2. Bind each target to one exact canonical document revision and one explicit projection/selector identity. Reuse existing selection/revision and text-position primitives rather than inventing ambiguous DOM offsets.
3. Add controlled React props/callbacks for host-supplied comments and suggestions; no implicit persistence or actor lookup.
4. Add accessible inline markers plus a review panel with:
   • keyboard traversal between targets;
   • visible focus;
   • non-color status semantics;
   • screen-reader names, counts, resolved state, and accept/reject actions;
   • responsive inline/sidebar presentation.
5. Implement deterministic accept/reject for insertion and deletion suggestions. Formatting suggestions are a separate follow-up unless the first ADR proves a bounded representation.
6. A stale revision must not be silently applied or re-anchored. Return a stable conflict result so the host can refetch/review.
7. Collaboration integration must accept host-owned Yjs/provider surfaces and must not introduce provider credentials or network calls in Inkspan.
8. Update PRD/TRD/contracts/UML/data model/threat model/traceability and add an ADR. Record a Figma File ID in the ADR only if Figma is actually used for the accepted interaction design; otherwise do not invent one.
9. Add Storybook stories or an equivalent executable component inventory for normal, selected, unresolved, resolved, stale, permission-disabled, narrow-screen, forced-colors, and print states.

Acceptance criteria

• Comment targets and suggestions round-trip through the public package without document-body or comment-body leakage into ordinary evidence metadata.
• Insert/delete suggestions can be accepted or rejected exactly once under the expected strong revision; retries are deterministic and stale revisions fail closed.
• Undo/redo behavior is documented and regression-tested for accept/reject operations.
• Concurrent host updates cannot cause a suggestion to apply to a different revision or range.
• Keyboard-only and screen-reader review journeys pass automated and real-browser tests across Chromium, Firefox, and WebKit.
• Print/export behavior explicitly includes or excludes review markup under a documented option; it never leaks interactive chrome accidentally.
• Package-consumer tests use the packed artifact and prove React-free imports for the contract/validation core.
• Production statement, branch, function, and line coverage remain 100%; public API docstring/TSDoc coverage remains 100%.
• No database, auth provider, notification provider, durable comment store, or proprietary collaboration runtime becomes an Inkspan dependency.

Priority and dependency

Priority: P1 buyer workflow, after the P0 stable-release acceptance tracked by #118. Design and contract work may proceed independently, but it must not be described as shipped until exact-head protected integration and package publication are complete.

The product/technical gap baseline is being maintained in PR #372.