@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/ui/WordReviewEditor.tsx

@@ -32,11 +32,14 @@ import type {
   InteractionGuardSnapshot,
   InsertImageOptions,
   InsertTableOptions,
+  MetadataPersistenceMode,
   PageLayoutSnapshot,
   PersistedEditorSnapshot,
+  ResolveMetadataConflictInput,
   ReviewQueueItem,
   ReviewQueueSnapshot,
   RuntimeRenderSnapshot,
+  ScopeMetadataPersistence,
   SectionBreakType,
   SectionLayoutPatch,
   SectionPageNumberingPatch,
@@ -71,6 +74,8 @@ import type {
   WorkspaceMode,
   ZoomLevel,
 } from "../api/public-types";
+import { MetadataResolverMissingError } from "../api/public-types";
+import type { ScopeMetadataResolver } from "../api/scope-metadata-resolver-types.ts";
 import {
   editorSessionStateFromPersistedSnapshot,
   persistedSnapshotFromEditorSessionState,
@@ -254,10 +259,219 @@ type SelectionToolbarDismissReason =
   | "comment-action"
   | "escape";
 
+// ---------------------------------------------------------------------------
+// P17 module-level helpers — metadata persistence
+// ---------------------------------------------------------------------------
+
+function conflictKey(input: {
+  scopeId?: string;
+  entryId?: string;
+  fieldKey?: string;
+}): string {
+  return `${input.scopeId ?? ""}|${input.entryId ?? ""}|${input.fieldKey ?? ""}`;
+}
+
+function resolveEffective(input: {
+  overlay?: MetadataPersistenceMode;
+  scope?: ScopeMetadataPersistence;
+  field?: ScopeMetadataPersistence;
+}): "internal" | "external" {
+  if (input.field === "internal" || input.field === "external") return input.field;
+  if (input.scope === "internal" || input.scope === "external") return input.scope;
+  return input.overlay ?? "internal";
+}
+
+/**
+ * A pending conflict record held in `metadataConflictPendingRef` while
+ * the host decides how to resolve.  Keyed by `conflictKey(...)`.
+ */
+interface PendingConflict {
+  scopeId?: string;
+  entryId?: string;
+  fieldKey?: string;
+  embedded: { value?: Record<string, unknown>; version?: number } | null;
+  external: { value?: Record<string, unknown>; version?: number } | null;
+  defaultPolicy: "prefer-latest";
+}
+
+/** Emit a single `metadata_conflict_detected` event and register the pending conflict. */
+function registerAndEmitConflict(args: {
+  onEvent: ((event: WordReviewEditorEvent) => void) | undefined;
+  documentId: string;
+  conflict: PendingConflict;
+  pendingConflicts: Map<string, PendingConflict>;
+}): void {
+  const key = conflictKey(args.conflict);
+  // Guard: do not emit duplicate events for the same key in a single pass.
+  if (args.pendingConflicts.has(key)) return;
+  args.pendingConflicts.set(key, args.conflict);
+  args.onEvent?.({
+    type: "metadata_conflict_detected",
+    documentId: args.documentId,
+    scopeId: args.conflict.scopeId,
+    entryId: args.conflict.entryId,
+    fieldKey: args.conflict.fieldKey,
+    embedded: args.conflict.embedded,
+    external: args.conflict.external,
+    defaultPolicy: args.conflict.defaultPolicy,
+  });
+}
+
+async function runConvertScopesToInternal(args: {
+  runtime: WordReviewEditorRuntime;
+  scopeIds: string[];
+  resolver: ScopeMetadataResolver | null;
+  /** When provided, version mismatches emit `metadata_conflict_detected`. */
+  documentId?: string;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  pendingConflicts?: Map<string, PendingConflict>;
+}): Promise<void> {
+  if (!args.resolver) throw new MetadataResolverMissingError();
+  const snapshot = args.runtime.getWorkflowMetadataSnapshot();
+  const overlay = args.runtime.getWorkflowOverlay();
+
+  const nextEntries = await Promise.all(
+    snapshot.entries.map(async (entry) => {
+      if (!entry.scopeId || !args.scopeIds.includes(entry.scopeId)) return entry;
+      const scope = overlay?.scopes.find((s) => s.scopeId === entry.scopeId);
+      const effective = resolveEffective({
+        overlay: overlay?.metadataPersistence,
+        scope: scope?.metadataPersistence,
+        field: entry.metadataPersistence,
+      });
+      if (effective !== "external" || !entry.storageRef) return entry;
+      const resolved = await args.resolver!.resolve(entry.storageRef);
+      if (!resolved) return entry;
+
+      // Conflict detection: compare embedded metadataVersion vs resolver version.
+      if (
+        args.pendingConflicts &&
+        args.documentId !== undefined &&
+        entry.metadataVersion !== undefined &&
+        resolved.version !== undefined &&
+        entry.metadataVersion !== resolved.version
+      ) {
+        registerAndEmitConflict({
+          onEvent: args.onEvent,
+          documentId: args.documentId,
+          pendingConflicts: args.pendingConflicts,
+          conflict: {
+            scopeId: entry.scopeId,
+            entryId: entry.entryId,
+            // External entries have no inline value; embedded side carries version only.
+            embedded: { version: entry.metadataVersion },
+            external: { value: resolved.value, version: resolved.version },
+            defaultPolicy: "prefer-latest",
+          },
+        });
+      }
+
+      // Default behavior: always apply the resolved value (host can override via resolveMetadataConflict).
+      return {
+        ...entry,
+        value: resolved.value,
+        metadataPersistence: "internal" as const,
+        storageRef: undefined,
+        metadataVersion: resolved.version ?? entry.metadataVersion,
+      };
+    }),
+  );
+
+  args.runtime.setWorkflowMetadataEntries(nextEntries);
+}
+
+async function runConvertScopesToExternal(args: {
+  runtime: WordReviewEditorRuntime;
+  scopeIds: string[];
+  resolver: ScopeMetadataResolver | null;
+  /** When provided, version-conflict publish errors emit `metadata_conflict_detected`. */
+  documentId?: string;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  pendingConflicts?: Map<string, PendingConflict>;
+}): Promise<void> {
+  if (!args.resolver) throw new MetadataResolverMissingError();
+  const snapshot = args.runtime.getWorkflowMetadataSnapshot();
+  const overlay = args.runtime.getWorkflowOverlay();
+
+  const nextEntries = await Promise.all(
+    snapshot.entries.map(async (entry) => {
+      if (!entry.scopeId || !args.scopeIds.includes(entry.scopeId)) return entry;
+      const scope = overlay?.scopes.find((s) => s.scopeId === entry.scopeId);
+      const effective = resolveEffective({
+        overlay: overlay?.metadataPersistence,
+        scope: scope?.metadataPersistence,
+        field: entry.metadataPersistence,
+      });
+      if (effective === "external") return entry;
+
+      try {
+        const { ref, version } = await args.resolver!.publish({
+          scopeId: entry.scopeId,
+          metadataId: entry.metadataId,
+          entryId: entry.entryId,
+          value: entry.value ?? {},
+          expectedVersion: entry.metadataVersion,
+        });
+        return {
+          ...entry,
+          value: undefined,
+          metadataPersistence: "external" as const,
+          storageRef: ref,
+          metadataVersion: version,
+        };
+      } catch (err: unknown) {
+        // Duck-type version-conflict errors (HarnessVersionConflictError or compatible shapes).
+        if (
+          args.pendingConflicts &&
+          args.documentId !== undefined &&
+          err instanceof Error &&
+          (err.name === "HarnessVersionConflictError" ||
+            ("ref" in err && "expected" in err && "actual" in err))
+        ) {
+          const conflictErr = err as Error & { ref?: string; expected?: number; actual?: number };
+          registerAndEmitConflict({
+            onEvent: args.onEvent,
+            documentId: args.documentId,
+            pendingConflicts: args.pendingConflicts,
+            conflict: {
+              scopeId: entry.scopeId,
+              entryId: entry.entryId,
+              // Embedded side: the entry's current inline value and metadataVersion.
+              embedded: { value: entry.value, version: entry.metadataVersion },
+              // External side: only the rowstore's actual version (no value available from error).
+              external: { version: conflictErr.actual },
+              defaultPolicy: "prefer-latest",
+            },
+          });
+          // Skip this entry — do not publish; leave it unchanged.
+          return entry;
+        }
+        // Non-conflict errors propagate normally.
+        throw err;
+      }
+    }),
+  );
+
+  args.runtime.setWorkflowMetadataEntries(nextEntries);
+}
+
+// ---------------------------------------------------------------------------
+
 export function __createWordReviewEditorRefBridge(
   runtime: WordReviewEditorRuntime,
   mountedSurface?: TwProseMirrorSurfaceRef | null,
+  options?: {
+    documentId?: string;
+    onEvent?: (event: WordReviewEditorEvent) => void;
+    resolverRef?: { current: ScopeMetadataResolver | null };
+    conflictResolutionsRef?: {
+      current: Map<string, { choice: string; mergedValue?: Record<string, unknown> }>;
+    };
+  },
 ): WordReviewEditorRef {
+  // Pending-conflict queue for this bridge instance.  Keyed by conflictKey(...).
+  const pendingConflicts = new Map<string, PendingConflict>();
+
   return {
     focus: () => runtime.focus(),
     blur: () => runtime.blur(),
@@ -277,6 +491,10 @@ export function __createWordReviewEditorRefBridge(
     rejectChange: (changeId) => runtime.rejectChange(changeId),
     acceptAllChanges: () => runtime.acceptAllChanges(),
     rejectAllChanges: () => runtime.rejectAllChanges(),
+    acceptSuggestionGroup: (groupId) =>
+      applySuggestionGroupAction(runtime, groupId, "accept"),
+    rejectSuggestionGroup: (groupId) =>
+      applySuggestionGroupAction(runtime, groupId, "reject"),
     exportDocx: (options) => runtime.exportDocx(options),
     getSessionState: () => runtime.getSessionState(),
     getSnapshot: () => runtime.getPersistedSnapshot(),
@@ -575,6 +793,167 @@ export function __createWordReviewEditorRefBridge(
     getWorkflowMetadataSnapshot: () => {
       return clonePublicValue(runtime.getWorkflowMetadataSnapshot());
     },
+    // P17 — metadata persistence toggle + convert methods.
+    setMetadataPersistenceMode: (mode) => {
+      if (mode === "external" && !(options?.resolverRef?.current ?? null)) {
+        throw new MetadataResolverMissingError();
+      }
+      const overlay = runtime.getWorkflowOverlay();
+      if (!overlay) return;
+      runtime.setWorkflowOverlay({ ...overlay, metadataPersistence: mode });
+      options?.onEvent?.({
+        type: "metadata_persistence_mode_changed",
+        documentId: options?.documentId ?? "",
+        mode,
+      });
+    },
+    getMetadataPersistenceMode: () => {
+      return runtime.getWorkflowOverlay()?.metadataPersistence ?? "internal";
+    },
+    setScopeMetadataPersistence: (scopeId, persistence) => {
+      if (persistence === "external" && !(options?.resolverRef?.current ?? null)) {
+        throw new MetadataResolverMissingError();
+      }
+      const overlay = runtime.getWorkflowOverlay();
+      if (!overlay) return;
+      const nextOverlay = {
+        ...overlay,
+        scopes: overlay.scopes.map((s) => {
+          if (s.scopeId !== scopeId) return s;
+          if (persistence === "inherit") {
+            const { metadataPersistence: _, ...rest } = s;
+            return rest as typeof s;
+          }
+          return { ...s, metadataPersistence: persistence };
+        }),
+      };
+      runtime.setWorkflowOverlay(nextOverlay);
+      options?.onEvent?.({
+        type: "scope_metadata_persistence_changed",
+        documentId: options?.documentId ?? "",
+        scopeId,
+        persistence,
+      });
+    },
+    getScopeMetadataPersistence: (scopeId) => {
+      const overlay = runtime.getWorkflowOverlay();
+      return overlay?.scopes.find((s) => s.scopeId === scopeId)?.metadataPersistence ?? "inherit";
+    },
+    setAllScopesMetadataPersistence: (persistence) => {
+      if (persistence === "external" && !(options?.resolverRef?.current ?? null)) {
+        throw new MetadataResolverMissingError();
+      }
+      const overlay = runtime.getWorkflowOverlay();
+      if (!overlay) return;
+      const nextOverlay = {
+        ...overlay,
+        scopes: overlay.scopes.map((s) => {
+          if (persistence === "inherit") {
+            const { metadataPersistence: _, ...rest } = s;
+            return rest as typeof s;
+          }
+          return { ...s, metadataPersistence: persistence };
+        }),
+      };
+      runtime.setWorkflowOverlay(nextOverlay);
+      options?.onEvent?.({
+        type: "scope_metadata_persistence_changed",
+        documentId: options?.documentId ?? "",
+        scopeId: "*",
+        persistence,
+      });
+    },
+    setScopeMetadataResolver: (resolver) => {
+      if (options?.resolverRef) {
+        options.resolverRef.current = resolver;
+      }
+    },
+    resolveMetadataConflict: (input: ResolveMetadataConflictInput) => {
+      // Legacy: keep conflictResolutionsRef updated so Task 8 tests pass.
+      if (options?.conflictResolutionsRef) {
+        options.conflictResolutionsRef.current.set(conflictKey(input), {
+          choice: input.choice,
+          mergedValue: input.mergedValue,
+        });
+      }
+
+      // New: apply the chosen value to the metadata snapshot.
+      const pending = pendingConflicts.get(conflictKey(input));
+      if (!pending) return; // No pending conflict — idempotent no-op.
+
+      let finalValue: Record<string, unknown> | undefined;
+      if (input.choice === "embedded") {
+        finalValue = pending.embedded?.value;
+      } else if (input.choice === "external") {
+        finalValue = pending.external?.value;
+      } else if (input.choice === "merge") {
+        finalValue = input.mergedValue;
+      }
+
+      if (finalValue === undefined) {
+        // Nothing to write (e.g., embedded side has no inline value).
+        pendingConflicts.delete(conflictKey(input));
+        return;
+      }
+
+      const winnerVersion =
+        input.choice === "external"
+          ? pending.external?.version ?? undefined
+          : input.choice === "embedded"
+            ? pending.embedded?.version ?? undefined
+            : undefined;
+
+      const snapshot = runtime.getWorkflowMetadataSnapshot();
+      const nextEntries = snapshot.entries.map((entry) => {
+        if (input.entryId && entry.entryId !== input.entryId) return entry;
+        if (input.scopeId && entry.scopeId !== input.scopeId) return entry;
+        return {
+          ...entry,
+          value: finalValue,
+          metadataPersistence: "internal" as const,
+          storageRef: undefined,
+          metadataVersion: winnerVersion ?? entry.metadataVersion,
+        };
+      });
+      runtime.setWorkflowMetadataEntries(nextEntries);
+      pendingConflicts.delete(conflictKey(input));
+    },
+    convertScopesToInternal: async (scopeIds) => {
+      await runConvertScopesToInternal({
+        runtime,
+        scopeIds,
+        resolver: options?.resolverRef?.current ?? null,
+        documentId: options?.documentId,
+        onEvent: options?.onEvent,
+        pendingConflicts,
+      });
+    },
+    convertScopesToExternal: async (scopeIds) => {
+      await runConvertScopesToExternal({
+        runtime,
+        scopeIds,
+        resolver: options?.resolverRef?.current ?? null,
+        documentId: options?.documentId,
+        onEvent: options?.onEvent,
+        pendingConflicts,
+      });
+    },
+    // Schema 1.2 — EditorStateChannel delegation.
+    configureEditorStatePolicy: (policy) => {
+      runtime.configureEditorStatePolicy(policy);
+    },
+    registerEditorStateResolver: (resolver) => {
+      runtime.registerEditorStateResolver(resolver);
+    },
+    registerEditorStatePersister: (persister) => {
+      runtime.registerEditorStatePersister(persister);
+    },
+    getEditorStateKey: (namespace) => {
+      return runtime.getEditorStateKey(namespace);
+    },
+    retryPendingPersist: async (namespace) => {
+      await runtime.retryPendingPersist(namespace);
+    },
     setHostAnnotationOverlay: (overlay) => {
       runtime.setHostAnnotationOverlay(clonePublicValue(overlay));
     },
@@ -687,6 +1066,11 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     const shellRef = useRef<HTMLDivElement | null>(null);
     const lastSelectionToolbarKeyRef = useRef<string | null>(null);
     const lastAnnouncedErrorIdRef = useRef<string | null>(null);
+    const scopeMetadataResolverRef = useRef<ScopeMetadataResolver | null>(null);
+    const metadataConflictResolutionsRef = useRef(
+      new Map<string, { choice: string; mergedValue?: Record<string, unknown> }>(),
+    );
+    const metadataConflictPendingRef = useRef(new Map<string, PendingConflict>());
     const {
       runtime,
       loadError,
@@ -1094,6 +1478,10 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         rejectChange: (changeId) => activeRuntime.rejectChange(changeId),
         acceptAllChanges: () => activeRuntime.acceptAllChanges(),
         rejectAllChanges: () => activeRuntime.rejectAllChanges(),
+        acceptSuggestionGroup: (groupId) =>
+          applySuggestionGroupAction(activeRuntime, groupId, "accept"),
+        rejectSuggestionGroup: (groupId) =>
+          applySuggestionGroupAction(activeRuntime, groupId, "reject"),
         exportDocx: (options) =>
           runtime
             ? persistAndExportFromBoundary({
@@ -1446,6 +1834,165 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         getWorkflowMetadataSnapshot: () => {
           return clonePublicValue(activeRuntime.getWorkflowMetadataSnapshot());
         },
+        // P17 — metadata persistence toggle + convert methods.
+        setMetadataPersistenceMode: (mode) => {
+          if (mode === "external" && scopeMetadataResolverRef.current === null) {
+            throw new MetadataResolverMissingError();
+          }
+          const overlay = activeRuntime.getWorkflowOverlay();
+          if (!overlay) return;
+          activeRuntime.setWorkflowOverlay({ ...overlay, metadataPersistence: mode });
+          onEventRef.current?.({
+            type: "metadata_persistence_mode_changed",
+            documentId,
+            mode,
+          });
+        },
+        getMetadataPersistenceMode: () => {
+          return activeRuntime.getWorkflowOverlay()?.metadataPersistence ?? "internal";
+        },
+        setScopeMetadataPersistence: (scopeId, persistence) => {
+          if (persistence === "external" && scopeMetadataResolverRef.current === null) {
+            throw new MetadataResolverMissingError();
+          }
+          const overlay = activeRuntime.getWorkflowOverlay();
+          if (!overlay) return;
+          const nextOverlay = {
+            ...overlay,
+            scopes: overlay.scopes.map((s) => {
+              if (s.scopeId !== scopeId) return s;
+              if (persistence === "inherit") {
+                const { metadataPersistence: _, ...rest } = s;
+                return rest as typeof s;
+              }
+              return { ...s, metadataPersistence: persistence };
+            }),
+          };
+          activeRuntime.setWorkflowOverlay(nextOverlay);
+          onEventRef.current?.({
+            type: "scope_metadata_persistence_changed",
+            documentId,
+            scopeId,
+            persistence,
+          });
+        },
+        getScopeMetadataPersistence: (scopeId) => {
+          const overlay = activeRuntime.getWorkflowOverlay();
+          return (
+            overlay?.scopes.find((s) => s.scopeId === scopeId)?.metadataPersistence ?? "inherit"
+          );
+        },
+        setAllScopesMetadataPersistence: (persistence) => {
+          if (persistence === "external" && scopeMetadataResolverRef.current === null) {
+            throw new MetadataResolverMissingError();
+          }
+          const overlay = activeRuntime.getWorkflowOverlay();
+          if (!overlay) return;
+          const nextOverlay = {
+            ...overlay,
+            scopes: overlay.scopes.map((s) => {
+              if (persistence === "inherit") {
+                const { metadataPersistence: _, ...rest } = s;
+                return rest as typeof s;
+              }
+              return { ...s, metadataPersistence: persistence };
+            }),
+          };
+          activeRuntime.setWorkflowOverlay(nextOverlay);
+          onEventRef.current?.({
+            type: "scope_metadata_persistence_changed",
+            documentId,
+            scopeId: "*",
+            persistence,
+          });
+        },
+        setScopeMetadataResolver: (resolver) => {
+          scopeMetadataResolverRef.current = resolver;
+        },
+        resolveMetadataConflict: (input) => {
+          // Legacy: keep metadataConflictResolutionsRef updated so Task 8 tests pass.
+          metadataConflictResolutionsRef.current.set(conflictKey(input), {
+            choice: input.choice,
+            mergedValue: input.mergedValue,
+          });
+
+          // New: apply the chosen value to the metadata snapshot.
+          const pending = metadataConflictPendingRef.current.get(conflictKey(input));
+          if (!pending) return; // No pending conflict — idempotent no-op.
+
+          let finalValue: Record<string, unknown> | undefined;
+          if (input.choice === "embedded") {
+            finalValue = pending.embedded?.value;
+          } else if (input.choice === "external") {
+            finalValue = pending.external?.value;
+          } else if (input.choice === "merge") {
+            finalValue = input.mergedValue;
+          }
+
+          if (finalValue === undefined) {
+            // Nothing to write (e.g., embedded side has no inline value).
+            metadataConflictPendingRef.current.delete(conflictKey(input));
+            return;
+          }
+
+          const winnerVersion =
+            input.choice === "external"
+              ? pending.external?.version ?? undefined
+              : input.choice === "embedded"
+                ? pending.embedded?.version ?? undefined
+                : undefined;
+
+          const snapshot = activeRuntime.getWorkflowMetadataSnapshot();
+          const nextEntries = snapshot.entries.map((entry) => {
+            if (input.entryId && entry.entryId !== input.entryId) return entry;
+            if (input.scopeId && entry.scopeId !== input.scopeId) return entry;
+            return {
+              ...entry,
+              value: finalValue,
+              metadataPersistence: "internal" as const,
+              storageRef: undefined,
+              metadataVersion: winnerVersion ?? entry.metadataVersion,
+            };
+          });
+          activeRuntime.setWorkflowMetadataEntries(nextEntries);
+          metadataConflictPendingRef.current.delete(conflictKey(input));
+        },
+        convertScopesToInternal: async (scopeIds) => {
+          await runConvertScopesToInternal({
+            runtime: activeRuntime,
+            scopeIds,
+            resolver: scopeMetadataResolverRef.current,
+            documentId,
+            onEvent: onEventRef.current,
+            pendingConflicts: metadataConflictPendingRef.current,
+          });
+        },
+        convertScopesToExternal: async (scopeIds) => {
+          await runConvertScopesToExternal({
+            runtime: activeRuntime,
+            scopeIds,
+            resolver: scopeMetadataResolverRef.current,
+            documentId,
+            onEvent: onEventRef.current,
+            pendingConflicts: metadataConflictPendingRef.current,
+          });
+        },
+        // Schema 1.2 — EditorStateChannel delegation.
+        configureEditorStatePolicy: (policy) => {
+          activeRuntime.configureEditorStatePolicy(policy);
+        },
+        registerEditorStateResolver: (resolver) => {
+          activeRuntime.registerEditorStateResolver(resolver);
+        },
+        registerEditorStatePersister: (persister) => {
+          activeRuntime.registerEditorStatePersister(persister);
+        },
+        getEditorStateKey: (namespace) => {
+          return activeRuntime.getEditorStateKey(namespace);
+        },
+        retryPendingPersist: async (namespace) => {
+          await activeRuntime.retryPendingPersist(namespace);
+        },
         setHostAnnotationOverlay: (overlay) => {
           setHostAnnotationOverlayState(clonePublicValue(overlay));
         },
@@ -2103,6 +2650,19 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           code: "unsupported_surface",
           message,
         }]),
+      onPasteApplied: (meta: {
+        segmentCount: number;
+        charCount: number;
+        source: "paste" | "drop";
+      }) => {
+        onEventRef.current?.({
+          type: "paste_applied",
+          documentId: props.documentId,
+          segmentCount: meta.segmentCount,
+          charCount: meta.charCount,
+          source: meta.source,
+        });
+      },
     };
 
     const reviewCallbacks = {
@@ -2248,14 +2808,21 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         applyRuntimeImageResize(activeRuntime, mediaId, dimensions),
       onSetImageFrame: (mediaId, offsets) =>
         applyRuntimeImageReposition(activeRuntime, mediaId, offsets),
-      onOpenHeaderStory: () =>
-        openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "header"),
-      onOpenFooterStory: () =>
-        openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "footer"),
+      // P8.11 — `onOpenHeaderStory` / `onOpenFooterStory` retired from the
+      // WordReviewEditor wiring.  Per-page header / footer bands rendered
+      // by `TwPageStackChromeLayer` call `onOpenStory(target)` with the
+      // exact `EditorStoryTarget` they represent, so the variant /
+      // relationship resolution happens inside the layout facet instead
+      // of the UI.  The deprecated props remain in the workspace type
+      // with a mount-time `console.warn`; hosts that still pass them can
+      // migrate to `onOpenStory` at their leisure.
       onOpenHeaderStoryForPage: (pageIndex: number) =>
         openStoryForPage(activeRuntime, pageIndex, "header"),
       onOpenFooterStoryForPage: (pageIndex: number) =>
         openStoryForPage(activeRuntime, pageIndex, "footer"),
+      onOpenStory: (target) => {
+        activeRuntime.openStory(target);
+      },
       onDeleteSectionBreak: (sectionIndex) =>
         applyRuntimeDeleteSectionBreak(activeRuntime, sectionIndex),
       onUpdateSectionLayout: (sectionIndex, patch) =>
@@ -2386,6 +2953,17 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         interactionGuardSnapshot={interactionGuardSnapshot}
         chromePreset={effectiveChromePreset}
         chromeOptions={chromeOptions}
+        {...(props.collabSession ? { collabSession: props.collabSession } : {})}
+        {...(props.collabTransportStatus
+          ? { collabTransportStatus: props.collabTransportStatus }
+          : {})}
+        {...(props.activeCommentId !== undefined
+          ? { activeCommentId: props.activeCommentId }
+          : {})}
+        collabActorId={currentUser.userId}
+        {...(props.collabSendBaseline
+          ? { collabSendBaseline: props.collabSendBaseline }
+          : {})}
         reviewQueue={reviewQueueSnapshot}
         documentContextAnalytics={documentContextAnalytics}
         selectionContextAnalytics={selectionContextAnalytics}
@@ -2450,11 +3028,83 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
             action: payload.action,
           });
         }}
+        onScopeAcceptSuggestionGroup={(payload) => {
+          applySuggestionGroupAction(activeRuntime, payload.groupId, "accept");
+        }}
+        onScopeRejectSuggestionGroup={(payload) => {
+          applySuggestionGroupAction(activeRuntime, payload.groupId, "reject");
+        }}
+        onScopeAskAgent={(payload) => {
+          // Resolve the scope's anchor + story from the facet's card
+          // model so the agent request carries the canonical range.
+          const facet = activeRuntime.layout;
+          const models =
+            facet && typeof facet.getAllScopeCardModels === "function"
+              ? facet.getAllScopeCardModels()
+              : [];
+          const model = models.find((entry) => entry.scopeId === payload.scopeId);
+          if (!model) return;
+          const scopeSnapshot = activeRuntime.getWorkflowScopeSnapshot();
+          const scopes = scopeSnapshot?.scopes ?? [];
+          const scope = scopes.find((entry) => entry.scopeId === payload.scopeId);
+          if (!scope) return;
+          const anchor = scope.anchor;
+          if (!anchor) return;
+          const requestId =
+            typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+              ? `req-${crypto.randomUUID()}`
+              : `req-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+          const eventPayload: Extract<
+            WordReviewEditorEvent,
+            { type: "agent-on-selection-requested" }
+          > = {
+            type: "agent-on-selection-requested",
+            documentId,
+            requestId,
+            scopeId: payload.scopeId,
+            anchor,
+            selectionText: model.label ?? "",
+            ...(scope.storyTarget ? { storyTarget: scope.storyTarget } : {}),
+          };
+          onEventRef.current?.(eventPayload);
+        }}
       />
     );
   },
 );
 
+/**
+ * R3 — best-effort suggestion-group accept/reject fan-out.  Resolves
+ * the group's suggestions from the current snapshot, then fans out
+ * `acceptChange` / `rejectChange` across every changeId in each
+ * group member.  P2 batches these in rapid succession; the runtime
+ * commit boundary collapses them into a single logical transaction.
+ * A future phase adds true atomicity at the runtime level.
+ */
+function applySuggestionGroupAction(
+  runtime: WordReviewEditorRuntime,
+  groupId: string,
+  action: "accept" | "reject",
+): void {
+  const snapshot = runtime.getSuggestionsSnapshot();
+  const group = snapshot.groups?.find((entry) => entry.groupId === groupId);
+  if (!group) return;
+  const byId = new Map(
+    snapshot.suggestions.map((entry) => [entry.suggestionId, entry]),
+  );
+  for (const suggestionId of group.suggestionIds) {
+    const suggestion = byId.get(suggestionId);
+    if (!suggestion) continue;
+    for (const changeId of suggestion.changeIds) {
+      if (action === "accept") {
+        runtime.acceptChange(changeId);
+      } else {
+        runtime.rejectChange(changeId);
+      }
+    }
+  }
+}
+
 function applyRuntimeFormattingOperation(
   runtime: WordReviewEditorRuntime,
   operation:
@@ -4279,47 +4929,6 @@ function openStoryForPage(
   runtime.openStory(target);
 }
 
-function openDefaultStoryVariant(
-  runtime: WordReviewEditorRuntime,
-  pageLayout: PageLayoutSnapshot | undefined,
-  navigation: ReturnType<WordReviewEditorRuntime["getDocumentNavigationSnapshot"]> | undefined,
-  kind: "header" | "footer",
-): void {
-  const variants =
-    kind === "header"
-      ? pageLayout?.headerVariants
-      : pageLayout?.footerVariants;
-  const activePage = navigation?.pages[navigation.activePageIndex];
-  const isFirstPageInSection =
-    activePage !== undefined &&
-    activePage.sectionIndex === pageLayout?.sectionIndex &&
-    activePage.pageInSection === 0;
-  const isEvenDocumentPage = activePage !== undefined && (activePage.pageIndex + 1) % 2 === 0;
-
-  let variant =
-    pageLayout?.differentFirstPage && isFirstPageInSection
-      ? variants?.find((entry) => entry.variant === "first")
-      : undefined;
-
-  if (!variant && pageLayout?.differentOddEvenPages && isEvenDocumentPage) {
-    variant = variants?.find((entry) => entry.variant === "even");
-  }
-
-  if (!variant) {
-    variant = variants?.find((entry) => entry.variant === "default") ?? variants?.[0];
-  }
-
-  if (!variant) {
-    return;
-  }
-  runtime.openStory({
-    kind,
-    relationshipId: variant.relationshipId,
-    variant: variant.variant,
-    sectionIndex: pageLayout?.sectionIndex,
-  });
-}
-
 function searchRuntimeDocument(
   runtime: WordReviewEditorRuntime,
   mountedSurface: TwProseMirrorSurfaceRef | null,