fix(super-editor): sync custom xml writes through part-sync (IT-1229) (#392)

* fix(super-editor): sync custom xml writes through part-sync

- metadata.* and customXml.parts.* writes routed through the parts
  mutation layer so partChanged fires and part-sync publishes
- a shared sandbox-and-diff wrapper commits every package path a custom
  xml create/update/remove touches (item, itemProps, item rels, document
  rels), not just the item xml
- two-client regression tests cover metadata attach and customXml
  create/patch/remove, including the remote client's converted xml

* fix(super-editor): record custom xml tombstones on remote part-sync deletes

Remote part deletions removed the part from convertedXml but never
populated removedCustomXmlPaths, so a collaborator whose original docx
contained the part re-emitted it on export. The consumer now records
tombstones for deleted custom xml storage parts, props parts, and item
rels (including rels-linked props paths), and clears stale tombstones
when a part is re-created remotely.

* fix(super-editor): tombstone absent custom xml parts on late-join and clear bibliography cache

- late joiners prune local custom xml parts absent from an authoritative
  parts map (a peer deleted them before this client joined), recording
  export tombstones through the same mutateParts mechanism hydration uses
- tombstoning a path now also invalidates converter caches, so deleting
  the bibliography storage part clears converter.bibliographyPart and
  export cannot resurrect it

* fix(super-editor): record hydration tombstones only after the prune mutation commits

Tombstones (and the bibliography cache clear) were applied before
mutateParts ran; a mutation failure rolled back the part store but left
the converter tombstoned. The prune now collects paths and records them
only after the mutation succeeds.

* fix(super-editor): clear stale custom xml tombstones during hydration

A client that tombstoned a custom xml part (e.g. deleted while offline)
and then rehydrated from an authoritative map containing the recreated
part kept the stale tombstone, so export dropped the recreated part.
Hydration now clears tombstones for present custom xml paths at the same
post-mutation point where absent paths are tombstoned - symmetric to the
live consumer path.

* fix(super-editor): invalidate bibliography cache on remote custom xml writes

Remote writes and hydration cleared stale tombstones but left the
bibliography cache pointing at the old content, so export rebuilt the
part from the stale cache over the collaborator's version. Written and
present custom xml paths now invalidate converter caches, and the part
path predicates agree on casing.

* fix(super-editor): clear hydration tombstones only for parts that hydrated

A key present in the authoritative map whose envelope failed to decode
never lands in convertedXml; clearing its tombstone would let export
copy the stale original zip entry through instead of dropping the part.

* ci: retrigger checks on current head

* fix(super-editor): scope hydration tombstone clearing to hydrated parts and make converter-state application rollback-safe

- hydration only clears a custom xml tombstone when the part actually
  hydrated this pass (a decode+op succeeded), not merely because a stale
  local copy is present; a failed-to-hydrate authoritative part no longer
  resurrects the stale local one on export
- applyConverterState is atomic and runs only after the part-store
  mutation durably commits, so a compound rollback cannot leave
  removedCustomXmlPaths / bibliographyPart mutated while the store is
  restored

* fix: address PR review comments on #392

* fix(super-editor): validate metadata payload before mutating on attach

metadata.attach serialized the payload only in the live path, inside the
part-sync sandbox that runs after the anchor is inserted. A non-serializable
payload (a BigInt or a cyclic object, neither of which the payload type can
rule out) therefore threw while building the envelope, after wrapRangeInAnchor
had already dispatched the anchor transaction, leaving an inline content
control with no matching customXml payload.

Build the envelope during the attach preview as well, so serialization fails
before the operation touches the document. Adds a regression test asserting a
cyclic payload throws without dispatching an anchor transaction.

* refactor(super-editor): serialize only the new entry in the attach preview

The attach preview rebuilt the whole metadata envelope to validate one payload,
re-serializing every existing entry in the namespace before the live path
serialized them again. Serialize just the new entry — existing entries were
already validated when they were written — so the preview stays a fail-fast
check for non-serializable payloads without the per-attach serialization cost.

* test(super-editor): fix concurrent-seed race in collaborator export test

The two-client export test created both collaborative editors on unsynced
ydocs, so both bootstrapped as a new room and both seeded the baseline
package into their parts maps as concurrent Yjs writes. The map-key conflict
on word/_rels/document.xml.rels is resolved by clientID, and with the wrong
random winner the second client's baseline seed discarded the first client's
published rels update, dropping the customXml document relationship from the
export (~50% failure rate; deterministically reproducible by pinning
clientIDs). Real clients receive room state before bootstrapping, see the
capability marker, and hydrate instead of seeding, so the conflict is an
artifact of the test's join order.

Create the second editor only after syncing the first editor's seeded state,
matching the real join flow, and wait for the received document rels content
(the baseline part always exists, so an existence check passed before the
remote update landed).

Ported-From-Source-Repo: superdoc/orbit
Ported-From-Source-Commit: 13119b74e8785850867256c4a8fffb06b41e73c3
Ported-Public-Prefix: superdoc/public

Author: caio-pizzol

packages/super-editor/src/editors/v1/core/super-converter/custom-xml-parts.js

@@ -610,7 +610,7 @@ export function removeCustomXmlPart(convertedXml, target, converter) {
   return true;
 }
 
-function invalidateConverterCachesForPath(converter, partName) {
+export function invalidateConverterCachesForPath(converter, partName) {
   if (!converter || typeof partName !== 'string') return;
   const biblio = converter.bibliographyPart;
   if (biblio && biblio.partPath === partName) {

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/anchored-metadata-export.integration.test.ts

@@ -1,4 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+import * as Y from 'yjs';
+import { Awareness } from 'y-protocols/awareness.js';
+import JSZip from 'jszip';
 import { initTestEditor, loadTestDataForEditorTests } from '@tests/helpers/helpers.js';
 
 function seedMetadataPart(
@@ -38,6 +41,58 @@ async function createEditorWithEmptyPackage() {
   return editor;
 }
 
+function createProviderStub(ydoc: Y.Doc) {
+  return {
+    synced: true,
+    isSynced: true,
+    on: vi.fn(),
+    off: vi.fn(),
+    disconnect: vi.fn(),
+    awareness: new Awareness(ydoc),
+  };
+}
+
+async function createCollaborativeEditorWithEmptyPackage(ydoc: Y.Doc) {
+  const docData = await loadTestDataForEditorTests('blank-doc.docx');
+  const { editor } = initTestEditor({
+    content: docData.docx,
+    media: docData.media,
+    mediaFiles: docData.mediaFiles,
+    fonts: docData.fonts,
+    ydoc,
+    collaborationProvider: createProviderStub(ydoc),
+    useImmediateSetTimeout: false,
+    isHeadless: true,
+    user: { name: 'Test', email: 'test@example.com' },
+  });
+  return editor;
+}
+
+function resolveBlockId(insertReceipt: unknown): string {
+  const receipt = insertReceipt as {
+    target?: { blockId?: unknown };
+    resolution?: { target?: { blockId?: unknown } };
+  };
+  const direct = receipt.target?.blockId;
+  if (typeof direct === 'string' && direct.length > 0) return direct;
+  const resolved = receipt.resolution?.target?.blockId;
+  if (typeof resolved === 'string' && resolved.length > 0) return resolved;
+  throw new Error('insert receipt did not include a blockId');
+}
+
+function convertedXml(editor: unknown): Record<string, unknown> {
+  return (editor as { converter: { convertedXml: Record<string, unknown> } }).converter.convertedXml;
+}
+
+function syncYDocs(source: Y.Doc, target: Y.Doc): void {
+  Y.applyUpdate(target, Y.encodeStateAsUpdate(source));
+}
+
+async function readZipPart(buffer: Uint8Array, path: string): Promise<string | undefined> {
+  const zip = await JSZip.loadAsync(buffer);
+  return zip.files[path]?.async('string');
+}
+
 describe('anchored metadata export filtering', () => {
   it('removes anchored-metadata entries from customXml when exporting final doc', async () => {
     const editor = await createEditorWithEmptyPackage();
@@ -73,4 +128,78 @@ describe('anchored metadata export filtering', () => {
       editor.destroy();
     }
   });
+
+  it('exports metadata customXml parts received from a collaborator', async () => {
+    const ydocA = new Y.Doc();
+    const ydocB = new Y.Doc();
+    const editorA = await createCollaborativeEditorWithEmptyPackage(ydocA);
+
+    await vi.waitFor(() => {
+      expect((editorA as unknown as { _partPublisher?: unknown })._partPublisher).toBeDefined();
+    });
+
+    // Model the real join order: A seeds the room first, then B receives that
+    // state BEFORE bootstrapping, so B hydrates instead of seeding. Creating
+    // both editors on unsynced ydocs makes both seed the same baseline keys as
+    // concurrent Yjs writes, and the map-key conflict is then resolved by
+    // clientID — with the wrong winner, B's baseline word/_rels/document.xml.rels
+    // silently discards A's published rels update.
+    syncYDocs(ydocA, ydocB);
+    const editorB = await createCollaborativeEditorWithEmptyPackage(ydocB);
+    const hostText = 'Alpha metadata target.';
+
+    try {
+      await vi.waitFor(() => {
+        expect((editorB as unknown as { _partPublisher?: unknown })._partPublisher).toBeDefined();
+      });
+
+      const inserted = await Promise.resolve(editorA.doc.insert({ value: hostText }));
+      const blockId = resolveBlockId(inserted);
+      const start = hostText.indexOf('metadata');
+      const end = start + 'metadata'.length;
+
+      const attached = editorA.doc.metadata.attach({
+        id: 'meta-export-sync',
+        namespace: 'urn:test:metadata-export-sync',
+        payload: { label: 'Remote export' },
+        target: {
+          kind: 'selection',
+          start: { kind: 'text', blockId, offset: start },
+          end: { kind: 'text', blockId, offset: end },
+        },
+      });
+      expect(attached.success).toBe(true);
+
+      syncYDocs(ydocA, ydocB);
+      await vi.waitFor(() => {
+        expect(convertedXml(editorB)['customXml/item1.xml']).toBeDefined();
+        expect(convertedXml(editorB)['customXml/itemProps1.xml']).toBeDefined();
+        expect(convertedXml(editorB)['customXml/_rels/item1.xml.rels']).toBeDefined();
+        // The baseline package already contains document.xml.rels, so checking
+        // mere existence would pass before the remote UPDATE lands — wait for
+        // the received rels content to reference the custom XML part.
+        expect(JSON.stringify(convertedXml(editorB)['word/_rels/document.xml.rels'])).toContain(
+          'relationships/customXml',
+        );
+      });
+
+      const exported = (await editorB.exportDocx({ getUpdatedDocs: false })) as Uint8Array;
+      const metadataXml = await readZipPart(exported, 'customXml/item1.xml');
+      const propsXml = await readZipPart(exported, 'customXml/itemProps1.xml');
+      const itemRelsXml = await readZipPart(exported, 'customXml/_rels/item1.xml.rels');
+      const documentRelsXml = await readZipPart(exported, 'word/_rels/document.xml.rels');
+
+      expect(metadataXml).toContain('meta-export-sync');
+      expect(metadataXml).toContain('Remote export');
+      expect(propsXml).toContain('datastoreItem');
+      expect(itemRelsXml).toContain('customXmlProps');
+      expect(documentRelsXml).toContain('relationships/customXml');
+      expect(documentRelsXml).toContain('../customXml/item1.xml');
+    } finally {
+      editorA.destroy();
+      editorB.destroy();
+      ydocA.destroy();
+      ydocB.destroy();
+    }
+  });
 });

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/anchored-metadata-wrappers.test.ts

@@ -288,6 +288,26 @@ describe('anchored metadata wrappers', () => {
     expect(metadataListWrapper(editor).total).toBe(0);
   });
 
+  it('rejects a non-serializable payload before mutating the document', () => {
+    const editor = makeEditor();
+
+    // A cyclic object cannot be represented in the JSON envelope and cannot be
+    // ruled out by the payload type. The preview must fail serialization before
+    // the live path inserts the SDT anchor; otherwise attach dispatches the
+    // anchor transaction and only then throws while building the envelope,
+    // leaving an anchor with no matching customXml payload.
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+
+    expect(() =>
+      metadataAttachWrapper(editor, { id: 'cyclic', target: TARGET, namespace: 'urn:test:metadata', payload: cyclic }),
+    ).toThrow();
+
+    // No anchor transaction was dispatched and no payload entry was written.
+    expect(editor.view!.dispatch).not.toHaveBeenCalled();
+    expect(metadataListWrapper(editor).total).toBe(0);
+  });
+
   it('attach dry-run throws REVISION_MISMATCH when expectedRevision is stale', () => {
     const editor = makeEditor();
 

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/anchored-metadata-wrappers.ts

@@ -41,6 +41,7 @@ import { findAllSdtNodes, SDT_INLINE_NAME } from '../helpers/content-controls/in
 import { executeOutOfBandMutation } from '../out-of-band-mutation.js';
 import { executeDomainCommand } from './plan-wrappers.js';
 import { checkRevision, getRevision } from './revision-tracker.js';
+import { mutateCustomXmlParts } from './custom-xml-part-mutation.js';
 
 type XmlNode = {
   type?: string;
@@ -394,56 +395,83 @@ function writeEntry(
   const convertedXml = getConvertedXml(editor);
   const converter = getConverter(editor);
   const existing = findPartByNamespace(convertedXml, namespace);
-  const entries = existing?.entries.filter((entry) => entry.id !== id) ?? [];
   const next: MetadataEntry = {
     id,
     namespace,
     partName: existing?.partName ?? predictPartName(convertedXml, converter),
     payload,
   };
-  const xml = buildEnvelopeXml(namespace, [...entries, next]);
 
   if (dryRun) {
+    // Serialize just the new entry during the preview so a non-serializable
+    // payload (BigInt, cyclic object) fails here, before the live path mutates
+    // the document. metadata.attach runs this preview before wrapRangeInAnchor;
+    // without it, the live path would insert the SDT anchor and only then throw
+    // while building the envelope, leaving an anchor with no customXml payload.
+    // Only the new entry needs checking: existing entries were validated when
+    // they were written, and the live path re-serializes the full envelope.
+    buildEnvelopeXml(namespace, [next]);
     return { partName: next.partName };
   }
 
-  if (existing) {
-    patchCustomXmlPart(
-      convertedXml,
-      { partName: existing.partName },
-      { content: xml, schemaRefs: undefined },
-      converter ?? undefined,
+  const partName = mutateCustomXmlParts(editor, 'metadata.writeEntry', (sandboxXml, sandboxConverter) => {
+    const sandboxExisting = findPartByNamespace(sandboxXml, namespace);
+    const sandboxEntries = sandboxExisting?.entries.filter((entry) => entry.id !== id) ?? [];
+    const sandboxNext: MetadataEntry = {
+      id,
+      namespace,
+      partName: sandboxExisting?.partName ?? predictPartName(sandboxXml, sandboxConverter),
+      payload,
+    };
+    const sandboxEnvelope = buildEnvelopeXml(namespace, [...sandboxEntries, sandboxNext]);
+
+    if (sandboxExisting) {
+      patchCustomXmlPart(
+        sandboxXml,
+        { partName: sandboxExisting.partName },
+        { content: sandboxEnvelope, schemaRefs: undefined },
+        sandboxConverter,
+      );
+      return sandboxExisting.partName;
+    }
+
+    const created = createCustomXmlPart(
+      sandboxXml,
+      { content: sandboxEnvelope, schemaRefs: undefined },
+      sandboxConverter,
     );
-    markConverterDirty(editor);
-    return { partName: existing.partName };
-  }
+    return created.partName;
+  });
 
-  const created = createCustomXmlPart(convertedXml, { content: xml, schemaRefs: undefined }, converter ?? undefined);
-  markConverterDirty(editor);
-  return { partName: created.partName };
+  return { partName };
 }
 
 function removeEntry(editor: Editor, id: string, dryRun: boolean): boolean {
   const convertedXml = getConvertedXml(editor);
-  const converter = getConverter(editor);
   const part = listMetadataParts(convertedXml).find((candidate) => candidate.entries.some((entry) => entry.id === id));
   if (!part) return false;
 
   if (dryRun) return true;
 
-  const remaining = part.entries.filter((entry) => entry.id !== id);
-  if (remaining.length === 0) {
-    removeCustomXmlPart(convertedXml, { partName: part.partName }, converter ?? undefined);
-  } else {
-    patchCustomXmlPart(
-      convertedXml,
-      { partName: part.partName },
-      { content: buildEnvelopeXml(part.namespace, remaining), schemaRefs: undefined },
-      converter ?? undefined,
+  return mutateCustomXmlParts(editor, 'metadata.removeEntry', (sandboxXml, sandboxConverter) => {
+    const sandboxPart = listMetadataParts(sandboxXml).find((candidate) =>
+      candidate.entries.some((entry) => entry.id === id),
     );
-  }
-  markConverterDirty(editor);
-  return true;
+    if (!sandboxPart) return false;
+
+    const remaining = sandboxPart.entries.filter((entry) => entry.id !== id);
+    if (remaining.length === 0) {
+      removeCustomXmlPart(sandboxXml, { partName: sandboxPart.partName }, sandboxConverter);
+    } else {
+      patchCustomXmlPart(
+        sandboxXml,
+        { partName: sandboxPart.partName },
+        { content: buildEnvelopeXml(sandboxPart.namespace, remaining), schemaRefs: undefined },
+        sandboxConverter,
+      );
+    }
+    return true;
+  });
 }
 
 function toSummary(entry: MetadataEntry, editor: Editor): AnchoredMetadataSummary {
@@ -619,7 +647,7 @@ export function metadataUpdateWrapper(
       if (!dryRun) {
         writeEntry(editor, existing.namespace, input.id, input.payload, false);
       }
-      return { changed: true, payload: { success: true, id: input.id } };
+      return { changed: false, payload: { success: true, id: input.id } };
     },
     { dryRun: options?.dryRun ?? false, expectedRevision: options?.expectedRevision },
   );
@@ -648,8 +676,8 @@ export function metadataRemoveWrapper(
     return executeOutOfBandMutation<AnchoredMetadataMutationResult>(
       editor,
       (dryRun) => {
-        const changed = removeEntry(editor, input.id, dryRun);
-        return { changed, payload: { success: true, id: input.id } };
+        removeEntry(editor, input.id, dryRun);
+        return { changed: false, payload: { success: true, id: input.id } };
       },
       { dryRun: false, expectedRevision: options?.expectedRevision },
     );