feat(docx-io): add tracked changes and comments import/export

Add full round-trip support for DOCX tracked changes (suggestions) and
comments with threading. This enables import/export of Word documents
while preserving revision history and comment discussions.

Import pipeline:
- Custom mammoth.js fork emits [[DOCX_*:...]] tokens for ins/del/comments
- importTrackChanges.ts parses tokens, applies suggestion marks
- importComments.ts parses comment tokens, creates discussion structures
- importDocx.ts orchestrates full pipeline with token cleanup
- searchRange.ts provides text-based range finding for token placement

Export pipeline:
- exportTrackChanges.ts injects tracking tokens into serialized HTML
- exportComments.ts handles comment-specific OOXML generation
- html-to-docx enhanced with comments.xml, commentsExtended.xml,
  commentsIds.xml, commentsExtensible.xml, and people.xml generation
- Proper paraId threading for reply chains

App integration:
- import-toolbar-button.tsx: full DOCX import with user registration
- export-toolbar-button.tsx: export with discussions and suggestions
- suggestion-node-docx.tsx: DOCX-safe suggestion rendering (no ins/del)
- discussion-kit.tsx: paraId fields for round-trip fidelity
- docx-export-kit.tsx: SuggestionLeafDocx override for clean export

Key features:
- Suggestion authorship preserved through round-trip
- Comment threading via paraId/parentParaId linking
- UTC date handling for cross-timezone compatibility
- Overlapping comment ranges supported
- ImportedUser type for user store registration

Author: arthrod

apps/www/src/registry/components/editor/plugins/discussion-kit.tsx

@@ -13,6 +13,12 @@ export type TDiscussion = {
   isResolved: boolean;
   userId: string;
   documentContent?: string;
+  /** Direct author name from DOCX import (bypasses user lookup) */
+  authorName?: string;
+  /** Author initials from DOCX import */
+  authorInitials?: string;
+  /** OOXML paraId for round-trip DOCX threading fidelity */
+  paraId?: string;
 };
 
 const discussionsData: TDiscussion[] = [

apps/www/src/registry/components/editor/plugins/docx-export-kit.tsx

@@ -26,6 +26,7 @@ import {
   EquationElementDocx,
   InlineEquationElementDocx,
 } from '@/registry/ui/equation-node-static';
+import { SuggestionLeafDocx } from '@/registry/ui/suggestion-node-docx';
 import { TocElementDocx } from '@/registry/ui/toc-node-static';
 import { DocxExportPlugin } from '@platejs/docx-io';
 import { KEYS } from 'platejs';
@@ -40,6 +41,7 @@ import { KEYS } from 'platejs';
  * - Equations (inline font instead of KaTeX)
  * - Callouts (table layout for icon placement)
  * - TOC (anchor links with paragraph breaks)
+ * - Suggestions (<span> instead of <ins>/<del> to avoid unwanted formatting)
  *
  * Tables use base version with juice CSS inlining.
  */
@@ -56,6 +58,7 @@ export const DocxExportKit = [
         [KEYS.inlineEquation]: InlineEquationElementDocx,
         [KEYS.callout]: CalloutElementDocx,
         [KEYS.toc]: TocElementDocx,
+        [KEYS.suggestion]: SuggestionLeafDocx,
       },
     },
   }),

apps/www/src/registry/lib/discussion-ids.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'bun:test';
+
+import { getDiscussionCounterSeed } from './discussion-ids';
+
+describe('getDiscussionCounterSeed', () => {
+  it('returns 0 for empty list', () => {
+    expect(getDiscussionCounterSeed([])).toBe(0);
+  });
+
+  it('returns max suffix for contiguous ids', () => {
+    const discussions = [{ id: 'discussion1' }, { id: 'discussion2' }];
+    expect(getDiscussionCounterSeed(discussions)).toBe(2);
+  });
+
+  it('returns max suffix for non-contiguous ids', () => {
+    const discussions = [{ id: 'discussion1' }, { id: 'discussion3' }];
+    expect(getDiscussionCounterSeed(discussions)).toBe(3);
+  });
+
+  it('ignores non-matching ids', () => {
+    const discussions = [
+      { id: 'alpha1' },
+      { id: 'discussion' },
+      { id: 'discussion10x' },
+    ];
+    expect(getDiscussionCounterSeed(discussions)).toBe(0);
+  });
+
+  it('handles mixed ids and returns highest match', () => {
+    const discussions = [
+      { id: 'discussion2' },
+      { id: 'alpha1' },
+      { id: 'discussion12' },
+    ];
+    expect(getDiscussionCounterSeed(discussions)).toBe(12);
+  });
+});

apps/www/src/registry/lib/discussion-ids.ts

@@ -0,0 +1,18 @@
+export type DiscussionIdLike = {
+  id: string;
+};
+
+const discussionIdPattern = /^discussion(\d+)$/;
+
+export const getDiscussionCounterSeed = (
+  discussions: DiscussionIdLike[]
+): number =>
+  discussions.reduce((max, discussion) => {
+    const match = discussionIdPattern.exec(discussion.id);
+    if (!match) return max;
+
+    const value = Number(match[1]);
+    if (Number.isNaN(value)) return max;
+
+    return Math.max(max, value);
+  }, 0);

apps/www/src/registry/ui/block-discussion.tsx

@@ -4,7 +4,11 @@ import * as React from 'react';
 
 import type { PlateElementProps, RenderNodeWrapper } from 'platejs/react';
 
-import { getDraftCommentKey } from '@platejs/comment';
+import {
+  getCommentKeyId,
+  getCommentKeys,
+  getDraftCommentKey,
+} from '@platejs/comment';
 import { CommentPlugin } from '@platejs/comment/react';
 import { getTransientSuggestionKey } from '@platejs/suggestion';
 import { SuggestionPlugin } from '@platejs/suggestion/react';
@@ -316,31 +320,45 @@ const useResolvedDiscussion = (
 
   const discussions = usePluginOption(discussionPlugin, 'discussions');
 
+  const getLeafCommentIds = (leaf: TCommentText) =>
+    getCommentKeys(leaf)
+      .map(getCommentKeyId)
+      .filter((id): id is string => Boolean(id) && id !== 'draft');
+
+  const map = getOption('uniquePathMap');
+  const nextMap = new Map(map);
+  let mapChanged = false;
+
   commentNodes.forEach(([node]) => {
-    const id = api.comment.nodeId(node);
-    const map = getOption('uniquePathMap');
+    const ids = getLeafCommentIds(node);
+    if (ids.length === 0) return;
 
-    if (!id) return;
+    ids.forEach((id) => {
+      const previousPath = nextMap.get(id);
 
-    const previousPath = map.get(id);
+      // If there are no comment nodes in the corresponding path in the map, then update it.
+      if (PathApi.isPath(previousPath)) {
+        const nodes = api.comment.node({ id, at: previousPath });
 
-    // If there are no comment nodes in the corresponding path in the map, then update it.
-    if (PathApi.isPath(previousPath)) {
-      const nodes = api.comment.node({ id, at: previousPath });
+        if (!nodes) {
+          nextMap.set(id, blockPath);
+          mapChanged = true;
+        }
 
-      if (!nodes) {
-        setOption('uniquePathMap', new Map(map).set(id, blockPath));
         return;
       }
-
-      return;
-    }
-    // TODO: fix throw error
-    setOption('uniquePathMap', new Map(map).set(id, blockPath));
+      // TODO: fix throw error
+      nextMap.set(id, blockPath);
+      mapChanged = true;
+    });
   });
 
+  if (mapChanged) {
+    setOption('uniquePathMap', nextMap);
+  }
+
   const commentsIds = new Set(
-    commentNodes.map(([node]) => api.comment.nodeId(node)).filter(Boolean)
+    commentNodes.flatMap(([node]) => getLeafCommentIds(node))
   );
 
   const resolvedDiscussions = discussions

apps/www/src/registry/ui/comment.tsx

@@ -54,6 +54,14 @@ export type TComment = {
   discussionId: string;
   isEdited: boolean;
   userId: string;
+  /** Direct author name from DOCX import (bypasses user lookup) */
+  authorName?: string;
+  /** Author initials from DOCX import */
+  authorInitials?: string;
+  /** OOXML paraId for round-trip DOCX threading fidelity */
+  paraId?: string;
+  /** OOXML parentParaId for round-trip DOCX reply threading */
+  parentParaId?: string;
 };
 
 export function Comment(props: {
@@ -180,12 +188,19 @@ export function Comment(props: {
     >
       <div className="relative flex items-center">
         <Avatar className="size-5">
-          <AvatarImage alt={userInfo?.name} src={userInfo?.avatarUrl} />
-          <AvatarFallback>{userInfo?.name?.[0]}</AvatarFallback>
+          <AvatarImage
+            alt={comment.authorName ?? userInfo?.name}
+            src={userInfo?.avatarUrl}
+          />
+          <AvatarFallback>
+            {comment.authorInitials ??
+              comment.authorName?.[0] ??
+              userInfo?.name?.[0]}
+          </AvatarFallback>
         </Avatar>
         <h4 className="mx-2 font-semibold text-sm leading-none">
-          {/* Replace to your own backend or refer to potion */}
-          {userInfo?.name}
+          {/* Use direct author name from DOCX or fall back to user lookup */}
+          {comment.authorName ?? userInfo?.name}
         </h4>
 
         <div className="text-muted-foreground/80 text-xs leading-none">

apps/www/src/registry/ui/export-toolbar-button.tsx

@@ -4,7 +4,7 @@ import * as React from 'react';
 
 import type { DropdownMenuProps } from '@radix-ui/react-dropdown-menu';
 
-import { exportToDocx } from '@platejs/docx-io';
+import { exportToDocx, type DocxExportDiscussion } from '@platejs/docx-io';
 import { MarkdownPlugin } from '@platejs/markdown';
 import { ArrowDownToLineIcon } from 'lucide-react';
 import type { SlatePlugin } from 'platejs';
@@ -20,6 +20,7 @@ import {
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
 import { BaseEditorKit } from '@/registry/components/editor/editor-base-kit';
+import { discussionPlugin } from '@/registry/components/editor/plugins/discussion-kit';
 
 import { EditorStatic } from './editor-static';
 import { ToolbarButton } from './toolbar';
@@ -151,8 +152,43 @@ export function ExportToolbarButton(props: DropdownMenuProps) {
   };
 
   const exportToWord = async () => {
+    // Get discussions and users from the discussion plugin for comment export
+    const discussions = editor.getOption(discussionPlugin, 'discussions') ?? [];
+    const users = editor.getOption(discussionPlugin, 'users') ?? {};
+
+    // Resolve display name: prefer authorName (from DOCX import), fall back to users lookup
+    const resolveUser = (
+      userId: string,
+      authorName?: string
+    ): { id: string; name: string } | undefined => {
+      const name = authorName ?? users[userId]?.name;
+      return name ? { id: userId, name } : undefined;
+    };
+
+    // Convert discussions to export format
+    const exportDiscussions: DocxExportDiscussion[] = discussions.map((d) => ({
+      id: d.id,
+      comments: d.comments?.map((c) => ({
+        contentRich: c.contentRich,
+        createdAt: c.createdAt,
+        id: c.id,
+        paraId: c.paraId,
+        parentParaId: c.parentParaId,
+        userId: c.userId,
+        user: resolveUser(c.userId, c.authorName),
+      })),
+      createdAt: d.createdAt,
+      documentContent: d.documentContent,
+      paraId: d.paraId,
+      userId: d.userId,
+      user: resolveUser(d.userId, d.authorName),
+    }));
+
     const blob = await exportToDocx(editor.children, {
       editorPlugins: [...BaseEditorKit, ...DocxExportKit] as SlatePlugin[],
+      tracking: {
+        discussions: exportDiscussions,
+      },
     });
 
     const url = URL.createObjectURL(blob);

apps/www/src/registry/ui/import-toolbar-button.tsx

@@ -4,11 +4,14 @@ import * as React from 'react';
 
 import type { DropdownMenuProps } from '@radix-ui/react-dropdown-menu';
 
-import { importDocx } from '@platejs/docx-io';
+import { getCommentKey } from '@platejs/comment';
+import { importDocxWithTracking } from '@platejs/docx-io';
 import { MarkdownPlugin } from '@platejs/markdown';
+import { getSuggestionKey } from '@platejs/suggestion';
 import { ArrowUpToLineIcon } from 'lucide-react';
-import { getEditorDOMFromHtmlString } from 'platejs/static';
+import { KEYS, TextApi } from 'platejs';
 import { useEditorRef } from 'platejs/react';
+import { getEditorDOMFromHtmlString } from 'platejs/static';
 import { useFilePicker } from 'use-file-picker';
 
 import {
@@ -19,10 +22,18 @@ import {
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
 
+import { commentPlugin } from '@/registry/components/editor/plugins/comment-kit';
+import {
+  discussionPlugin,
+  type TDiscussion,
+} from '@/registry/components/editor/plugins/discussion-kit';
+import { getDiscussionCounterSeed } from '../lib/discussion-ids';
 import { ToolbarButton } from './toolbar';
 
 type ImportType = 'html' | 'markdown';
 
+const WHITESPACE_REGEX = /\s+/;
+
 export function ImportToolbarButton(props: DropdownMenuProps) {
   const editor = useEditorRef();
   const [open, setOpen] = React.useState(false);
@@ -73,9 +84,93 @@ export function ImportToolbarButton(props: DropdownMenuProps) {
     multiple: false,
     onFilesSelected: async ({ plainFiles }) => {
       const arrayBuffer = await plainFiles[0].arrayBuffer();
-      const result = await importDocx(editor, arrayBuffer);
 
-      editor.tf.insertNodes(result.nodes as typeof editor.children);
+      // Compute next discussion number to avoid ID collisions
+      const existingDiscussions =
+        editor.getOption(discussionPlugin, 'discussions') ?? [];
+      let discussionCounter = getDiscussionCounterSeed(existingDiscussions);
+
+      // Import with full tracking support (suggestions + comments)
+      const result = await importDocxWithTracking(editor as any, arrayBuffer, {
+        suggestionKey: KEYS.suggestion,
+        getSuggestionKey,
+        commentKey: KEYS.comment,
+        getCommentKey,
+        isText: TextApi.isText,
+        generateId: () => `discussion${++discussionCounter}`,
+      });
+
+      // Register imported users so suggestion/comment UI can resolve them
+      if (result.users.length > 0) {
+        const existingUsers = editor.getOption(discussionPlugin, 'users') ?? {};
+        const updatedUsers = { ...existingUsers };
+
+        for (const user of result.users) {
+          if (!updatedUsers[user.id]) {
+            updatedUsers[user.id] = {
+              id: user.id,
+              name: user.name,
+              avatarUrl: `https://api.dicebear.com/9.x/glass/svg?seed=${encodeURIComponent(user.name)}`,
+            };
+          }
+        }
+
+        editor.setOption(discussionPlugin, 'users', updatedUsers);
+      }
+
+      // Add imported discussions to the discussion plugin
+      if (result.discussions.length > 0) {
+        // Convert imported discussions to TDiscussion format
+        const newDiscussions: TDiscussion[] = result.discussions.map((d) => ({
+          id: d.id,
+          comments: (d.comments ?? []).map((c, index) => ({
+            id: c.id || `comment${index + 1}`,
+            contentRich:
+              c.contentRich as TDiscussion['comments'][number]['contentRich'],
+            createdAt: c.createdAt ?? new Date(),
+            discussionId: d.id,
+            isEdited: false,
+            userId: c.userId ?? c.user?.id ?? 'imported-unknown',
+            authorName: c.user?.name,
+            authorInitials: c.user?.name
+              ? c.user.name
+                  .split(WHITESPACE_REGEX)
+                  .slice(0, 2)
+                  .map((w) => w[0]?.toUpperCase() ?? '')
+                  .join('')
+              : undefined,
+            paraId: c.paraId,
+            parentParaId: c.parentParaId,
+          })),
+          createdAt: d.createdAt ?? new Date(),
+          documentContent: d.documentContent,
+          isResolved: false,
+          userId: d.userId ?? d.user?.id ?? 'imported-unknown',
+          authorName: d.user?.name,
+          authorInitials: d.user?.name
+            ? d.user.name
+                .split(WHITESPACE_REGEX)
+                .slice(0, 2)
+                .map((w) => w[0]?.toUpperCase() ?? '')
+                .join('')
+            : undefined,
+          paraId: d.paraId,
+        }));
+
+        // Replace all discussions (not append) because importDocxWithTracking
+        // replaces the entire editor content, making old discussions stale
+        editor.setOption(discussionPlugin, 'discussions', newDiscussions);
+        editor.setOption(commentPlugin, 'uniquePathMap', new Map());
+      }
+
+      // Log import results in dev only
+      if (
+        result.hasTracking &&
+        result.errors.length > 0 &&
+        process.env.NODE_ENV !== 'production'
+      ) {
+        console.warn('[DOCX Import] Errors:', result.errors);
+      }
     },
   });