@beyondwork/docx-react-component 1.0.33 → 1.0.35

package/src/model/snapshot.ts

@@ -124,12 +124,20 @@ export interface PersistedWorkflowMetadataSnapshot {
 
 export interface PersistedWorkflowScope {
   scopeId: string;
+  version?: number;
   mode: "edit" | "suggest" | "comment" | "view";
   anchor: Record<string, unknown>;
   storyTarget?: Record<string, unknown>;
   workItemId?: string;
   label?: string;
   domain?: "legal" | "commercial" | "finance" | "other";
+  metadata?: PersistedWorkflowScopeMetadataField[];
+}
+
+export interface PersistedWorkflowScopeMetadataField {
+  key: string;
+  valueType?: "string" | "number" | "boolean" | "json";
+  value?: string | number | boolean | Record<string, unknown>;
 }
 
 export interface PersistedWorkflowWorkItem {
@@ -726,12 +734,62 @@ function validateWorkflowScope(
     issues.push({ path: `${path}.mode`, message: "mode must be edit, suggest, comment, or view." });
   }
   asPlainObject(record.anchor, `${path}.anchor`, issues);
+  if (record.version !== undefined && !Number.isInteger(record.version)) {
+    issues.push({ path: `${path}.version`, message: "version must be an integer." });
+  }
   if (record.workItemId !== undefined) {
     expectString(record.workItemId, `${path}.workItemId`, issues);
   }
   if (record.label !== undefined) {
     expectString(record.label, `${path}.label`, issues);
   }
+  if (record.metadata !== undefined) {
+    if (!Array.isArray(record.metadata)) {
+      issues.push({ path: `${path}.metadata`, message: "metadata must be an array." });
+    } else {
+      record.metadata.forEach((field, index) =>
+        validateWorkflowScopeMetadataField(field, `${path}.metadata[${index}]`, issues),
+      );
+    }
+  }
+}
+
+function validateWorkflowScopeMetadataField(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+  expectString(record.key, `${path}.key`, issues);
+  if (
+    record.valueType !== undefined &&
+    record.valueType !== "string" &&
+    record.valueType !== "number" &&
+    record.valueType !== "boolean" &&
+    record.valueType !== "json"
+  ) {
+    issues.push({
+      path: `${path}.valueType`,
+      message: "valueType must be string, number, boolean, or json.",
+    });
+  }
+  if (
+    record.value !== undefined &&
+    typeof record.value !== "string" &&
+    typeof record.value !== "number" &&
+    typeof record.value !== "boolean"
+  ) {
+    const nestedRecord = asPlainObject(record.value, `${path}.value`, issues);
+    if (!nestedRecord) {
+      issues.push({
+        path: `${path}.value`,
+        message: "value must be a string, number, boolean, or plain object.",
+      });
+    }
+  }
 }
 
 function validateWorkflowWorkItem(

package/src/runtime/collab-review-sync.ts

@@ -0,0 +1,254 @@
+import * as Y from "yjs";
+
+import type { DocumentRuntime, DocumentRuntimeEvent, Unsubscribe } from "./document-runtime.ts";
+
+// ---------------------------------------------------------------------------
+// Serialised shapes stored inside the Y.Maps
+// ---------------------------------------------------------------------------
+
+interface YCommentThread {
+  commentId: string;
+  status: "open" | "resolved" | "detached";
+  anchor: { kind: string; [key: string]: unknown };
+  createdAt: string;
+  createdBy: string;
+  authorId: string;
+  body: string;
+  entries: Array<{
+    entryId: string;
+    authorId: string;
+    body: string;
+    createdAt: string;
+  }>;
+  resolvedAt?: string;
+  resolvedBy?: string;
+  warningIds: string[];
+  sourceClientId: number;
+}
+
+interface YRevisionAction {
+  changeId: string;
+  action: "accept" | "reject";
+  sourceClientId: number;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface CollabReviewSyncHandle {
+  destroy(): void;
+}
+
+export function createCollabReviewSync(
+  ydoc: Y.Doc,
+  runtime: DocumentRuntime,
+): CollabReviewSyncHandle {
+  const yComments = ydoc.getMap<YCommentThread>("comments");
+  const yRevisionActions = ydoc.getMap<YRevisionAction>("revisionActions");
+  const clientId = ydoc.clientID;
+
+  let suppressLocalEvents = false;
+
+  // --- Local → Yjs ---------------------------------------------------------
+
+  const unsubEvents: Unsubscribe = runtime.subscribeToEvents((event) => {
+    if (suppressLocalEvents) return;
+
+    switch (event.type) {
+      case "comment_added":
+        pushCommentToYjs(event.commentId);
+        break;
+      case "comment_resolved":
+        syncCommentFieldToYjs(event.commentId);
+        break;
+      case "change_accepted":
+        yRevisionActions.set(revisionActionKey(event.changeId, "accept"), {
+          changeId: event.changeId,
+          action: "accept",
+          sourceClientId: clientId,
+        });
+        break;
+      case "change_rejected":
+        yRevisionActions.set(revisionActionKey(event.changeId, "reject"), {
+          changeId: event.changeId,
+          action: "reject",
+          sourceClientId: clientId,
+        });
+        break;
+    }
+  });
+
+  function pushCommentToYjs(commentId: string): void {
+    const thread = runtime
+      .getRenderSnapshot()
+      .comments.threads.find((t) => t.commentId === commentId);
+    if (!thread) return;
+
+    yComments.set(commentId, {
+      commentId: thread.commentId,
+      status: thread.status,
+      anchor: thread.anchor,
+      createdAt: thread.createdAt,
+      createdBy: thread.createdBy,
+      authorId: thread.createdBy,
+      body: thread.entries[0]?.body ?? "",
+      entries: thread.entries.map((e) => ({
+        entryId: e.entryId,
+        authorId: e.authorId,
+        body: e.body,
+        createdAt: e.createdAt,
+      })),
+      resolvedAt: thread.resolvedAt,
+      resolvedBy: thread.resolvedBy,
+      warningIds: [],
+      sourceClientId: clientId,
+    });
+  }
+
+  function syncCommentFieldToYjs(commentId: string): void {
+    const existing = yComments.get(commentId);
+    const thread = runtime
+      .getRenderSnapshot()
+      .comments.threads.find((t) => t.commentId === commentId);
+    if (!existing || !thread) return;
+
+    yComments.set(commentId, {
+      ...existing,
+      status: thread.status,
+      entries: thread.entries.map((e) => ({
+        entryId: e.entryId,
+        authorId: e.authorId,
+        body: e.body,
+        createdAt: e.createdAt,
+      })),
+      resolvedAt: thread.resolvedAt,
+      resolvedBy: thread.resolvedBy,
+      sourceClientId: clientId,
+    });
+  }
+
+  // --- Yjs → Local ---------------------------------------------------------
+
+  function onCommentMapChange(event: Y.YMapEvent<YCommentThread>): void {
+    suppressLocalEvents = true;
+    try {
+      for (const [commentId, change] of event.changes.keys) {
+        const entry = yComments.get(commentId);
+        if (!entry || entry.sourceClientId === clientId) continue;
+
+        const existing = runtime
+          .getRenderSnapshot()
+          .comments.threads.find((t) => t.commentId === commentId);
+
+        if (change.action === "add" && !existing) {
+          runtime.dispatch({
+            type: "comment.add",
+            comment: {
+              commentId: entry.commentId,
+              status: entry.status,
+              anchor: entry.anchor as never,
+              createdAt: entry.createdAt,
+              createdBy: entry.createdBy,
+              authorId: entry.authorId,
+              body: entry.body,
+              entries: entry.entries,
+              warningIds: entry.warningIds,
+              isResolved: entry.status === "resolved",
+              metadata: { source: "runtime" },
+            },
+          });
+        } else if (change.action === "update" && existing) {
+          if (entry.status === "resolved" && existing.status !== "resolved") {
+            runtime.dispatch({
+              type: "comment.resolve",
+              commentId,
+              resolvedBy: entry.resolvedBy,
+            });
+          } else if (entry.status === "open" && existing.status === "resolved") {
+            runtime.dispatch({ type: "comment.reopen", commentId });
+          }
+
+          const localEntryCount = existing.entries.length;
+          if (entry.entries.length > localEntryCount) {
+            for (const newEntry of entry.entries.slice(localEntryCount)) {
+              runtime.dispatch({
+                type: "comment.add-reply",
+                commentId,
+                body: newEntry.body,
+                authorId: newEntry.authorId,
+              });
+            }
+          }
+        }
+      }
+    } finally {
+      suppressLocalEvents = false;
+    }
+  }
+
+  function onRevisionActionMapChange(event: Y.YMapEvent<YRevisionAction>): void {
+    suppressLocalEvents = true;
+    try {
+      for (const [, change] of event.changes.keys) {
+        if (change.action !== "add") continue;
+        const entries = [...yRevisionActions.entries()];
+        const latest = entries[entries.length - 1];
+        if (!latest) continue;
+        const entry = latest[1];
+        if (entry.sourceClientId === clientId) continue;
+
+        runtime.dispatch({
+          type: entry.action === "accept" ? "change.accept" : "change.reject",
+          changeId: entry.changeId,
+        });
+      }
+    } finally {
+      suppressLocalEvents = false;
+    }
+  }
+
+  yComments.observe(onCommentMapChange);
+  yRevisionActions.observe(onRevisionActionMapChange);
+
+  // --- Initial sync: push existing comments to Yjs if first client ----------
+
+  const snapshot = runtime.getRenderSnapshot();
+  if (yComments.size === 0 && snapshot.comments.threads.length > 0) {
+    ydoc.transact(() => {
+      for (const thread of snapshot.comments.threads) {
+        yComments.set(thread.commentId, {
+          commentId: thread.commentId,
+          status: thread.status,
+          anchor: thread.anchor,
+          createdAt: thread.createdAt,
+          createdBy: thread.createdBy,
+          authorId: thread.createdBy,
+          body: thread.entries[0]?.body ?? "",
+          entries: thread.entries.map((e) => ({
+            entryId: e.entryId,
+            authorId: e.authorId,
+            body: e.body,
+            createdAt: e.createdAt,
+          })),
+          resolvedAt: thread.resolvedAt,
+          resolvedBy: thread.resolvedBy,
+          warningIds: [],
+          sourceClientId: clientId,
+        });
+      }
+    });
+  }
+
+  return {
+    destroy() {
+      unsubEvents();
+      yComments.unobserve(onCommentMapChange);
+      yRevisionActions.unobserve(onRevisionActionMapChange);
+    },
+  };
+}
+
+function revisionActionKey(changeId: string, action: string): string {
+  return `${changeId}:${action}`;
+}

package/src/runtime/document-runtime.ts

@@ -3949,10 +3949,11 @@ function resolveSupportedFieldDisplay(
   if (!field.fieldFamily || !isSupportedFieldFamily(field.fieldFamily)) {
     return undefined;
   }
+  if (field.fieldFamily === "TOC") {
+    return undefined;
+  }
   if (!field.fieldTarget) {
-    return field.fieldFamily === "TOC"
-      ? undefined
-      : { displayText: "", refreshStatus: "unresolvable" };
+    return { displayText: "", refreshStatus: "unresolvable" };
   }
   if (field.fieldFamily === "REF") {
     const result = resolveRefFieldText(document, bookmarkMap, field.fieldTarget);

package/src/runtime/surface-projection.ts

@@ -1427,6 +1427,14 @@ function describePreservedInlinePreview(
     };
   }
 
+  if (/\b(?:w:)?br\b[^>]*\b(?:w:)?type="page"/u.test(payloadReference)) {
+    return {
+      label: "Page break",
+      detail: "Word page-break marker preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
   if (/\b(?:w:)?permStart\b/u.test(payloadReference)) {
     const editorGroup = /\bw:edGrp="([^"]+)"/u.exec(payloadReference)?.[1];
     return {

package/src/ui/WordReviewEditor.tsx

@@ -197,6 +197,7 @@ import {
   resolveChromePreset,
   resolveChromeVisibilityForPreset,
 } from "../ui-tailwind/chrome/chrome-preset-model.ts";
+import { createCollabReviewSync } from "../runtime/collab-review-sync.ts";
 
 export {
   __createFallbackRuntime,
@@ -615,6 +616,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
   function WordReviewEditor(props, ref) {
     const {
       currentUser,
+      ydoc,
+      awareness,
       hostAdapter,
       datastore,
       documentId,
@@ -982,6 +985,12 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       [activeReviewQueueItemId, activeRuntime, reviewQueueSnapshot],
     );
 
+    useEffect(() => {
+      if (!ydoc || !runtime) return;
+      const handle = createCollabReviewSync(ydoc, runtime);
+      return () => handle.destroy();
+    }, [ydoc, runtime]);
+
     useEffect(() => {
       runtimeViewStateSeedRef.current = {
         workspaceMode: viewState.workspaceMode,
@@ -2209,6 +2218,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       <EditorSurfaceController
         ref={surfaceRef}
         currentUser={currentUser}
+        ydoc={ydoc}
+        awareness={awareness}
         snapshot={snapshot}
         canonicalDocument={canonicalDocument}
         documentNavigation={documentNavigation}

package/src/ui/editor-surface-controller.tsx

@@ -23,6 +23,8 @@ import type { MediaPreviewDescriptor } from "../ui-tailwind/editor-surface/pm-st
 
 export interface EditorSurfaceControllerProps {
   currentUser: EditorUser;
+  ydoc?: import('yjs').Doc;
+  awareness?: import("y-protocols/awareness").Awareness;
   snapshot: RuntimeRenderSnapshot;
   canonicalDocument: CanonicalDocumentEnvelope;
   documentNavigation: DocumentNavigationSnapshot;

package/src/ui-tailwind/editor-surface/pm-collab-plugins.ts

@@ -0,0 +1,40 @@
+import { type Plugin } from "prosemirror-state";
+import { keymap } from "prosemirror-keymap";
+import { columnResizing, tableEditing } from "prosemirror-tables";
+import { yCursorPlugin, ySyncPlugin, yUndoPlugin, undo, redo } from "y-prosemirror";
+import type { Awareness } from "y-protocols/awareness";
+import type { Doc as YDoc } from "yjs";
+
+import {
+  createSelectionSyncPlugin,
+  type SelectionSyncCallbacks,
+} from "./pm-command-bridge";
+
+export interface CollabPluginOptions {
+  ydoc: YDoc;
+  awareness?: Awareness;
+  selectionCallbacks: SelectionSyncCallbacks;
+}
+
+export function createCollabPlugins(options: CollabPluginOptions): Plugin[] {
+  const yXmlFragment = options.ydoc.getXmlFragment("prosemirror");
+
+  const plugins: Plugin[] = [
+    ySyncPlugin(yXmlFragment),
+    yUndoPlugin(),
+    keymap({
+      "Mod-z": undo,
+      "Mod-y": redo,
+      "Shift-Mod-z": redo,
+    }),
+    createSelectionSyncPlugin(options.selectionCallbacks),
+    tableEditing(),
+    columnResizing(),
+  ];
+
+  if (options.awareness) {
+    plugins.splice(1, 0, yCursorPlugin(options.awareness));
+  }
+
+  return plugins;
+}

package/src/ui-tailwind/editor-surface/pm-command-bridge.ts

@@ -9,7 +9,13 @@ import {
 import { resolveSurfaceShortcut } from "../../ui/runtime-shortcut-dispatch";
 import type { PositionMap } from "./pm-position-map";
 
-export interface CommandBridgeCallbacks {
+export interface SelectionSyncCallbacks {
+  onSelectionChange: (selection: SelectionSnapshot) => void;
+  getPositionMap: () => PositionMap | null;
+  isSelectionSyncSuppressed?: () => boolean;
+}
+
+export interface CommandBridgeCallbacks extends SelectionSyncCallbacks {
   onInsertText: (text: string) => void;
   onDeleteBackward: () => void;
   onDeleteForward: () => void;
@@ -20,48 +26,20 @@ export interface CommandBridgeCallbacks {
   onUndo: () => void;
   onRedo: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => void;
-  onSelectionChange: (selection: SelectionSnapshot) => void;
-  getPositionMap: () => PositionMap | null;
-  isSelectionSyncSuppressed?: () => boolean;
 }
 
 const bridgeKey = new PluginKey("command-bridge");
 
-/**
- * Creates ProseMirror plugins that intercept user input and dispatch
- * runtime commands instead of letting PM mutate its own state.
- *
- * All doc-changing transactions are blocked. Only the explicit input
- * hooks below are allowed to trigger runtime commands.
- */
-export function createCommandBridgePlugins(
-  callbacks: CommandBridgeCallbacks,
-): Plugin[] {
-  let isComposing = false;
-
-  // Transaction filter: block ALL doc-changing transactions.
-  // The runtime is the sole authority for document mutations.
-  const filterPlugin = new Plugin({
-    key: bridgeKey,
-    filterTransaction(tr) {
-      // Allow selection-only and metadata-only transactions
-      if (!tr.docChanged) return true;
-      // Block doc changes — runtime handles mutations via callbacks
-      return false;
-    },
-  });
-
-  // Selection sync: when PM selection changes, notify the runtime.
-  const selectionPlugin = new Plugin({
+export function createSelectionSyncPlugin(
+  callbacks: SelectionSyncCallbacks,
+): Plugin {
+  return new Plugin({
     view() {
       return {
         update(view, prevState) {
           if (callbacks.isSelectionSyncSuppressed?.()) {
             return;
           }
-          if (isComposing) {
-            return;
-          }
           if (!view.state.selection.eq(prevState.selection)) {
             const posMap = callbacks.getPositionMap();
             if (!posMap) return;
@@ -84,6 +62,22 @@ export function createCommandBridgePlugins(
       };
     },
   });
+}
+
+export function createCommandBridgePlugins(
+  callbacks: CommandBridgeCallbacks,
+): Plugin[] {
+  let isComposing = false;
+
+  const filterPlugin = new Plugin({
+    key: bridgeKey,
+    filterTransaction(tr) {
+      if (!tr.docChanged) return true;
+      return false;
+    },
+  });
+
+  const selectionPlugin = createSelectionSyncPlugin(callbacks);
 
   // Text input hook: intercept typed characters.
   const inputPlugin = new Plugin({

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -309,11 +309,11 @@ export function buildDecorations(
       // This is the critical behavior: "hide tracked changes" must show
       // the document as if accepted, not show deleted text as kept text.
       if (markupDisplay === "clean" && rev.kind === "deletion") {
-        const pmFrom = positionMap.runtimeToPm(rev.from);
-        const pmTo = positionMap.runtimeToPm(rev.to);
-        if (pmFrom < pmTo) {
+        const cleanPmFrom = positionMap.runtimeToPm(rev.from);
+        const cleanPmTo = positionMap.runtimeToPm(rev.to);
+        if (cleanPmFrom < cleanPmTo) {
           decorations.push(
-            Decoration.inline(pmFrom, pmTo, {
+            Decoration.inline(cleanPmFrom, cleanPmTo, {
               class: "hidden",
               "data-revision-id": rev.revisionId,
             }),
@@ -322,13 +322,11 @@ export function buildDecorations(
         continue;
       }
 
-      // Skip visual styling when tracked changes display is off
-      if (!showTrackedChanges) continue;
-
       const pmFrom = positionMap.runtimeToPm(rev.from);
       const pmTo = positionMap.runtimeToPm(rev.to);
       if (pmFrom >= pmTo) continue;
 
+      // Suggestions styling is always shown regardless of showTrackedChanges toggle.
       if (suggestionsEnabled) {
         if (rev.kind === "insertion") {
           decorations.push(
@@ -366,6 +364,9 @@ export function buildDecorations(
         continue;
       }
 
+      // Skip normal markup styling when tracked changes display is off
+      if (!showTrackedChanges) continue;
+
       const cls = getRevisionHighlightClass(
         revisionModel,
         rev.from,

package/src/ui-tailwind/editor-surface/surface-build-keys.ts

@@ -37,6 +37,7 @@ export function createSurfaceDocumentBuildKey(input: {
 export function createSurfaceDecorationKey(input: {
   markupDisplay: string;
   showTrackedChanges: boolean;
+  suggestionsEnabled?: boolean;
   canEdit: boolean;
   activeCommentId?: string;
   activeRevisionId?: string;
@@ -51,6 +52,7 @@ export function createSurfaceDecorationKey(input: {
   return JSON.stringify({
     markupDisplay: input.markupDisplay,
     showTrackedChanges: input.showTrackedChanges,
+    suggestionsEnabled: input.suggestionsEnabled ?? false,
     canEdit: input.canEdit,
     activeCommentId: input.activeCommentId ?? null,
     activeRevisionId: input.activeRevisionId ?? null,