@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,339 +0,0 @@
-# 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