feat: add header and footer diffing support (SD-2238)

examples/features/diffing/src/App.vue

@@ -259,19 +259,9 @@ const compareDocuments = async () => {
       createHeadlessEditor(rightFile.value),
     ]);
 
-    const leftDiff = leftEditor.commands.compareDocuments(
-      rightHeadless.state.doc,
-      rightHeadless.converter?.comments ?? [],
-      rightHeadless.converter?.translatedLinkedStyles ?? null,
-      rightHeadless.converter?.translatedNumbering ?? null,
-    );
-
-    const rightDiff = rightEditor.commands.compareDocuments(
-      leftHeadless.state.doc,
-      leftHeadless.converter?.comments ?? [],
-      leftHeadless.converter?.translatedLinkedStyles ?? null,
-      leftHeadless.converter?.translatedNumbering ?? null,
-    );
+    const leftDiff = leftEditor.commands.compareDocuments(rightHeadless);
+
+    const rightDiff = rightEditor.commands.compareDocuments(leftHeadless);
 
     leftEditor.commands.replayDifferences(leftDiff, { applyTrackedChanges: true });
     rightEditor.commands.replayDifferences(rightDiff, { applyTrackedChanges: true });

packages/document-api/src/contract/schemas.ts

@@ -609,7 +609,7 @@
 const trackedChangeAddressSchema = ref('TrackedChangeAddress');
 const entityAddressSchema = ref('EntityAddress');
 const selectionTargetSchema = ref('SelectionTarget');
 const targetLocatorSchema = ref('TargetLocator');
 const deleteBehaviorSchema = ref('DeleteBehavior');
 const resolvedHandleSchema = ref('ResolvedHandle');
 const pageInfoSchema = ref('PageInfo');
@@ -874,7 +874,7 @@
   text: { type: 'string' },
 });
 
 const nodeInfoSchema: JsonSchema = {
   type: 'object',
   required: ['nodeType', 'kind'],
   properties: {
@@ -890,7 +890,7 @@
   additionalProperties: false,
 };
 
 const matchContextSchema = objectSchema(
   {
     address: nodeAddressSchema,
     snippet: { type: 'string' },
@@ -901,7 +901,7 @@
   ['address', 'snippet', 'highlightRange'],
 );
 
 const unknownNodeDiagnosticSchema = objectSchema(
   {
     message: { type: 'string' },
     address: nodeAddressSchema,
@@ -2777,26 +2777,31 @@
     comments: { type: 'boolean' },
     styles: { type: 'boolean' },
     numbering: { type: 'boolean' },
-    headerFooters: { type: 'boolean', const: false },
+    headerFooters: { type: 'boolean' },
   },
   ['body', 'comments', 'styles', 'numbering', 'headerFooters'],
 );
 
 const diffSummarySchema: JsonSchema = objectSchema(
   {
     hasChanges: { type: 'boolean' },
-    changedComponents: { type: 'array', items: { type: 'string', enum: ['body', 'comments', 'styles', 'numbering'] } },
+    changedComponents: {
+      type: 'array',
+      items: { type: 'string', enum: ['body', 'comments', 'styles', 'numbering', 'headerFooters', 'parts'] },
+    },
     body: objectSchema({ hasChanges: { type: 'boolean' } }, ['hasChanges']),
     comments: objectSchema({ hasChanges: { type: 'boolean' } }, ['hasChanges']),
     styles: objectSchema({ hasChanges: { type: 'boolean' } }, ['hasChanges']),
     numbering: objectSchema({ hasChanges: { type: 'boolean' } }, ['hasChanges']),
+    headerFooters: objectSchema({ hasChanges: { type: 'boolean' } }, ['hasChanges']),
+    parts: objectSchema({ hasChanges: { type: 'boolean' } }, ['hasChanges']),
   },
-  ['hasChanges', 'changedComponents', 'body', 'comments', 'styles', 'numbering'],
+  ['hasChanges', 'changedComponents', 'body', 'comments', 'styles', 'numbering', 'headerFooters', 'parts'],
 );
 
 const diffSnapshotSchema: JsonSchema = objectSchema(
   {
-    version: { type: 'string', const: 'sd-diff-snapshot/v1' },
+    version: { type: 'string', enum: ['sd-diff-snapshot/v1', 'sd-diff-snapshot/v2'] },
     engine: { type: 'string', enum: ['super-editor'] },
     fingerprint: { type: 'string' },
     coverage: diffCoverageSchema,
@@ -2807,7 +2812,7 @@
 
 const diffPayloadSchema: JsonSchema = objectSchema(
   {
-    version: { type: 'string', const: 'sd-diff-payload/v1' },
+    version: { type: 'string', enum: ['sd-diff-payload/v1', 'sd-diff-payload/v2'] },
     engine: { type: 'string', enum: ['super-editor'] },
     baseFingerprint: { type: 'string' },
     targetFingerprint: { type: 'string' },

packages/document-api/src/diff/diff.ts

@@ -19,8 +19,8 @@ import type {
 // Constants
 // ---------------------------------------------------------------------------
 
-const SNAPSHOT_VERSION = 'sd-diff-snapshot/v1';
-const PAYLOAD_VERSION = 'sd-diff-payload/v1';
+const SNAPSHOT_VERSIONS = new Set(['sd-diff-snapshot/v1', 'sd-diff-snapshot/v2']);
+const PAYLOAD_VERSIONS = new Set(['sd-diff-payload/v1', 'sd-diff-payload/v2']);
 
 // ---------------------------------------------------------------------------
 // Adapter interface — implemented by each engine
@@ -54,10 +54,10 @@ function validateSnapshotWrapper(snapshot: unknown): asserts snapshot is DiffSna
   if (!isRecord(snapshot)) {
     throw new DocumentApiValidationError('INVALID_INPUT', 'targetSnapshot must be a DiffSnapshot object.');
   }
-  if (snapshot.version !== SNAPSHOT_VERSION) {
+  if (!SNAPSHOT_VERSIONS.has(String(snapshot.version))) {
     throw new DocumentApiValidationError(
       'CAPABILITY_UNSUPPORTED',
-      `Unsupported snapshot version "${String(snapshot.version)}". Expected "${SNAPSHOT_VERSION}".`,
+      `Unsupported snapshot version "${String(snapshot.version)}". Expected one of "${[...SNAPSHOT_VERSIONS].join('", "')}".`,
     );
   }
   if (typeof snapshot.engine !== 'string') {
@@ -78,10 +78,10 @@ function validateDiffPayloadWrapper(diff: unknown): asserts diff is DiffPayload
   if (!isRecord(diff)) {
     throw new DocumentApiValidationError('INVALID_INPUT', 'diff must be a DiffPayload object.');
   }
-  if (diff.version !== PAYLOAD_VERSION) {
+  if (!PAYLOAD_VERSIONS.has(String(diff.version))) {
     throw new DocumentApiValidationError(
       'CAPABILITY_UNSUPPORTED',
-      `Unsupported diff version "${String(diff.version)}". Expected "${PAYLOAD_VERSION}".`,
+      `Unsupported diff version "${String(diff.version)}". Expected one of "${[...PAYLOAD_VERSIONS].join('", "')}".`,
     );
   }
   if (typeof diff.engine !== 'string') {

packages/document-api/src/diff/diff.types.ts

@@ -23,7 +23,7 @@ export interface DiffCoverage {
   comments: boolean;
   styles: boolean;
   numbering: boolean;
-  headerFooters: false;
+  headerFooters: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -32,7 +32,7 @@ export interface DiffCoverage {
 
 /** Versioned, fingerprinted snapshot of a document's diffable state. */
 export interface DiffSnapshot {
-  version: 'sd-diff-snapshot/v1';
+  version: 'sd-diff-snapshot/v1' | 'sd-diff-snapshot/v2';
   engine: DiffEngineId;
   fingerprint: string;
   coverage: DiffCoverage;
@@ -47,16 +47,18 @@ export interface DiffSnapshot {
 /** Coarse change summary for a diff payload. */
 export interface DiffSummary {
   hasChanges: boolean;
-  changedComponents: Array<'body' | 'comments' | 'styles' | 'numbering'>;
+  changedComponents: Array<'body' | 'comments' | 'styles' | 'numbering' | 'headerFooters' | 'parts'>;
   body: { hasChanges: boolean };
   comments: { hasChanges: boolean };
   styles: { hasChanges: boolean };
   numbering: { hasChanges: boolean };
+  headerFooters: { hasChanges: boolean };
+  parts: { hasChanges: boolean };
 }
 
 /** Versioned diff payload describing changes from a base to a target document. */
 export interface DiffPayload {
-  version: 'sd-diff-payload/v1';
+  version: 'sd-diff-payload/v1' | 'sd-diff-payload/v2';
   engine: DiffEngineId;
   baseFingerprint: string;
   targetFingerprint: string;

packages/super-editor/src/core/Editor.lifecycle.test.ts

@@ -199,6 +199,46 @@ describe('Editor Lifecycle API', () => {
         await editor.open(undefined, getBlankDocOptions());
         expect(editor.lifecycleState).toBe('ready');
       });
+
+      it('isolates extension storage across editors created from the same extension list', async () => {
+        const sharedExtensions = getStarterExtensions();
+        const editorA = createTestEditor({ extensions: sharedExtensions });
+        const editorB = createTestEditor({ extensions: sharedExtensions });
+
+        try {
+          await editorA.open(undefined, getBlankDocOptions());
+          await editorB.open(undefined, getBlankDocOptions());
+
+          editorA.storage.image.media = {
+            ...editorA.storage.image.media,
+            'word/media/image1.png': 'base64-image-a',
+          };
+
+          editorB.storage.image.media = {
+            ...editorB.storage.image.media,
+            'word/media/image2.png': 'base64-image-b',
+          };
+
+          expect(editorA.storage.image.media).not.toBe(editorB.storage.image.media);
+
+          editorB.destroy();
+
+          expect(editorA.storage.image.media['word/media/image1.png']).toBe('base64-image-a');
+        } finally {
+          if (!editorA.isDestroyed) {
+            if (editorA.lifecycleState === 'ready') {
+              editorA.close();
+            }
+            editorA.destroy();
+          }
+          if (!editorB.isDestroyed) {
+            if (editorB.lifecycleState === 'ready') {
+              editorB.close();
+            }
+            editorB.destroy();
+          }
+        }
+      });
     });
 
     describe('Source Types', () => {

packages/super-editor/src/core/Editor.ts

@@ -97,6 +97,29 @@ const PIXELS_PER_INCH = 96;
 const MAX_HEIGHT_BUFFER_PX = 50;
 const MAX_WIDTH_BUFFER_PX = 20;
 
+type ExtensionInstanceLike = {
+  type?: string;
+  config?: Record<string, unknown>;
+};
+
+const cloneExtensionInstance = <T>(extension: T): T => {
+  const extensionLike = extension as ExtensionInstanceLike & {
+    constructor?: new (config: Record<string, unknown>) => unknown;
+  };
+  const config = extensionLike?.config;
+  const ExtensionCtor = extensionLike?.constructor;
+
+  if (!config || typeof config !== 'object' || typeof ExtensionCtor !== 'function') {
+    return extension;
+  }
+
+  try {
+    return new ExtensionCtor(config) as T;
+  } catch {
+    return extension;
+  }
+};
+
 /**
  * Given a table cell node, returns the total cell content width in pixels.
  * Sums all colwidth values and subtracts left/right cell margins (padding).
@@ -2003,12 +2026,16 @@ export class Editor extends EventEmitter<EditorEventMap> {
     ];
     const externalExtensions = this.options.externalExtensions || [];
 
-    const allExtensions = [...coreExtensions, ...this.options.extensions!].filter((extension) => {
-      const extensionType = typeof extension?.type === 'string' ? extension.type : undefined;
-      return extensionType ? allowedExtensions.includes(extensionType) : false;
-    });
+    const allExtensions = [...coreExtensions, ...this.options.extensions!]
+      .filter((extension) => {
+        const extensionType = typeof extension?.type === 'string' ? extension.type : undefined;
+        return extensionType ? allowedExtensions.includes(extensionType) : false;
+      })
+      .map((extension) => cloneExtensionInstance(extension));
+
+    const isolatedExternalExtensions = externalExtensions.map((extension) => cloneExtensionInstance(extension));
 
-    this.extensionService = ExtensionService.create(allExtensions, externalExtensions, this);
+    this.extensionService = ExtensionService.create(allExtensions, isolatedExternalExtensions, this);
   }
 
   /**

packages/super-editor/src/core/super-converter/helpers.d.ts

@@ -66,4 +66,5 @@ export function hasSomeParentWithClass(element: any, classname: any): any;
 export function getTextIndentExportValue(indent: string | number): number;
 export function polygonUnitsToPixels(pu: any): number;
 export function pixelsToPolygonUnits(pixels: any): number;
+export function resolveOpcTargetPath(target: string, baseDir?: string): string | null;
 //# sourceMappingURL=helpers.d.ts.map

packages/super-editor/src/document-api-adapters/diff-adapter.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { Editor } from '@core/Editor.js';
+import { BLANK_DOCX_BASE64 } from '@core/blank-docx.js';
+import { getStarterExtensions } from '@extensions/index.js';
+import { captureSnapshot, compareToSnapshot } from '@extensions/diffing/service/index.ts';
+import { createDiffAdapter } from './diff-adapter.ts';
+
+const TEST_USER = { name: 'Test User', email: 'test@example.com' };
+
+async function openBlankEditor(text: string): Promise<Editor> {
+  const editor = await Editor.open(Buffer.from(BLANK_DOCX_BASE64, 'base64'), {
+    isHeadless: true,
+    extensions: getStarterExtensions(),
+    user: TEST_USER,
+  });
+  editor.dispatch(editor.state.tr.insertText(text, 1));
+  return editor;
+}
+
+function createHeaderFooterDoc(editor: Editor, text: string): Record<string, unknown> {
+  const paragraph = editor.schema.nodes.paragraph.create(
+    undefined,
+    editor.schema.nodes.run.create(undefined, text ? [editor.schema.text(text)] : []),
+  );
+  return editor.schema.nodes.doc.create(undefined, [paragraph]).toJSON() as Record<string, unknown>;
+}
+
+function seedHeader(editor: Editor, refId: string, partPath: string, text: string): void {
+  const converter = editor.converter!;
+  const headers = (converter.headers ??= {});
+  headers[refId] = createHeaderFooterDoc(editor, text);
+
+  const headerIds = (converter.headerIds ??= {}) as { ids?: string[]; default?: string | null };
+  if (!Array.isArray(headerIds.ids)) headerIds.ids = [];
+  if (!headerIds.ids.includes(refId)) headerIds.ids.push(refId);
+
+  const relsPart = (converter.convertedXml!['word/_rels/document.xml.rels'] ??= {
+    type: 'element',
+    name: 'document',
+    elements: [],
+  }) as { elements?: Array<{ name?: string; attributes?: Record<string, string>; elements?: unknown[] }> };
+  if (!relsPart.elements) relsPart.elements = [];
+
+  let relsRoot = relsPart.elements.find((e) => e.name === 'Relationships');
+  if (!relsRoot) {
+    relsRoot = {
+      name: 'Relationships',
+      attributes: { xmlns: 'http://schemas.openxmlformats.org/package/2006/relationships' },
+      elements: [],
+    };
+    relsPart.elements.push(relsRoot);
+  }
+  if (!relsRoot.elements) relsRoot.elements = [];
+
+  relsRoot.elements.push({
+    name: 'Relationship',
+    attributes: {
+      Id: refId,
+      Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/header',
+      Target: partPath.replace(/^word\//, ''),
+    },
+    elements: [],
+  });
+
+  const sectPrElements: Array<Record<string, unknown>> = [
+    { type: 'element', name: 'w:pgSz', attributes: { 'w:w': '12240', 'w:h': '15840' } },
+    {
+      type: 'element',
+      name: 'w:pgMar',
+      attributes: {
+        'w:top': '1440',
+        'w:right': '1440',
+        'w:bottom': '1440',
+        'w:left': '1440',
+        'w:header': '708',
+        'w:footer': '708',
+        'w:gutter': '0',
+      },
+    },
+    { type: 'element', name: 'w:headerReference', attributes: { 'w:type': 'default', 'r:id': refId }, elements: [] },
+  ];
+  converter.bodySectPr = { type: 'element', name: 'w:sectPr', elements: sectPrElements };
+}
+
+describe('createDiffAdapter', () => {
+  it('dispatches transaction for header-only diffs when document body is unchanged', async () => {
+    const baseEditor = await openBlankEditor('Same body text.');
+    const targetEditor = await openBlankEditor('Same body text.');
+
+    try {
+      seedHeader(targetEditor, 'rIdHeader1', 'word/header1.xml', 'New header content');
+
+      const snapshot = captureSnapshot(targetEditor);
+      const diff = compareToSnapshot(baseEditor, snapshot);
+
+      expect(diff.summary.body.hasChanges).toBe(false);
+      expect(diff.summary.headerFooters.hasChanges).toBe(true);
+
+      const dispatchSpy = vi.spyOn(baseEditor, 'dispatch');
+      const adapter = createDiffAdapter(baseEditor);
+      const result = adapter.apply({ diff }, { changeMode: 'direct' });
+
+      expect(result.appliedOperations).toBeGreaterThan(0);
+      expect(dispatchSpy).toHaveBeenCalledOnce();
+    } finally {
+      baseEditor.destroy?.();
+      targetEditor.destroy?.();
+    }
+  });
+
+  it('does not dispatch when there are no changes', async () => {
+    const baseEditor = await openBlankEditor('Identical content.');
+    const targetEditor = await openBlankEditor('Identical content.');
+
+    try {
+      const snapshot = captureSnapshot(targetEditor);
+      const diff = compareToSnapshot(baseEditor, snapshot);
+
+      expect(diff.summary.hasChanges).toBe(false);
+
+      const dispatchSpy = vi.spyOn(baseEditor, 'dispatch');
+      const adapter = createDiffAdapter(baseEditor);
+      const result = adapter.apply({ diff }, { changeMode: 'direct' });
+
+      expect(result.appliedOperations).toBe(0);
+      expect(dispatchSpy).not.toHaveBeenCalled();
+    } finally {
+      baseEditor.destroy?.();
+      targetEditor.destroy?.();
+    }
+  });
+});

packages/super-editor/src/document-api-adapters/diff-adapter.ts

@@ -39,7 +39,7 @@ export function createDiffAdapter(editor: Editor): DiffAdapter {
     apply(input: DiffApplyInput, options?: DiffApplyOptions): DiffApplyResult {
       const { result, tr } = wrapServiceCall(() => applyDiffPayload(editor, input.diff, options));
 
-      if (tr.docChanged) {
+      if (tr.docChanged || result.appliedOperations > 0) {
         editor.dispatch(tr);
       }