@beyondwork/docx-react-component 1.0.32 → 1.0.34

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
+  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -88,6 +89,31 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  },
   "keywords": [
     "docx",
     "word",
@@ -130,7 +156,15 @@
     "prosemirror-view": "^1.41.7",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "tailwindcss": "^4.2.2"
+    "tailwindcss": "^4.2.2",
+    "yjs": "^13.6.0",
+    "y-prosemirror": "^1.2.0",
+    "y-protocols": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "yjs": { "optional": true },
+    "y-prosemirror": { "optional": true },
+    "y-protocols": { "optional": true }
   },
   "devDependencies": {
     "@chllming/wave-orchestration": "^0.9.15",
@@ -148,31 +182,19 @@
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "tsup": "^8.3.0",
-    "tsx": "^4.21.0"
+    "tsx": "^4.21.0",
+    "y-prosemirror": "^1.3.7",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.30"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ],
+    "overrides": {
+      "react": "19.2.4",
+      "react-dom": "19.2.4"
+    }
   }
-}
+}

package/src/api/public-types.ts

@@ -1,13 +1,8 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
-import type {
-  FieldFamily as FieldFamilyType,
-  FieldRefreshStatus as FieldRefreshStatusType,
-  SupportedFieldFamily as SupportedFieldFamilyType,
-} from "../model/canonical-document.ts";
 
-export type FieldFamily = FieldFamilyType;
-export type FieldRefreshStatus = FieldRefreshStatusType;
-export type SupportedFieldFamily = SupportedFieldFamilyType;
+export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
+export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
+export type SupportedFieldFamily = import("../model/canonical-document.ts").SupportedFieldFamily;
 
 export type ExternalDocumentSource =
   | {
@@ -1930,6 +1925,8 @@ export interface WordReviewEditorChromeOptions {
 export interface WordReviewEditorProps {
   documentId: string;
   currentUser: EditorUser;
+  ydoc?: import('yjs').Doc;
+  awareness?: import("y-protocols/awareness").Awareness;
   initialDocx?: Uint8Array | ArrayBuffer;
   initialSessionState?: EditorSessionState;
   initialSnapshot?: PersistedEditorSnapshot;

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/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

@@ -261,6 +261,7 @@ export function buildDecorations(
   revisionModel: RevisionDecorationModel | undefined,
   markupDisplay: MarkupDisplay,
   showTrackedChanges = true,
+  suggestionsEnabled = false,
   workflowScopes?: readonly WorkflowScope[],
   activeStory: EditorStoryTarget = MAIN_STORY_TARGET,
   workflowCandidates?: readonly WorkflowCandidateRange[],
@@ -324,6 +325,47 @@ export function buildDecorations(
       // 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;
+
+      if (suggestionsEnabled) {
+        if (rev.kind === "insertion") {
+          decorations.push(
+            Decoration.inline(pmFrom, pmTo, {
+              class: "text-insert",
+              "data-revision-id": rev.revisionId,
+            }),
+          );
+          decorations.push(
+            Decoration.widget(pmFrom, () => {
+              const el = document.createElement("span");
+              el.textContent = "[";
+              el.className = "text-insert";
+              el.setAttribute("contenteditable", "false");
+              return el;
+            }, { side: -1, key: `${rev.revisionId}-open` }),
+          );
+          decorations.push(
+            Decoration.widget(pmTo, () => {
+              const el = document.createElement("span");
+              el.textContent = "]";
+              el.className = "text-insert";
+              el.setAttribute("contenteditable", "false");
+              return el;
+            }, { side: 1, key: `${rev.revisionId}-close` }),
+          );
+        } else if (rev.kind === "deletion") {
+          decorations.push(
+            Decoration.inline(pmFrom, pmTo, {
+              class: "text-danger line-through decoration-danger/80 decoration-1",
+              "data-revision-id": rev.revisionId,
+            }),
+          );
+        }
+        continue;
+      }
+
       const cls = getRevisionHighlightClass(
         revisionModel,
         rev.from,
@@ -332,16 +374,12 @@ export function buildDecorations(
       );
       if (!cls) continue;
 
-      const pmFrom = positionMap.runtimeToPm(rev.from);
-      const pmTo = positionMap.runtimeToPm(rev.to);
-      if (pmFrom < pmTo) {
-        decorations.push(
-          Decoration.inline(pmFrom, pmTo, {
-            class: cls,
-            "data-revision-id": rev.revisionId,
-          }),
-        );
-      }
+      decorations.push(
+        Decoration.inline(pmFrom, pmTo, {
+          class: cls,
+          "data-revision-id": rev.revisionId,
+        }),
+      );
     }
   }
 

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -42,6 +42,8 @@ import {
   createCommandBridgePlugins,
   type CommandBridgeCallbacks,
 } from "./pm-command-bridge";
+import { createCollabPlugins } from "./pm-collab-plugins";
+import { prosemirrorToYXmlFragment } from "y-prosemirror";
 import { buildDecorations } from "./pm-decorations";
 import { createContextualInteractionPlugin } from "./pm-contextual-ui";
 import {
@@ -71,6 +73,8 @@ import type { MediaPreviewDescriptor } from "./pm-state-from-snapshot";
  */
 export interface TwProseMirrorSurfaceProps {
   currentUser: EditorUser;
+  ydoc?: import("yjs").Doc;
+  awareness?: import("y-protocols/awareness").Awareness;
   snapshot: RuntimeRenderSnapshot;
   canonicalDocument: CanonicalDocumentEnvelope;
   documentNavigation: DocumentNavigationSnapshot;
@@ -80,6 +84,7 @@ export interface TwProseMirrorSurfaceProps {
   activeRevisionId?: string;
   activeSelectionToolKind?: ActiveSelectionToolModel["kind"] | null;
   showTrackedChanges?: boolean;
+  suggestionsEnabled?: boolean;
   /** When true, the surface renders inside the page workspace (vs canvas). */
   isPageWorkspace?: boolean;
   onFocus: FocusEventHandler<HTMLDivElement>;
@@ -196,6 +201,7 @@ export const TwProseMirrorSurface = forwardRef<
     [snapshot.comments],
   );
   const showTrackedChanges = props.showTrackedChanges !== false;
+  const suggestionsEnabled = props.suggestionsEnabled ?? false;
   // Always create the revision model — needed for deletion hiding in clean mode
   // even when the tracked changes display toggle is off.
   const revisionModel = useMemo(
@@ -244,32 +250,46 @@ export const TwProseMirrorSurface = forwardRef<
     ],
   );
 
+  const isCollabMode = Boolean(props.ydoc);
+
   // Create PM plugins (stable across renders — callbacks accessed via ref)
   const plugins = useMemo(() => {
+    const selectionCallbacks = {
+      onSelectionChange: (sel: SelectionSnapshot) => callbacksRef.current?.onSelectionChange(sel),
+      getPositionMap: () => callbacksRef.current?.getPositionMap() ?? null,
+      isSelectionSyncSuppressed: () =>
+        callbacksRef.current?.isSelectionSyncSuppressed?.() ?? false,
+    };
+
+    const corePlugins = props.ydoc
+      ? createCollabPlugins({
+          ydoc: props.ydoc,
+          awareness: props.awareness,
+          selectionCallbacks,
+        })
+      : createCommandBridgePlugins({
+          ...selectionCallbacks,
+          onInsertText: (text) => callbacksRef.current?.onInsertText(text),
+          onDeleteBackward: () => callbacksRef.current?.onDeleteBackward(),
+          onDeleteForward: () => callbacksRef.current?.onDeleteForward(),
+          onSplitParagraph: () => callbacksRef.current?.onSplitParagraph(),
+          onInsertHardBreak: () => callbacksRef.current?.onInsertHardBreak(),
+          onInsertTab: () => callbacksRef.current?.onInsertTab(),
+          onOutdentTab: () => callbacksRef.current?.onOutdentTab?.(),
+          onUndo: () => callbacksRef.current?.onUndo(),
+          onRedo: () => callbacksRef.current?.onRedo(),
+          onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
+        });
+
     return [
-      ...createCommandBridgePlugins({
-        onInsertText: (text) => callbacksRef.current?.onInsertText(text),
-        onDeleteBackward: () => callbacksRef.current?.onDeleteBackward(),
-        onDeleteForward: () => callbacksRef.current?.onDeleteForward(),
-        onSplitParagraph: () => callbacksRef.current?.onSplitParagraph(),
-        onInsertHardBreak: () => callbacksRef.current?.onInsertHardBreak(),
-        onInsertTab: () => callbacksRef.current?.onInsertTab(),
-        onOutdentTab: () => callbacksRef.current?.onOutdentTab?.(),
-        onUndo: () => callbacksRef.current?.onUndo(),
-        onRedo: () => callbacksRef.current?.onRedo(),
-        onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
-        onSelectionChange: (sel) => callbacksRef.current?.onSelectionChange(sel),
-        getPositionMap: () => callbacksRef.current?.getPositionMap() ?? null,
-        isSelectionSyncSuppressed: () =>
-          callbacksRef.current?.isSelectionSyncSuppressed?.() ?? false,
-      }),
+      ...corePlugins,
       createContextualInteractionPlugin({
         onCommentActivated: (commentId) => props.onCommentActivated?.(commentId),
         onRevisionActivated: (revisionId) => props.onRevisionActivated?.(revisionId),
       }),
       createSearchPlugin(),
     ];
-  }, [props.onCommentActivated, props.onRevisionActivated]);
+  }, [props.onCommentActivated, props.onRevisionActivated, props.ydoc, props.awareness]);
 
   const applyDecorationProps = useCallback(
     (view: EditorView, positionMap: PositionMap): void => {
@@ -280,6 +300,7 @@ export const TwProseMirrorSurface = forwardRef<
         revisionModel,
         markupDisplay,
         showTrackedChanges,
+        suggestionsEnabled,
         props.workflowScopes,
         snapshot.activeStory,
         props.workflowCandidates,
@@ -311,13 +332,18 @@ export const TwProseMirrorSurface = forwardRef<
       props.workflowScopes,
       revisionModel,
       showTrackedChanges,
+      suggestionsEnabled,
     ],
   );
 
-  // Create or update the PM document only when the structural key changes.
   useEffect(() => {
     if (!mountRef.current || !surface) return;
 
+    // Collab mode: y-prosemirror owns the doc after initial mount
+    if (isCollabMode && viewRef.current) {
+      return;
+    }
+
     if (viewRef.current && documentBuildKeyRef.current === documentBuildKey) {
       return;
     }
@@ -337,6 +363,7 @@ export const TwProseMirrorSurface = forwardRef<
       revisionModel,
       markupDisplay,
       showTrackedChanges,
+      suggestionsEnabled,
       props.workflowScopes,
       snapshot.activeStory,
       props.workflowCandidates,
@@ -350,19 +377,23 @@ export const TwProseMirrorSurface = forwardRef<
     incrementInvalidationCounter("pm.laneA.rebuilds");
 
     if (!viewRef.current) {
-      // First time surface is available — create the EditorView
       const view = new EditorView(mountRef.current, {
         state,
         nodeViews: tableNodeViews,
         editable: () => canEdit,
         decorations: () => decorations,
-        dispatchTransaction(tr) {
-          const newState = view.state.apply(tr);
-          view.updateState(newState);
-        },
       });
       viewRef.current = view;
       recordPerfSample("pm.mount");
+
+      if (isCollabMode && props.ydoc) {
+        const yXmlFragment = props.ydoc.getXmlFragment("prosemirror");
+        if (yXmlFragment.length === 0) {
+          props.ydoc.transact(() => {
+            prosemirrorToYXmlFragment(view.state.doc, yXmlFragment);
+          });
+        }
+      }
     } else {
       suppressSelectionEchoRef.current = true;
       viewRef.current.updateState(state);
@@ -386,10 +417,12 @@ export const TwProseMirrorSurface = forwardRef<
   }, [
     applyDecorationProps,
     documentBuildKey,
+    isCollabMode,
     surface,
     snapshot.selection,
     plugins,
     props.mediaPreviews,
+    props.ydoc,
   ]);
 
   // Update decorations and editability without rebuilding the PM document.
@@ -422,6 +455,7 @@ export const TwProseMirrorSurface = forwardRef<
   ]);
 
   useEffect(() => {
+    if (isCollabMode) return;
     const view = viewRef.current;
     const positionMap = positionMapRef.current;
     if (!view || !surface || !positionMap) {
@@ -443,7 +477,7 @@ export const TwProseMirrorSurface = forwardRef<
     queueMicrotask(() => {
       suppressSelectionEchoRef.current = false;
     });
-  }, [snapshot.selection, surface]);
+  }, [isCollabMode, snapshot.selection, surface]);
 
   useEffect(() => {
     if (!pendingSelectionProbeRef.current) {