@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/specs/wave-1-review-and-ui-contracts.md

@@ -0,0 +1,339 @@
+# Wave 1 - Review And UI Contracts
+
+**Agent:** A4 (Review And UI Contract Lock)  
+**Date:** 2026-03-25  
+**Status:** frozen for Wave 2 implementation
+
+This spec freezes the review-state boundary and the minimal calm UI shell that later waves must preserve for:
+
+- `comments-and-anchor-mapping`
+- `tracked-changes-and-review-actions`
+- `react-editor-ui`
+
+It applies the A1 design packet to the owned review and UI surfaces so later implementation waves do not drift back toward DOM-owned truth, ribbon-heavy chrome, or ambiguous opaque-region behavior.
+
+## 1. Frozen Outcomes
+
+- Comments and revisions remain outside the canonical content tree and live in `review`.
+- The editor canvas remains the primary visual surface; review chrome remains contextual and secondary.
+- Locked and opaque regions are visible, diagnosable, and whole-unit only; they are never partially editable.
+- React remains a render and command-dispatch layer over runtime snapshots; it never owns editable document truth.
+
+## 2. Review Model Boundary
+
+`src/review` owns comment threads, revision records, remap helpers, and review-facing selectors over canonical state.
+
+`src/review` does not own:
+
+- content-tree node definitions
+- position arithmetic primitives
+- transaction commit orchestration
+- OOXML import or export
+- React UI state or rendering
+
+Frozen review-store minimum:
+
+```ts
+type ReviewStore = {
+  comments: Record<string, CommentThread>;
+  revisions: Record<string, RevisionRecord>;
+};
+```
+
+Frozen comment-thread contract:
+
+```ts
+type CommentThread = {
+  commentId: string;
+  anchor: ReviewAnchor;
+  status: "open" | "resolved" | "detached";
+  comments: CommentEntry[];
+  createdBy: string;
+  createdAt: string;
+  resolvedAt?: string;
+  resolvedBy?: string;
+  warningIds: string[];
+};
+
+type CommentEntry = {
+  entryId: string;
+  authorId: string;
+  body: string;
+  createdAt: string;
+};
+```
+
+Frozen revision contract:
+
+```ts
+type RevisionRecord = {
+  revisionId: string;
+  kind: "insertion" | "deletion";
+  anchor: ReviewAnchor;
+  authorId: string;
+  createdAt: string;
+  status: "active" | "accepted" | "rejected" | "detached";
+  warningIds: string[];
+};
+```
+
+Frozen anchor union:
+
+```ts
+type ReviewAnchor =
+  | {
+      kind: "range";
+      range: { from: number; to: number };
+      assoc: { start: -1 | 1; end: -1 | 1 };
+    }
+  | {
+      kind: "node";
+      at: number;
+      assoc: -1 | 1;
+    }
+  | {
+      kind: "detached";
+      lastKnownRange: { from: number; to: number };
+      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
+    };
+```
+
+Frozen rules:
+
+- Comments and revisions reference the shared integer position space from A1 D1; they do not duplicate DOM paths, offsets, or browser selection handles.
+- Comment authoring in v1 is limited to single-paragraph editable ranges plus thread replies and resolution state.
+- Revision authoring in v1 is limited to tracked insertions and tracked deletions plus accept or reject actions.
+- Multi-paragraph editable comment ranges, tracked moves, tracked formatting changes, and structural list or table revisions remain preserve-only and locked.
+- A detached anchor remains in `review` with `kind: "detached"` and `lastKnownRange`; it is not silently removed.
+- Review warnings are stable ids referenced from `warningIds` so runtime diagnostics and UI badges can point to the same issue without inventing parallel state.
+
+## 3. Review Command Contract
+
+Review actions remain runtime commands that operate on canonical state plus `review`.
+
+Frozen supported commands:
+
+- `addComment`
+- `resolveComment`
+- `openCommentThread`
+- `acceptRevision`
+- `rejectRevision`
+- `acceptAllRevisions`
+- `rejectAllRevisions`
+- selection-driven review navigation commands
+
+Frozen prohibitions:
+
+- no UI-local comment creation state may mutate anchors directly
+- no accept or reject flow may bypass the transaction and remap pipeline
+- no review command may edit inside opaque placeholders
+
+Wave 5 still proves imported threaded-comment structure and resolution metadata on `F10`, but
+reply authoring and reopen are not part of the shipped Wave 1 through Wave 8 command surface.
+- no review command may silently discard detached comments or revisions
+
+## 4. Opaque And Locked Region Behavior
+
+Opaque and locked regions must behave the same in the review model and UI shell.
+
+Frozen opaque-region rules:
+
+- `opaque_inline` and `opaque_block` are atomic leaves in the content tree and point to preservation records by `fragmentId`.
+- Review anchors may target positions adjacent to opaque nodes but may not span into their internal preserved payload.
+- Comment creation is disallowed for a selection that partially intersects an opaque node.
+- Revision authoring is disallowed inside opaque nodes and across preserve-only structural regions.
+- Whole-node deletion of an opaque placeholder is destructive and must require an explicit warning-backed command path.
+- Locked preserve-only review constructs imported from OOXML remain visible in the document and sidebar, but their editing affordances are disabled.
+
+Frozen UI-visible states for any locked or opaque region:
+
+- `normal`: fully editable or actionable
+- `locked-preserve-only`: visible, selectable as a whole unit, not internally editable
+- `detached-review-anchor`: review artifact still exists but no longer maps to an active editable range
+- `destructive-action-required`: the next action would remove or invalidate preserved or review content and must be explicitly confirmed
+
+## 5. React Editor UI Boundary
+
+`src/ui` owns presentation, interaction composition, focus management, and theme-token application for `WordReviewEditor`.
+
+`src/ui` does not own:
+
+- canonical content truth
+- review or preservation storage
+- import or export orchestration
+- compatibility classification logic
+
+Frozen UI composition:
+
+```text
+WordReviewEditor
+  top-toolbar
+  editor-shell
+    document-canvas
+    contextual-overlays
+  optional-right-sidebar
+  optional-status-surface
+```
+
+Frozen layout priorities:
+
+1. document canvas
+2. contextual review overlays
+3. right sidebar for comments and review navigation
+4. toolbar
+5. status and compatibility surfaces
+
+Frozen layout rules:
+
+- Canvas mode is the default review posture.
+- Page mode is optional and secondary.
+- The reading column stays centered and visually dominant.
+- The right sidebar docks outside the reading column and must not compress the document into a narrow app-shell pane.
+- Toolbar density stays compact and non-ribbon-like.
+- Advanced controls stay contextual rather than permanently expanded.
+
+## 6. Runtime/UI Data Contract
+
+React binds to runtime snapshots through an external-store boundary only.
+
+Frozen runtime-owned render contract:
+
+```ts
+interface RuntimeRenderSnapshot {
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+
+  revisionToken: string;
+  isReady: boolean;
+  isDirty: boolean;
+  readOnly: boolean;
+
+  selection: SelectionSnapshot;
+  documentStats: DocumentStats;
+  comments: CommentSidebarSnapshot;
+  trackedChanges: TrackedChangesSnapshot;
+
+  compatibility: CompatibilityPanelSnapshot;
+  warnings: EditorWarning[];
+  fatalError?: EditorError;
+
+  commandState: CommandStateSnapshot;
+}
+```
+
+UI binding note:
+
+- comment sidebar focus state and active anchor emphasis derive from `RuntimeRenderSnapshot.comments.activeCommentId`
+- the shell must pass that runtime value through to both sidebar and surface decoration layers rather than recomputing active state locally
+
+Frozen rules:
+
+- The runtime owns exactly one render snapshot contract for Wave 1: `RuntimeRenderSnapshot` from `wave-1-runtime-contracts.md`.
+- This spec does not introduce a second runtime-owned render snapshot shape.
+- React may derive ephemeral presentation state such as hover, local popover geometry, or scroll position, but it may not derive an alternate editable review store.
+- Sidebar thread order, markup visibility, review highlights, warnings, and command enablement come from `RuntimeRenderSnapshot`, not DOM scanning.
+- UI selection indicators and review highlights are projections of canonical positions, not browser-native Range objects stored as truth.
+- React may hold refs for focus, measurement, and scrolling, but ref usage is an escape hatch for presentation only.
+
+Frozen UI-owned derived selector surface:
+
+```ts
+type EditorPresentationState = {
+  review: {
+    commentIdsInOrder: string[];
+    openCommentId?: string;
+    comments: Record<string, CommentThread>;
+    revisions: Record<string, RevisionRecord>;
+    markupDisplay: "clean" | "simple" | "all";
+  };
+  chrome: {
+    reviewSidebarOpen: boolean;
+    activePopover?: string;
+    focusedRegion: "canvas" | "toolbar" | "sidebar";
+    pendingDestructiveAction?: {
+      kind: "deleteOpaqueNode" | "dropDetachedAnchor";
+      targetId: string;
+    };
+  };
+  diagnostics: {
+    warningIds: string[];
+    blockExport: boolean;
+  };
+};
+```
+
+Derived selector rules:
+
+- `EditorPresentationState` is a selector output derived from `RuntimeRenderSnapshot` plus ephemeral UI-local presentation state.
+- The derived selector may reorganize data for panel rendering, but it must not redefine the runtime-owned render contract or become a second persistence surface.
+- Any field added to `EditorPresentationState` must remain derivable from the runtime snapshot, stable review records, or ephemeral UI-only state such as focus and popover geometry.
+
+## 7. Frozen Review UI Contract
+
+Persistent review UI:
+
+- comment thread sidebar
+- markup display control
+- track-changes toggle
+- comment insertion trigger
+
+Contextual review UI:
+
+- inline selection affordance for adding a comment
+- focused comment marker and active-thread highlight
+- accept or reject affordances adjacent to the selected revision or active review item
+- detached-anchor and locked-region warnings where the user is acting
+
+Frozen review UI rules:
+
+- Comments render as annotations over the canvas plus a secondary sidebar thread list; the sidebar is not the sole source of review visibility.
+- Markup visibility changes presentation only; it does not mutate review records.
+- Comment navigation and revision navigation must be possible without exposing a large persistent review control tray.
+- Review warnings use the same stable ids emitted by runtime diagnostics.
+- Detached anchors remain inspectable from the sidebar and must indicate the detach reason.
+
+## 8. Frozen Calm UI Contract
+
+The minimal UI shell later waves must preserve:
+
+- compact top toolbar with only the highest-value persistent actions
+- central document canvas with ample breathing room
+- optional right sidebar for comments and review
+- low-emphasis status area for save/export/compatibility state
+- contextual floating tools for selection-sensitive actions
+
+Explicitly disallowed drifts:
+
+- ribbon-style permanent control sprawl
+- left-navigation chrome that competes with the document surface
+- always-open heavy inspector panels for basic review tasks
+- aggressive diff colors or thick annotation borders as the default treatment
+- hard-coded one-off styling values in place of semantic tokens
+
+## 9. Interface Impacts
+
+| Surface | Exact impact |
+| --- | --- |
+| `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md` | Freezes review-store keys `comments`, `revisions`; freezes `CommentThread.status`, `RevisionRecord.status`, and `ReviewAnchor.kind`; freezes the render snapshot slices `document`, `review`, `ui`, and `diagnostics`. |
+| `src/review/README.md` | Must state that comments and revisions live outside the content tree, flow through runtime commands, and use detached-anchor retention rather than silent deletion. |
+| `src/ui/README.md` | Must state that `WordReviewEditor` is a runtime projection, that canvas mode is primary, that the sidebar is secondary, and that opaque/locked-region affordances are warning-backed whole-unit actions only. |
+| `src/review/store.ts` | Later implementation must land `ReviewStore`, `CommentThread`, `RevisionRecord`, and `ReviewAnchor` using the keys frozen here. |
+| `src/ui/WordReviewEditor.tsx` | Later implementation must bind React to runtime snapshots only and keep the shell regions named in this spec. |
+| `src/ui/comments/*` | Later implementation must expose detached-anchor, preserve-only, and active-thread states without inventing a second review truth source. |
+| `src/ui/review/*` | Later implementation must keep markup display and accept/reject controls command-driven and contextual. |
+
+## 10. Proof Handoff
+
+- Wave 2 repo-lands the React shell and runtime subscription seam without introducing React-owned document truth.
+- Wave 3 baseline-proves canvas rendering, toolbar dispatch, and ref-backed focus over runtime snapshots on F01-F02.
+- Wave 5 proves comment anchoring, thread navigation, detached-anchor handling, and sidebar synchronization on F09-F10.
+- Wave 6 proves tracked insertion or deletion rendering plus accept or reject flows on F11-F14.
+
+## 11. Out Of Scope For This Freeze
+
+- final visual polish beyond the calm-shell rules above
+- host-specific app-shell composition
+- multi-pane comparison workflows
+- editing inside preserve-only opaque regions
+- widening review authoring beyond the v1 single-paragraph comment plus insertion or deletion scope