fix: extract duplicate block identity normalization from docxImporter

Author: harbournick

packages/super-editor/src/core/super-converter/v2/importer/docxImporter.js

@@ -32,6 +32,7 @@ import { ensureNumberingCache } from './numberingCache.js';
 import { commentRangeStartHandlerEntity, commentRangeEndHandlerEntity } from './commentRangeImporter.js';
 import { permStartHandlerEntity } from './permStartImporter.js';
 import { permEndHandlerEntity } from './permEndImporter.js';
+import { normalizeDuplicateBlockIdentitiesInContent } from './normalizeDuplicateBlockIdentitiesInContent.js';
 import bookmarkStartAttrConfigs from '@converter/v3/handlers/w/bookmark-start/attributes/index.js';
 import bookmarkEndAttrConfigs from '@converter/v3/handlers/w/bookmark-end/attributes/index.js';
 import { translator as wStylesTranslator } from '@converter/v3/handlers/w/styles/index.js';
@@ -169,6 +170,7 @@ export const createDocumentJson = (docx, converter, editor) => {
     parsedContent = filterOutRootInlineNodes(parsedContent);
     parsedContent = normalizeTableBookmarksInContent(parsedContent, editor);
     collapseWhitespaceNextToInlinePassthrough(parsedContent);
+    parsedContent = normalizeDuplicateBlockIdentitiesInContent(parsedContent);
 
     const result = {
       type: 'doc',
@@ -688,6 +690,7 @@ const importHeadersFooters = (docx, converter, mainEditor, numbering, translated
 
     // Safety: drop inline-only nodes at the root of header docs
     schema = filterOutRootInlineNodes(schema);
+    schema = normalizeDuplicateBlockIdentitiesInContent(schema);
 
     if (!converter.headerIds.ids) converter.headerIds.ids = [];
     converter.headerIds.ids.push(rId);
@@ -727,6 +730,7 @@ const importHeadersFooters = (docx, converter, mainEditor, numbering, translated
 
     // Safety: drop inline-only nodes at the root of footer docs
     schema = filterOutRootInlineNodes(schema);
+    schema = normalizeDuplicateBlockIdentitiesInContent(schema);
 
     if (!converter.footerIds.ids) converter.footerIds.ids = [];
     converter.footerIds.ids.push(rId);

packages/super-editor/src/core/super-converter/v2/importer/normalizeDuplicateBlockIdentitiesInContent.js

@@ -0,0 +1,86 @@
+import { generateDocxRandomId } from '@core/helpers/generateDocxRandomId.js';
+
+const PARAGRAPH_IDENTITY_ATTRS = ['sdBlockId', 'paraId'];
+const TABLE_IDENTITY_ATTRS = ['sdBlockId', 'paraId', 'blockId'];
+const DEFAULT_BLOCK_IDENTITY_ATTRS = ['sdBlockId', 'blockId', 'paraId'];
+
+/** Maps block node types to safe block-identity attribute lookup order. */
+const BLOCK_IDENTITY_ATTRS = {
+  paragraph: PARAGRAPH_IDENTITY_ATTRS,
+  heading: DEFAULT_BLOCK_IDENTITY_ATTRS,
+  listItem: DEFAULT_BLOCK_IDENTITY_ATTRS,
+  table: TABLE_IDENTITY_ATTRS,
+  tableRow: TABLE_IDENTITY_ATTRS,
+  tableCell: TABLE_IDENTITY_ATTRS,
+  tableHeader: TABLE_IDENTITY_ATTRS,
+  sdt: DEFAULT_BLOCK_IDENTITY_ATTRS,
+  structuredContentBlock: DEFAULT_BLOCK_IDENTITY_ATTRS,
+};
+
+function toIdentityValue(value) {
+  if (typeof value === 'string' && value.length > 0) return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+function resolvePrimaryBlockIdentity(node) {
+  if (!node || typeof node !== 'object') return undefined;
+
+  const attrPriority = BLOCK_IDENTITY_ATTRS[node.type];
+  if (!attrPriority) return undefined;
+
+  const attrs = typeof node.attrs === 'object' && node.attrs ? node.attrs : {};
+  for (const attr of attrPriority) {
+    const value = toIdentityValue(attrs[attr]);
+    if (value) return { id: value, source: attr };
+  }
+  return undefined;
+}
+
+function nextUniqueDocxId(usedIds) {
+  let id = generateDocxRandomId();
+  while (usedIds.has(id)) {
+    id = generateDocxRandomId();
+  }
+  return id;
+}
+
+function dedupeBlockIdentitiesInNode(node, usedIds) {
+  if (!node || typeof node !== 'object') return;
+
+  const identity = resolvePrimaryBlockIdentity(node);
+  if (identity) {
+    if (usedIds.has(identity.id)) {
+      const replacementId = nextUniqueDocxId(usedIds);
+      node.attrs = { ...node.attrs, [identity.source]: replacementId };
+      usedIds.add(replacementId);
+    } else {
+      usedIds.add(identity.id);
+    }
+  }
+
+  if (Array.isArray(node.content)) {
+    node.content.forEach((child) => dedupeBlockIdentitiesInNode(child, usedIds));
+  }
+}
+
+/**
+ * Deduplicate block identities during import so document-api targeting remains stable.
+ *
+ * Word files can occasionally contain duplicate stable block IDs across blocks.
+ * Since stable IDs are used for deterministic targeting in the adapters,
+ * duplicates break deterministic targeting and mutations.
+ *
+ * Only safe block identity attributes are rewritten: sdBlockId, paraId, and blockId.
+ *
+ * @param {Array<{type?: string, attrs?: Record<string, unknown>, content?: unknown[]}>} content
+ * @returns {Array<{type?: string, attrs?: Record<string, unknown>, content?: unknown[]}>}
+ */
+export function normalizeDuplicateBlockIdentitiesInContent(content = []) {
+  if (!Array.isArray(content) || content.length === 0) return content;
+
+  const usedIds = new Set();
+  content.forEach((node) => dedupeBlockIdentitiesInNode(node, usedIds));
+
+  return content;
+}

packages/super-editor/src/core/super-converter/v2/importer/normalizeDuplicateBlockIdentitiesInContent.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeDuplicateBlockIdentitiesInContent } from './normalizeDuplicateBlockIdentitiesInContent.js';
+
+describe('normalizeDuplicateBlockIdentitiesInContent', () => {
+  const paragraph = (attrs = {}, text = 'text') => ({
+    type: 'paragraph',
+    attrs,
+    marks: [],
+    content: [{ type: 'text', text, marks: [] }],
+  });
+
+  const table = (content = [], attrs = {}) => ({ type: 'table', attrs, marks: [], content });
+  const row = (content = [], attrs = {}) => ({ type: 'tableRow', attrs, marks: [], content });
+  const cell = (content = [], attrs = {}) => ({ type: 'tableCell', attrs, marks: [], content });
+  const image = (attrs = {}) => ({ type: 'image', attrs, marks: [] });
+
+  it('deduplicates duplicate paraId values while keeping the first occurrence unchanged', () => {
+    const content = [paragraph({ paraId: 'DUPLICATE' }, 'A'), paragraph({ paraId: 'DUPLICATE' }, 'B')];
+
+    normalizeDuplicateBlockIdentitiesInContent(content);
+
+    expect(content[0].attrs.paraId).toBe('DUPLICATE');
+    expect(content[1].attrs.paraId).not.toBe('DUPLICATE');
+    expect(content[1].attrs.paraId).toMatch(/^[0-9A-F]{8}$/);
+  });
+
+  it('rewrites the field that actually provided the identity (sdBlockId fallback for paragraph)', () => {
+    const content = [paragraph({ sdBlockId: 'SAME' }, 'A'), paragraph({ sdBlockId: 'SAME' }, 'B')];
+
+    normalizeDuplicateBlockIdentitiesInContent(content);
+
+    expect(content[0].attrs.sdBlockId).toBe('SAME');
+    expect(content[1].attrs.sdBlockId).not.toBe('SAME');
+    expect(content[1].attrs.sdBlockId).toMatch(/^[0-9A-F]{8}$/);
+    expect(content[1].attrs.paraId).toBeUndefined();
+  });
+
+  it('prioritizes sdBlockId over paraId when both are present on paragraphs', () => {
+    const content = [
+      paragraph({ paraId: 'P1', sdBlockId: 'SAME' }, 'A'),
+      paragraph({ paraId: 'P2', sdBlockId: 'SAME' }, 'B'),
+    ];
+
+    normalizeDuplicateBlockIdentitiesInContent(content);
+
+    expect(content[0].attrs.sdBlockId).toBe('SAME');
+    expect(content[1].attrs.sdBlockId).not.toBe('SAME');
+    expect(content[1].attrs.sdBlockId).toMatch(/^[0-9A-F]{8}$/);
+    expect(content[0].attrs.paraId).toBe('P1');
+    expect(content[1].attrs.paraId).toBe('P2');
+  });
+
+  it('deduplicates table blockId when paraId/sdBlockId are not present', () => {
+    const content = [table([], { blockId: 'TABLE-ID' }), table([], { blockId: 'TABLE-ID' })];
+
+    normalizeDuplicateBlockIdentitiesInContent(content);
+
+    expect(content[0].attrs.blockId).toBe('TABLE-ID');
+    expect(content[1].attrs.blockId).not.toBe('TABLE-ID');
+    expect(content[1].attrs.blockId).toMatch(/^[0-9A-F]{8}$/);
+  });
+
+  it('does not rewrite non-block identity fields (e.g. image attrs.id)', () => {
+    const content = [image({ id: '42', src: 'a.png' }), image({ id: '42', src: 'b.png' })];
+
+    normalizeDuplicateBlockIdentitiesInContent(content);
+
+    expect(content[0].attrs.id).toBe('42');
+    expect(content[1].attrs.id).toBe('42');
+  });
+
+  it('deduplicates identities across nested table block nodes', () => {
+    const content = [
+      table(
+        [
+          row(
+            [
+              cell([paragraph({ paraId: 'CELLPARA' }, 'R1C1')], { paraId: 'CELLID' }),
+              cell([paragraph({ paraId: 'CELLPARA' }, 'R1C2')], { paraId: 'CELLID' }),
+            ],
+            { paraId: 'ROWID' },
+          ),
+          row([cell([paragraph({ paraId: 'ROWID' }, 'R2C1')], { paraId: 'CELLID' })], { paraId: 'ROWID' }),
+        ],
+        { paraId: 'TABLEID' },
+      ),
+    ];
+
+    normalizeDuplicateBlockIdentitiesInContent(content);
+
+    const identities = new Set();
+    const duplicates = new Set();
+    const collect = (node) => {
+      if (!node || typeof node !== 'object') return;
+      const attrs = node.attrs ?? {};
+      const id =
+        (typeof attrs.paraId === 'string' && attrs.paraId) ||
+        (typeof attrs.sdBlockId === 'string' && attrs.sdBlockId) ||
+        (typeof attrs.blockId === 'string' && attrs.blockId) ||
+        (typeof attrs.id === 'string' && attrs.id) ||
+        (typeof attrs.uuid === 'string' && attrs.uuid);
+      if (id) {
+        if (identities.has(id)) duplicates.add(id);
+        identities.add(id);
+      }
+      if (Array.isArray(node.content)) node.content.forEach(collect);
+    };
+
+    content.forEach(collect);
+    expect(duplicates.size).toBe(0);
+  });
+});