@beyondwork/docx-react-component 1.0.8 → 1.0.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [
@@ -29,6 +29,18 @@
       "types": "./src/ui-tailwind/index.ts",
       "import": "./src/ui-tailwind/index.ts"
     },
+    "./api/public-types": {
+      "types": "./src/api/public-types.ts",
+      "import": "./src/api/public-types.ts"
+    },
+    "./io/docx-session": {
+      "types": "./src/io/docx-session.ts",
+      "import": "./src/io/docx-session.ts"
+    },
+    "./runtime/document-runtime": {
+      "types": "./src/runtime/document-runtime.ts",
+      "import": "./src/runtime/document-runtime.ts"
+    },
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css",
     "./package.json": "./package.json"
   },
@@ -78,7 +90,7 @@
     "tailwindcss": "^4.2.2"
   },
   "devDependencies": {
-    "@chllming/wave-orchestration": "^0.9.8",
+    "@chllming/wave-orchestration": "^0.9.12",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@typescript/native-preview": "7.0.0-dev.20260409.1",

package/src/api/public-types.ts

@@ -508,6 +508,7 @@ export interface WordReviewEditorRef {
   getWarnings(): EditorWarning[];
   getComments(): CommentSidebarSnapshot;
   getTrackedChanges(): TrackedChangesSnapshot;
+  scrollToRevision(revisionId: string): void;
 }
 
 export interface WordReviewEditorProps {

package/src/compare/diff-engine.ts

@@ -48,6 +48,7 @@ export interface CompareDocumentVersionsOptions {
 }
 
 interface BuildEntry {
+  changeId?: string;
   block: BlockNode;
   trackChange?: "insertion" | "deletion";
   tracked: boolean;
@@ -196,6 +197,7 @@ function addTrackedOrStructuralEntry(
   const text = getBlockDisplayText(block);
 
   buildEntries.push({
+    ...(tracked ? { changeId } : {}),
     block: cloned,
     ...(tracked ? { trackChange: direction } : {}),
     tracked,
@@ -243,7 +245,7 @@ function buildComparedDocument(
     if (entry.block.type === "paragraph") {
       if (entry.trackChange) {
         pendingRevisions.push({
-          changeId: `change-${pendingRevisions.length + 1}`,
+          changeId: entry.changeId ?? `change-${pendingRevisions.length + 1}`,
           kind: entry.trackChange,
           paragraphIndex,
         });
@@ -281,7 +283,7 @@ function buildComparedDocument(
       children: contentChildren,
     },
     review: {
-      comments: {},
+      comments: projectValue(target.review.comments),
       revisions,
     },
     preservation: mergePreservationStores(base.preservation, target.preservation),
@@ -321,15 +323,14 @@ function createParagraphRevisionRecords(
   }
 
   const entries: Array<[string, RevisionRecord]> = [];
-  pendingRevisions.forEach((revision, index) => {
+  pendingRevisions.forEach((revision) => {
     const position = positionByParagraphIndex.get(revision.paragraphIndex);
     if (position === undefined) {
       return;
     }
 
-    const changeId = `change-${index + 1}`;
     const record: RevisionRecord = {
-      changeId,
+      changeId: revision.changeId,
       kind: revision.kind,
       anchor: {
         kind: "range",
@@ -346,7 +347,7 @@ function createParagraphRevisionRecords(
           revision.kind === "insertion" ? "paragraph-insertion" : "paragraph-deletion",
       },
     };
-    entries.push([changeId, record]);
+    entries.push([revision.changeId, record]);
   });
   return Object.fromEntries(entries);
 }

package/src/compare/export-redlines.ts

@@ -5,6 +5,12 @@ import {
   serializeNumberingXml,
 } from "../io/export/serialize-numbering.ts";
 import { serializeRuntimeRevisionsIntoDocumentXml } from "../io/export/serialize-runtime-revisions.ts";
+import { splitDocumentAtReviewBoundaries } from "../io/export/split-review-boundaries.ts";
+import {
+  createCommentExportIdMap,
+  serializeCommentAnchorsIntoDocumentXml,
+  serializeMergedCommentsXml,
+} from "../io/export/serialize-comments.ts";
 import { createExportSession } from "../io/export/export-session.ts";
 import {
   DOCX_DOCUMENT_CONTENT_TYPE,
@@ -13,13 +19,34 @@ import {
 } from "../io/opc/docx-package.ts";
 import type { OpcPackage } from "../io/opc/package-reader.ts";
 import { readOpcPackage } from "../io/opc/package-reader.ts";
+import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
 import type { RevisionRecord as ReviewRevisionRecord } from "../review/store/revision-types.ts";
 import type { VersionCompareResult } from "./diff-engine.ts";
 
 const MAIN_DOCUMENT_PATH = "/word/document.xml";
 const NUMBERING_PART_PATH = "/word/numbering.xml";
+const COMMENTS_PART_PATH = "/word/comments.xml";
+const COMMENTS_EXTENDED_PART_PATH = "/word/commentsExtended.xml";
+const COMMENTS_IDS_PART_PATH = "/word/commentsIds.xml";
+const PEOPLE_PART_PATH = "/word/people.xml";
 const NUMBERING_RELATIONSHIP_TYPE =
   "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+const COMMENTS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+const COMMENTS_EXTENDED_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
+const COMMENTS_IDS_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds";
+const PEOPLE_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/people";
+const COMMENTS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
+const COMMENTS_EXTENDED_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
+const COMMENTS_IDS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
+const PEOPLE_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
 
 export interface ExportComparedDocumentOptions {
   fileName?: string;
@@ -46,15 +73,22 @@ export function exportComparedDocumentRedlines(
   const existingRelationships =
     sourcePackage.parts.get(MAIN_DOCUMENT_PATH)?.relationships ?? [];
 
+  const commentThreads = Object.values(
+    createCommentStoreFromRuntimeComments(result.comparedDocument.review.comments).threads,
+  );
+  const actionableRevisions = toReviewRevisionRecords(result.comparedDocument.review.revisions);
   const serialized = serializeMainDocument(
-    result.comparedDocument.content,
+    splitDocumentAtReviewBoundaries(
+      result.comparedDocument.content as never,
+      commentThreads,
+      actionableRevisions,
+    ) as never,
     result.comparedDocument.preservation,
     existingRelationships,
     {
       media: result.comparedDocument.media,
     },
   );
-  const actionableRevisions = toReviewRevisionRecords(result.comparedDocument.review.revisions);
   const revisionDocument = serializeRuntimeRevisionsIntoDocumentXml(
     serialized.documentXml,
     actionableRevisions,
@@ -65,23 +99,70 @@ export function exportComparedDocumentRedlines(
       `Compare export skipped ${revisionDocument.skippedRevisionIds.length} revision markers.`,
     );
   }
+  const exportCommentIds = createCommentExportIdMap(commentThreads);
+  const serializedComments = serializeMergedCommentsXml(commentThreads, {
+    exportCommentIds,
+  });
+  const annotatedDocument = serializeCommentAnchorsIntoDocumentXml(
+    revisionDocument.documentXml,
+    commentThreads,
+    undefined,
+    {
+      exportCommentIds,
+    },
+  );
+  if (annotatedDocument.skippedCommentIds.length > 0) {
+    throw new Error(
+      `Compare export skipped ${annotatedDocument.skippedCommentIds.length} comment anchors.`,
+    );
+  }
 
   const numberingXml = hasNumberingEntries(result.comparedDocument.numbering)
     ? serializeNumberingXml(result.comparedDocument.numbering)
     : undefined;
-  const relationships = withOptionalNumberingRelationship(
-    serialized.relationships,
+  const relationships = withOptionalRelatedPart(
+    withOptionalRelatedPart(
+      withOptionalRelatedPart(
+        withOptionalRelatedPart(
+          withOptionalRelatedPart(
+            serialized.relationships,
+            existingRelationships,
+            NUMBERING_RELATIONSHIP_TYPE,
+            "numbering.xml",
+            Boolean(numberingXml),
+          ),
+          existingRelationships,
+          COMMENTS_RELATIONSHIP_TYPE,
+          "comments.xml",
+          serializedComments.serializedCommentIds.length > 0,
+        ),
+        existingRelationships,
+        COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
+        "commentsExtended.xml",
+        Boolean(serializedComments.commentsExtendedXml),
+      ),
+      existingRelationships,
+      COMMENTS_IDS_RELATIONSHIP_TYPE,
+      "commentsIds.xml",
+      Boolean(serializedComments.commentsIdsXml),
+    ),
     existingRelationships,
-    Boolean(numberingXml),
+    PEOPLE_RELATIONSHIP_TYPE,
+    "people.xml",
+    Boolean(serializedComments.peopleXml),
   );
   const exportSession = createExportSession(sourcePackage, [
     MAIN_DOCUMENT_PATH,
     ...(numberingXml ? [NUMBERING_PART_PATH] : []),
+    ...(serializedComments.serializedCommentIds.length > 0 ? [COMMENTS_PART_PATH] : []),
+    ...(serializedComments.commentsExtendedXml ? [COMMENTS_EXTENDED_PART_PATH] : []),
+    ...(serializedComments.commentsIdsXml ? [COMMENTS_IDS_PART_PATH] : []),
+    ...(serializedComments.peopleXml ? [PEOPLE_PART_PATH] : []),
   ]);
 
   exportSession.replaceOwnedPart({
     path: MAIN_DOCUMENT_PATH,
-    bytes: new TextEncoder().encode(revisionDocument.documentXml),
+    bytes: new TextEncoder().encode(annotatedDocument.documentXml),
     contentType: DOCX_DOCUMENT_CONTENT_TYPE,
     relationships,
   });
@@ -95,6 +176,43 @@ export function exportComparedDocumentRedlines(
     });
   }
 
+  if (serializedComments.serializedCommentIds.length > 0) {
+    exportSession.replaceOwnedPart({
+      path: COMMENTS_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.commentsXml),
+      contentType:
+        sourcePackage.parts.get(COMMENTS_PART_PATH)?.contentType ?? COMMENTS_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.commentsExtendedXml) {
+    exportSession.replaceOwnedPart({
+      path: COMMENTS_EXTENDED_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.commentsExtendedXml),
+      contentType:
+        sourcePackage.parts.get(COMMENTS_EXTENDED_PART_PATH)?.contentType ??
+        COMMENTS_EXTENDED_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.commentsIdsXml) {
+    exportSession.replaceOwnedPart({
+      path: COMMENTS_IDS_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.commentsIdsXml),
+      contentType:
+        sourcePackage.parts.get(COMMENTS_IDS_PART_PATH)?.contentType ?? COMMENTS_IDS_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.peopleXml) {
+    exportSession.replaceOwnedPart({
+      path: PEOPLE_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.peopleXml),
+      contentType:
+        sourcePackage.parts.get(PEOPLE_PART_PATH)?.contentType ?? PEOPLE_CONTENT_TYPE,
+    });
+  }
+
   return {
     bytes: exportSession.serialize(),
     mimeType: DOCX_MIME_TYPE,
@@ -132,28 +250,30 @@ function hasNumberingEntries(
   );
 }
 
-function withOptionalNumberingRelationship(
+function withOptionalRelatedPart(
   relationships: readonly OpcRelationship[],
   existingRelationships: readonly OpcRelationship[],
-  includeNumbering: boolean,
+  relationshipType: string,
+  target: string,
+  includePart: boolean,
 ): OpcRelationship[] {
   const next = relationships.map((relationship) => ({ ...relationship }));
-  if (!includeNumbering) {
+  if (!includePart) {
     return next;
   }
 
-  const existing = next.find((relationship) => relationship.type === NUMBERING_RELATIONSHIP_TYPE);
+  const existing = next.find((relationship) => relationship.type === relationshipType);
   if (existing) {
     return next;
   }
 
   const fallbackId =
-    existingRelationships.find((relationship) => relationship.type === NUMBERING_RELATIONSHIP_TYPE)?.id ??
+    existingRelationships.find((relationship) => relationship.type === relationshipType)?.id ??
     `rId${next.length + 1}`;
   next.push({
     id: fallbackId,
-    type: NUMBERING_RELATIONSHIP_TYPE,
-    target: "numbering.xml",
+    type: relationshipType,
+    target,
     targetMode: "internal",
   });
   return next;

package/src/compare/snapshot.ts

@@ -20,6 +20,13 @@ export interface CreateDocumentVersionSnapshotOptions {
   createdAt?: string;
 }
 
+export function createDocumentVersionSnapshotId(
+  document: Pick<CanonicalDocument, "docId">,
+  name: string,
+): string {
+  return `${document.docId}:${name}`;
+}
+
 export function createDocumentVersionSnapshot(
   document: CanonicalDocument,
   options: CreateDocumentVersionSnapshotOptions,
@@ -27,7 +34,8 @@ export function createDocumentVersionSnapshot(
   const canonicalDocument = projectCanonicalDocument(document);
   return {
     snapshotVersion: "document-version-snapshot/1",
-    versionId: options.versionId ?? `${canonicalDocument.docId}:${options.name}`,
+    versionId:
+      options.versionId ?? createDocumentVersionSnapshotId(canonicalDocument, options.name),
     name: options.name,
     createdAt: options.createdAt ?? canonicalDocument.updatedAt,
     documentId: canonicalDocument.docId,
@@ -35,3 +43,24 @@ export function createDocumentVersionSnapshot(
     canonicalDocument,
   };
 }
+
+export function saveDocumentVersionSnapshot(
+  snapshots: readonly DocumentVersionSnapshot[],
+  snapshot: DocumentVersionSnapshot,
+): DocumentVersionSnapshot[] {
+  const next = snapshots.filter((entry) => entry.versionId !== snapshot.versionId);
+  next.push(snapshot);
+  return next.sort(compareDocumentVersionSnapshots);
+}
+
+function compareDocumentVersionSnapshots(
+  left: DocumentVersionSnapshot,
+  right: DocumentVersionSnapshot,
+): number {
+  const createdAtComparison = right.createdAt.localeCompare(left.createdAt);
+  if (createdAtComparison !== 0) {
+    return createdAtComparison;
+  }
+
+  return left.versionId.localeCompare(right.versionId);
+}

package/src/ui/WordReviewEditor.tsx

@@ -114,6 +114,16 @@ export function __createWordReviewEditorRefBridge(
     getWarnings: () => runtime.getWarnings(),
     getComments: () => runtime.getRenderSnapshot().comments,
     getTrackedChanges: () => runtime.getRenderSnapshot().trackedChanges,
+    scrollToRevision: (revisionId: string) => {
+      const revision = runtime.getRenderSnapshot().trackedChanges.revisions.find(
+        (r) => r.revisionId === revisionId,
+      );
+      if (!revision || revision.anchor.kind === "detached") return;
+      runtime.dispatch({
+        type: "selection.set",
+        selection: toRuntimeSelectionSnapshot(createSelectionFromAnchor(revision.anchor)),
+      });
+    },
   };
 }
 
@@ -500,6 +510,16 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         getWarnings: () => activeRuntime.getWarnings(),
         getComments: () => activeRuntime.getRenderSnapshot().comments,
         getTrackedChanges: () => activeRuntime.getRenderSnapshot().trackedChanges,
+        scrollToRevision: (revisionId: string) => {
+          const revision = activeRuntime.getRenderSnapshot().trackedChanges.revisions.find(
+            (r) => r.revisionId === revisionId,
+          );
+          if (!revision || revision.anchor.kind === "detached") return;
+          activeRuntime.dispatch({
+            type: "selection.set",
+            selection: toRuntimeSelectionSnapshot(createSelectionFromAnchor(revision.anchor)),
+          });
+        },
       }),
       [activeRuntime, currentUser.userId, documentId, runtime],
     );