fix(document-api): add document diff API and fix tracked diff replay in CLI host session

apps/cli/src/cli/operation-hints.ts

@@ -208,6 +208,11 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   'images.setPosition': 'set position',
   'images.setAnchorOptions': 'set anchor options',
   'images.setZOrder': 'set z-order',
+
+  // Diff
+  'diff.capture': 'captured snapshot',
+  'diff.compare': 'compared documents',
+  'diff.apply': 'applied diff',
 };
 
 // ---------------------------------------------------------------------------
@@ -235,7 +240,10 @@ export type OutputFormat =
   | 'documentInfo'
   | 'receipt'
   | 'plain'
-  | 'void';
+  | 'void'
+  | 'diffSnapshot'
+  | 'diffPayload'
+  | 'diffApplyResult';
 
 export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   get: 'plain',
@@ -375,6 +383,11 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   'images.setPosition': 'plain',
   'images.setAnchorOptions': 'plain',
   'images.setZOrder': 'plain',
+
+  // Diff
+  'diff.capture': 'diffSnapshot',
+  'diff.compare': 'diffPayload',
+  'diff.apply': 'diffApplyResult',
 };
 
 // ---------------------------------------------------------------------------
@@ -537,6 +550,11 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   'headerFooters.parts.list': 'result',
   'headerFooters.parts.create': 'result',
   'headerFooters.parts.delete': 'result',
+
+  // Diff
+  'diff.capture': 'snapshot',
+  'diff.compare': 'diff',
+  'diff.apply': 'result',
 };
 
 // ---------------------------------------------------------------------------
@@ -577,6 +595,7 @@ export type OperationFamily =
   | 'create'
   | 'blocks'
   | 'query'
+  | 'diff'
   | 'general';
 
 export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> = {
@@ -717,4 +736,9 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   'images.setPosition': 'images',
   'images.setAnchorOptions': 'images',
   'images.setZOrder': 'images',
+
+  // Diff
+  'diff.capture': 'diff',
+  'diff.compare': 'diff',
+  'diff.apply': 'diff',
 };

apps/cli/src/cli/operation-set.ts

@@ -105,6 +105,7 @@ const REFERENCE_GROUP_TO_CATEGORY: Record<string, CliCategory> = {
   toc: 'toc',
   images: 'images',
   history: 'history',
+  diff: 'core',
 };
 
 function deriveCategoryFromDocApi(docApiId: OperationId): CliCategory {

apps/cli/src/lib/document.ts

@@ -2,10 +2,9 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { Editor } from 'superdoc/super-editor';
 import { BLANK_DOCX_BASE64 } from '@superdoc/super-editor/blank-docx';
-import { getDocumentApiAdapters } from '@superdoc/super-editor/document-api-adapters';
 import { markdownToPmDoc } from '@superdoc/super-editor/markdown';
 
-import { createDocumentApi, type DocumentApi } from '@superdoc/document-api';
+import type { DocumentApi } from '@superdoc/document-api';
 import { createCliDomEnvironment } from './dom-environment';
 import type { CollaborationProfile } from './collaboration';
 import { createCollaborationRuntime } from './collaboration';
@@ -218,9 +217,6 @@ export async function openDocument(
     }
   }
 
-  const adapters = getDocumentApiAdapters(editor);
-  const docApi = createDocumentApi(adapters);
-  Object.defineProperty(editor, 'doc', { value: docApi, configurable: true, writable: true });
   const editorWithDoc = editor as EditorWithDoc;
 
   return {

apps/cli/src/lib/error-mapping.ts

@@ -324,6 +324,27 @@ function tryMapPlanEngineError(
 // Per-family error mappers (dispatch by family)
 // ---------------------------------------------------------------------------
 
+function mapDiffError(operationId: CliExposedOperationId, error: unknown, code: string | undefined): CliError {
+  const message = extractErrorMessage(error);
+  const details = extractErrorDetails(error);
+
+  if (code === 'INVALID_INPUT') {
+    return new CliError('INVALID_INPUT', message, { operationId, details });
+  }
+  if (code === 'CAPABILITY_UNSUPPORTED') {
+    return new CliError('CAPABILITY_UNSUPPORTED', message, { operationId, details });
+  }
+  if (code === 'PRECONDITION_FAILED') {
+    return new CliError('PRECONDITION_FAILED', message, { operationId, details });
+  }
+  if (code === 'CAPABILITY_UNAVAILABLE') {
+    return new CliError('CAPABILITY_UNAVAILABLE', message, { operationId, details });
+  }
+
+  if (error instanceof CliError) return error;
+  return new CliError('COMMAND_FAILED', message, { operationId, details });
+}
+
 const FAMILY_MAPPERS: Record<
   OperationFamily,
   (operationId: CliExposedOperationId, error: unknown, code: string | undefined) => CliError
@@ -338,6 +359,7 @@ const FAMILY_MAPPERS: Record<
   create: mapCreateError,
   blocks: mapBlocksError,
   query: mapQueryError,
+  diff: mapDiffError,
   general: (operationId, error, code) => {
     // Plan-engine errors pass through with original code and structured details
     const planEngineError = tryMapPlanEngineError(operationId, error, code);

apps/cli/src/lib/errors.ts

@@ -42,7 +42,8 @@ export type CliErrorCode =
   | 'PAGE_NUMBERS_NOT_MATERIALIZED'
   | 'CAPABILITY_UNAVAILABLE'
   | 'INVALID_TARGET'
-  | 'AMBIGUOUS_TARGET';
+  | 'AMBIGUOUS_TARGET'
+  | 'CAPABILITY_UNSUPPORTED';
 
 /**
  * Intersection type for errors thrown by document-api adapter operations.

apps/cli/src/lib/output-formatters.ts

@@ -187,6 +187,46 @@ function formatDocumentInfo(result: unknown, ctx: FormatContext): string {
   return lines.join('\n');
 }
 
+// ---------------------------------------------------------------------------
+// Diff formatters
+// ---------------------------------------------------------------------------
+
+function formatDiffSnapshot(result: unknown, ctx: FormatContext): string {
+  const record = asRecord(result);
+  if (!record) return `Revision ${ctx.revision}: captured snapshot`;
+  const fingerprint = hasNonEmptyString(record.fingerprint) ? record.fingerprint : '<unknown>';
+  const coverage = asRecord(record.coverage);
+  const components = coverage
+    ? Object.entries(coverage)
+        .filter(([, v]) => v === true)
+        .map(([k]) => k)
+        .join(', ')
+    : 'body';
+  const payloadSize = record.payload ? JSON.stringify(record.payload).length : 0;
+  return `Revision ${ctx.revision}: captured snapshot\n  fingerprint: ${fingerprint}\n  coverage: ${components}\n  payload size: ${payloadSize} bytes`;
+}
+
+function formatDiffPayload(result: unknown, ctx: FormatContext): string {
+  const record = asRecord(result);
+  if (!record) return `Revision ${ctx.revision}: compared documents`;
+  const summary = asRecord(record.summary);
+  const changed = asArray(summary?.changedComponents).filter(hasNonEmptyString);
+  const baseFp = hasNonEmptyString(record.baseFingerprint) ? record.baseFingerprint : '<unknown>';
+  const targetFp = hasNonEmptyString(record.targetFingerprint) ? record.targetFingerprint : '<unknown>';
+  const changedStr = changed.length > 0 ? changed.join(', ') : 'none';
+  return `Revision ${ctx.revision}: compared documents\n  base: ${baseFp}\n  target: ${targetFp}\n  changed: ${changedStr}`;
+}
+
+function formatDiffApplyResult(result: unknown, ctx: FormatContext): string {
+  const record = asRecord(result);
+  if (!record) return `Revision ${ctx.revision}: applied diff`;
+  const ops = safeNumber(record.appliedOperations, 0);
+  const summary = asRecord(record.summary);
+  const changed = asArray(summary?.changedComponents).filter(hasNonEmptyString);
+  const changedStr = changed.length > 0 ? changed.join(', ') : 'none';
+  return `Revision ${ctx.revision}: applied diff (${ops} operations)\n  changed: ${changedStr}`;
+}
+
 // ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
@@ -200,6 +240,9 @@ const FORMAT_DISPATCH: Partial<Record<OutputFormat, Formatter>> = {
   listResult: (result, ctx) => formatListResult(result, ctx),
   trackChangeList: (result, ctx) => formatTrackChangeList(result, ctx),
   documentInfo: (result, ctx) => formatDocumentInfo(result, ctx),
+  diffSnapshot: (result, ctx) => formatDiffSnapshot(result, ctx),
+  diffPayload: (result, ctx) => formatDiffPayload(result, ctx),
+  diffApplyResult: (result, ctx) => formatDiffApplyResult(result, ctx),
 };
 
 /**

apps/docs/docs.json

@@ -109,7 +109,10 @@
                   "document-api/available-operations"
                 ]
               },
-              "document-engine/sdks",
+              {
+                "group": "SDKs",
+                "pages": ["document-engine/sdks", "document-engine/sdk-diffing"]
+              },
               "document-engine/cli",
               {
                 "group": "AI Agents",

apps/docs/document-api/available-operations.mdx

@@ -24,6 +24,7 @@ Use the tables below to see what operations are available and where each one is
 | Core | 13 | 0 | 13 | [Reference](/document-api/reference/core/index) |
 | Create | 6 | 0 | 6 | [Reference](/document-api/reference/create/index) |
 | Cross-References | 5 | 0 | 5 | [Reference](/document-api/reference/cross-refs/index) |
+| Diff | 3 | 0 | 3 | [Reference](/document-api/reference/diff/index) |
 | Fields | 5 | 0 | 5 | [Reference](/document-api/reference/fields/index) |
 | Footnotes | 6 | 0 | 6 | [Reference](/document-api/reference/footnotes/index) |
 | Format | 44 | 1 | 45 | [Reference](/document-api/reference/format/index) |
@@ -161,6 +162,9 @@ Use the tables below to see what operations are available and where each one is
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.crossRefs.insert(...)</code></span> | [`crossRefs.insert`](/document-api/reference/cross-refs/insert) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.crossRefs.rebuild(...)</code></span> | [`crossRefs.rebuild`](/document-api/reference/cross-refs/rebuild) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.crossRefs.remove(...)</code></span> | [`crossRefs.remove`](/document-api/reference/cross-refs/remove) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.diff.capture(...)</code></span> | [`diff.capture`](/document-api/reference/diff/capture) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.diff.compare(...)</code></span> | [`diff.compare`](/document-api/reference/diff/compare) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.diff.apply(...)</code></span> | [`diff.apply`](/document-api/reference/diff/apply) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.fields.list(...)</code></span> | [`fields.list`](/document-api/reference/fields/list) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.fields.get(...)</code></span> | [`fields.get`](/document-api/reference/fields/get) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.fields.insert(...)</code></span> | [`fields.insert`](/document-api/reference/fields/insert) |

apps/docs/document-api/reference/_generated-manifest.json

@@ -126,6 +126,10 @@
     "apps/docs/document-api/reference/cross-refs/rebuild.mdx",
     "apps/docs/document-api/reference/cross-refs/remove.mdx",
     "apps/docs/document-api/reference/delete.mdx",
+    "apps/docs/document-api/reference/diff/apply.mdx",
+    "apps/docs/document-api/reference/diff/capture.mdx",
+    "apps/docs/document-api/reference/diff/compare.mdx",
+    "apps/docs/document-api/reference/diff/index.mdx",
     "apps/docs/document-api/reference/fields/get.mdx",
     "apps/docs/document-api/reference/fields/index.mdx",
     "apps/docs/document-api/reference/fields/insert.mdx",
@@ -948,8 +952,15 @@
       "operationIds": ["ranges.resolve"],
       "pagePath": "apps/docs/document-api/reference/ranges/index.mdx",
       "title": "Ranges"
+    },
+    {
+      "aliasMemberPaths": [],
+      "key": "diff",
+      "operationIds": ["diff.capture", "diff.compare", "diff.apply"],
+      "pagePath": "apps/docs/document-api/reference/diff/index.mdx",
+      "title": "Diff"
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "068dea933bf1591112019534c6bae48f811dc8d65c42f6cb94f365548028ea77"
+  "sourceHash": "bf7e9b493d8ab9e84c2d5875b5aa7fe0e74e8504ec3e258e463af5e529b16e92"
 }