@beyondwork/docx-react-component 1.0.26-rc2 → 1.0.26

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.26rc2",
+  "version": "1.0.26",
   "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,30 @@
     "./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: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 +155,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,30 +181,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: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 =
   | {
@@ -1388,6 +1383,8 @@ export interface WordReviewEditorRef {
 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/core/selection/review-anchors.ts

@@ -104,6 +104,7 @@ export function rangeStaysWithinSingleParagraph(
 }
 
 export function canCreateDocxCommentAnchor(
+  content: unknown,
   anchor: ReviewAnchor,
 ): boolean {
   if (anchor.kind !== "range") {
@@ -111,7 +112,11 @@ export function canCreateDocxCommentAnchor(
   }
 
   const normalized = normalizeRange(anchor.range);
-  return normalized.from !== normalized.to;
+  if (normalized.from === normalized.to) {
+    return false;
+  }
+
+  return rangeStaysWithinSingleParagraph(content, normalized);
 }
 
 function readSurfaceBlocks(

package/src/io/export/serialize-comments.ts

@@ -261,25 +261,19 @@ export function serializeCommentAnchorsIntoDocumentXml(
       continue;
     }
 
-    const startParagraph = paragraphs.find(
+    const paragraph = paragraphs.find(
       (candidate) =>
         anchor.range.from >= candidate.start &&
-        anchor.range.from <= candidate.end,
-    );
-
-    const endParagraph = paragraphs.find(
-      (candidate) =>
-        anchor.range.to >= candidate.start &&
         anchor.range.to <= candidate.end,
     );
 
-    if (!startParagraph || !endParagraph) {
+    if (!paragraph) {
       skippedCommentIds.push(thread.commentId);
       continue;
     }
 
-    const startIndex = startParagraph.boundaries.get(anchor.range.from);
-    const endIndex = endParagraph.boundaries.get(anchor.range.to);
+    const startIndex = paragraph.boundaries.get(anchor.range.from);
+    const endIndex = paragraph.boundaries.get(anchor.range.to);
 
     if (startIndex === undefined || endIndex === undefined) {
       skippedCommentIds.push(thread.commentId);

package/src/review/store/comment-remapping.ts

@@ -4,6 +4,7 @@ import {
   getAnchorRange,
   mapReviewAnchor,
   mappingTouchesAnchorContent,
+  rangeStaysWithinSingleParagraph,
   type ReviewAnchor,
 } from "../../core/selection/review-anchors.ts";
 import type { TransactionMapping } from "../../core/selection/mapping.ts";
@@ -27,7 +28,7 @@ export function remapCommentThreads(
   const comments = Object.fromEntries(
     Object.entries(options.comments).map(([commentId, comment]) => [
       commentId,
-      remapCommentThread(comment, options.mapping),
+      remapCommentThread(comment, options.mapping, options.nextContent),
     ]),
   );
   const detachedCommentIds = Object.values(comments)
@@ -44,13 +45,14 @@ export function remapCommentThreads(
 export function remapCommentThread(
   comment: CommentThreadRecord,
   mapping: TransactionMapping,
+  nextContent: unknown,
 ): CommentThreadRecord {
   if (comment.anchor.kind === "detached") {
     return comment;
   }
 
   const mappedAnchor = mapReviewAnchor(comment.anchor, mapping);
-  const anchor = normalizeCommentAnchor(comment.anchor, mappedAnchor, mapping);
+  const anchor = normalizeCommentAnchor(comment.anchor, mappedAnchor, mapping, nextContent);
 
   return {
     ...comment,
@@ -62,6 +64,7 @@ function normalizeCommentAnchor(
   previousAnchor: ReviewAnchor,
   mappedAnchor: ReviewAnchor,
   mapping: TransactionMapping,
+  nextContent: unknown,
 ): ReviewAnchor {
   if (mappedAnchor.kind === "detached") {
     return mappedAnchor;
@@ -80,6 +83,13 @@ function normalizeCommentAnchor(
     return detachReviewAnchor(previousRange, detachReason(mapping));
   }
 
+  if (
+    mappedAnchor.kind === "range" &&
+    !rangeStaysWithinSingleParagraph(nextContent, mappedAnchor.range)
+  ) {
+    return detachReviewAnchor(previousRange, "invalidatedByStructureChange");
+  }
+
   return mappedAnchor;
 }
 

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

@@ -1160,9 +1160,9 @@ export function createDocumentRuntime(
       const selection = params.anchor
         ? createSelectionFromPublicAnchor(params.anchor)
         : state.selection;
-      if (!canCreateDocxCommentAnchor(anchor)) {
+      if (!canCreateDocxCommentAnchor(state.document.content, anchor)) {
         const message =
-          "DOCX comments must use a non-empty range.";
+          "DOCX comments must use a non-empty range that stays within a single paragraph.";
         emitError({
           errorId: createSessionId("comment-anchor", clock()),
           code: "validation_failed",

package/src/runtime/session-capabilities.ts

@@ -110,7 +110,7 @@ export function deriveCapabilities(
     activeStory.kind === "main" &&
     !snapshot.selection.isCollapsed &&
     Boolean(snapshot.surface) &&
-    canCreateDocxCommentAnchor(toRuntimeAnchor(snapshot.selection.activeRange));
+    canCreateDocxCommentAnchor(snapshot.surface, toRuntimeAnchor(snapshot.selection.activeRange));
   const canExport = isReady && !exportBlocked && !hasFatalError;
 
   // Revision capabilities

package/src/ui/WordReviewEditor.tsx

@@ -169,6 +169,7 @@ import {
 } from "./browser-export";
 import { EditorShellView } from "./editor-shell-view.tsx";
 import { EditorSurfaceController } from "./editor-surface-controller.tsx";
+import { createCollabReviewSync } from "../runtime/collab-review-sync.ts";
 
 export {
   __createFallbackRuntime,
@@ -503,6 +504,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
   function WordReviewEditor(props, ref) {
     const {
       currentUser,
+      ydoc,
+      awareness,
       hostAdapter,
       datastore,
       documentId,
@@ -698,6 +701,12 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       activeRuntime.setDocumentMode(suggestionsEnabled ? "suggesting" : "editing");
     }, [activeRuntime, suggestionsEnabled]);
 
+    useEffect(() => {
+      if (!ydoc || !runtime) return;
+      const handle = createCollabReviewSync(ydoc, runtime);
+      return () => handle.destroy();
+    }, [ydoc, runtime]);
+
     useEffect(() => {
       runtimeViewStateSeedRef.current = {
         workspaceMode: viewState.workspaceMode,
@@ -1705,6 +1714,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

@@ -20,6 +20,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 {
 } from "../../ui/headless/selection-helpers";
 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;
@@ -82,6 +60,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/tw-prosemirror-surface.tsx

@@ -39,6 +39,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 {
@@ -68,6 +70,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;
@@ -236,32 +240,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 => {
@@ -303,10 +321,14 @@ export const TwProseMirrorSurface = forwardRef<
     ],
   );
 
-  // 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;
     }
@@ -336,7 +358,6 @@ 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,
@@ -349,6 +370,15 @@ export const TwProseMirrorSurface = forwardRef<
       });
       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);
@@ -372,10 +402,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.
@@ -408,6 +440,7 @@ export const TwProseMirrorSurface = forwardRef<
   ]);
 
   useEffect(() => {
+    if (isCollabMode) return;
     const view = viewRef.current;
     const positionMap = positionMapRef.current;
     if (!view || !surface || !positionMap) {
@@ -429,7 +462,7 @@ export const TwProseMirrorSurface = forwardRef<
     queueMicrotask(() => {
       suppressSelectionEchoRef.current = false;
     });
-  }, [snapshot.selection, surface]);
+  }, [isCollabMode, snapshot.selection, surface]);
 
   useEffect(() => {
     if (!pendingSelectionProbeRef.current) {