@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/io/docx-session.ts

@@ -1,6 +1,7 @@
 import type {
   CompatibilityReport as PublicCompatibilityReport,
   EditorError,
+  EditorHostAdapter,
   EditorSessionState,
   EditorWarning as PublicEditorWarning,
   EditorAnchorProjection as PublicEditorAnchorProjection,
@@ -39,7 +40,12 @@ import {
   type ParsedInlineNode,
   type ParsedPermStartInlineNode,
 } from "./ooxml/parse-main-document.ts";
-import { normalizeParsedTextDocument } from "./normalize/normalize-text.ts";
+import {
+  normalizeParsedTextDocument,
+  normalizeParsedTextDocumentAsync,
+} from "./normalize/normalize-text.ts";
+import { resolveChartPreviewsForDocument } from "./chart-preview-resolver.ts";
+import { type LoadScheduler } from "./load-scheduler.ts";
 import {
   CONTENT_TYPES_PATH,
   PACKAGE_RELATIONSHIPS_PATH,
@@ -213,6 +219,26 @@ interface LoadDocxEditorSessionOptions {
   sourceLabel?: string;
   bytes: Uint8Array | ArrayBuffer;
   editorBuild?: string;
+  /**
+   * Fastload P2: optional instrumentation callback invoked once per
+   * completed load stage. Stage ordering: opc → body →
+   * styles-numbering-comments → skeleton-ready. `durationMs` is
+   * measured against `performance.now()` boundaries inside the loader.
+   *
+   * Pure instrumentation — has no effect on returned session shape.
+   * Safe to leave undefined; existing callers observe no behavior
+   * change.
+   */
+  onLoadStage?: (stage: import("../api/public-types.ts").LoadStage, durationMs: number) => void;
+  /**
+   * Stage 0B.1: host-adapter surface. The sync loader accepts the option for
+   * API symmetry with {@link LoadDocxEditorSessionAsyncOptions} but does not
+   * invoke `renderChartPreview` — chart-preview synthesis is asynchronous, so
+   * hosts that want preview bitmaps must call {@link loadDocxEditorSessionAsync}.
+   * Other adapter methods (load/saveSession/logEvent) are not consumed by the
+   * loader itself and are carried through unchanged.
+   */
+  hostAdapter?: EditorHostAdapter;
 }
 
 export interface LoadedDocxEditorSession {
@@ -225,6 +251,8 @@ export interface LoadedDocxEditorSession {
     sessionState: EditorSessionState | PersistedEditorSnapshot,
     options?: ExportDocxOptions,
   ) => Promise<ExportResult>;
+  /** Schema 1.2 — editorState block parsed from the 1.2 payload, if present. */
+  initialEditorStatePayload?: import("./ooxml/workflow-payload.ts").EditorStatePayload;
 }
 
 interface ImportedDocxState {
@@ -277,6 +305,37 @@ const BLOCKING_COMMENT_DIAGNOSTIC_CODES = new Set<CommentImportDiagnostic["code"
   "preserve_only_revision_overlap",
 ]);
 
+interface StageEmitter {
+  emit(stage: import("../api/public-types.ts").LoadStage): void;
+}
+
+/**
+ * Fastload P2 (hoisted in P6): build a stage-event emitter. When no callback
+ * is supplied the emitter is a zero-cost no-op. Shared between the sync and
+ * async load orchestrators so both paths emit `load-stage` events at the
+ * same four boundaries: `opc` → `body` → `styles-numbering-comments` →
+ * `skeleton-ready`.
+ */
+function createStageEmitter(
+  onStage: LoadDocxEditorSessionOptions["onLoadStage"],
+): StageEmitter {
+  if (!onStage) {
+    return {
+      emit() {
+        /* no-op */
+      },
+    };
+  }
+  let cursor = loadStageNow();
+  return {
+    emit(stage) {
+      const nextMark = loadStageNow();
+      onStage(stage, nextMark - cursor);
+      cursor = nextMark;
+    },
+  };
+}
+
 export function loadDocxEditorSession(
   options: LoadDocxEditorSessionOptions,
 ): LoadedDocxEditorSession {
@@ -285,6 +344,9 @@ export function loadDocxEditorSession(
       ? options.editorBuild
       : "dev";
   const sourceBytes = toUint8Array(options.bytes);
+
+  const stages = createStageEmitter(options.onLoadStage);
+
   let sourcePackage: OpcPackage;
 
   try {
@@ -297,6 +359,7 @@ export function loadDocxEditorSession(
       }),
     );
   }
+  stages.emit("opc");
   const embeddedWorkflowPayload = parseWorkflowPayloadEnvelopeFromPackage(sourcePackage);
   const embeddedWorkflowMetadata = embeddedWorkflowPayload?.workflowMetadata;
   const embeddedWorkflowOverlay = embeddedWorkflowPayload?.workflowOverlay;
@@ -376,6 +439,7 @@ export function loadDocxEditorSession(
       parsedDocument,
       mainDocumentPath,
     );
+    stages.emit("body");
     const commentsPartPath = resolveCommentsPartPath(
       sourcePackage,
       mainDocumentPath,
@@ -438,6 +502,7 @@ export function loadDocxEditorSession(
       normalizedDocument.preservation.opaqueFragments,
       normalizedRevisions.revisions,
     );
+    stages.emit("styles-numbering-comments");
     const importedStoryRevisions: ReviewRevisionRecord[] = [];
     const importedStoryRevisionDiagnostics: ParsedRevisionsResult["diagnostics"] = [];
     const subPartOpaqueState = createSubPartOpaqueImportState(
@@ -813,6 +878,7 @@ export function loadDocxEditorSession(
       },
     };
 
+    stages.emit("skeleton-ready");
     return {
       initialSessionState,
       initialSnapshot: snapshot,
@@ -820,6 +886,9 @@ export function loadDocxEditorSession(
       protectionSnapshot: importedProtectionSnapshot,
       exportDocx: async (nextSessionState, exportOptions) =>
         exportDocxEditorSession(importedState, nextSessionState, exportOptions),
+      ...(embeddedWorkflowPayload?.editorState
+        ? { initialEditorStatePayload: embeddedWorkflowPayload.editorState }
+        : {}),
     };
   } catch (error) {
     return createDiagnosticsSession(
@@ -829,6 +898,623 @@ export function loadDocxEditorSession(
   }
 }
 
+interface LoadDocxEditorSessionAsyncOptions extends LoadDocxEditorSessionOptions {
+  /**
+   * Scheduler that the async loader awaits between parse stages. Callers
+   * in DOM environments should construct this with `createLoadScheduler()`
+   * (auto-detects scheduler.yield → MessageChannel → setTimeout backend).
+   * Callers in Node / SSR should pass
+   * `createLoadScheduler({ backendOverride: "sync" })` — sync backend
+   * yields resolve without task-boundary latency, so the async path
+   * behaves like the sync path from the test harness POV.
+   */
+  scheduler: LoadScheduler;
+}
+
+/**
+ * Fastload P6: async sibling of {@link loadDocxEditorSession} that yields to
+ * the browser between parse stages. Parse sequence is byte-equivalent to
+ * the sync path (asserted on every F*.docx fixture in
+ * `test/io/fastload-parity.test.ts`). Yields fire at:
+ *   1. after OPC read,
+ *   2. after `parseMainDocumentXml`,
+ *   3. between every header/footer sub-part parse,
+ *   4. after footnotes/endnotes parse,
+ *   5. after theme + settings + styles parse,
+ *   6. after `buildCompatibilityReport`,
+ * plus mid-walk yields every 256 blocks inside
+ * `normalizeParsedTextDocumentAsync` (stage 3 — body normalize).
+ *
+ * Sync `loadDocxEditorSession` remains the only entry point for Node tests
+ * and SSR. The DOM boundary in `editor-runtime-boundary.ts` calls this
+ * async path so the browser can paint the skeleton mid-parse.
+ */
+export async function loadDocxEditorSessionAsync(
+  options: LoadDocxEditorSessionAsyncOptions,
+): Promise<LoadedDocxEditorSession> {
+  const { scheduler } = options;
+  const editorBuild =
+    typeof options.editorBuild === "string" && options.editorBuild.length > 0
+      ? options.editorBuild
+      : "dev";
+  const sourceBytes = toUint8Array(options.bytes);
+
+  const stages = createStageEmitter(options.onLoadStage);
+
+  let sourcePackage: OpcPackage;
+
+  try {
+    sourcePackage = readOpcPackage(sourceBytes);
+  } catch (error) {
+    return createDiagnosticsSession(
+      options,
+      createPackageImportDiagnostics({
+        issue: classifyCorruptPackageError(error),
+      }),
+    );
+  }
+  stages.emit("opc");
+  await scheduler.yield();
+  const embeddedWorkflowPayload = parseWorkflowPayloadEnvelopeFromPackage(sourcePackage);
+  const embeddedWorkflowMetadata = embeddedWorkflowPayload?.workflowMetadata;
+  const embeddedWorkflowOverlay = embeddedWorkflowPayload?.workflowOverlay;
+
+  const mainDocumentPath = resolveMainDocumentPartPath(sourcePackage);
+  const brokenRelationshipIssues = collectBrokenInternalRelationshipIssues(
+    sourcePackage,
+    mainDocumentPath,
+  );
+  if (brokenRelationshipIssues.length > 0) {
+    return createDiagnosticsSession(
+      options,
+      createPackageImportDiagnostics({
+        issue: {
+          ...brokenRelationshipIssues[0],
+          message: summarizeBrokenRelationshipIssues(brokenRelationshipIssues),
+          details: {
+            issueCount: brokenRelationshipIssues.length,
+            targets: brokenRelationshipIssues.map((issue) => issue.targetPartPath).filter(Boolean),
+          },
+        },
+      }),
+    );
+  }
+
+  if (!mainDocumentPath) {
+    return createDiagnosticsSession(
+      options,
+      createPackageImportDiagnostics({
+        issue: createMissingPartIssue(MAIN_DOCUMENT_PATH),
+      }),
+    );
+  }
+
+  const documentPart = sourcePackage.parts.get(mainDocumentPath);
+  if (!documentPart) {
+    return createDiagnosticsSession(
+      options,
+      createPackageImportDiagnostics({
+        issue: createMissingPartIssue(mainDocumentPath),
+      }),
+    );
+  }
+  if (documentPart.contentType !== MAIN_DOCUMENT_CONTENT_TYPE) {
+    return createDiagnosticsSession(
+      options,
+      createValidationImportDiagnostics({
+        message: `DOCX main document part ${mainDocumentPath} must use content type ${MAIN_DOCUMENT_CONTENT_TYPE}.`,
+      }),
+    );
+  }
+
+  try {
+    const sourceDocumentXml = decodeUtf8(documentPart.bytes);
+    const importedRevisions = parseRevisionsFromDocumentXml(sourceDocumentXml);
+    const numberingPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      NUMBERING_RELATIONSHIP_TYPE,
+      NUMBERING_PART_PATH,
+    );
+    const parsedNumbering = numberingPartPath
+      ? parseNumberingXml(
+          decodeUtf8(sourcePackage.parts.get(numberingPartPath)?.bytes ?? new Uint8Array()),
+        )
+      : createEmptyNumberingCatalog();
+    const mediaParts = collectInlineMediaParts(sourcePackage);
+    const parsedDocument = parseMainDocumentXml(
+      sourceDocumentXml,
+      documentPart.relationships,
+      mediaParts,
+      mainDocumentPath,
+    );
+    await scheduler.yield();
+    const protectionRanges = extractProtectionRanges(parsedDocument.blocks);
+    const normalizedDocument = await normalizeParsedTextDocumentAsync(
+      parsedDocument,
+      mainDocumentPath,
+      scheduler,
+    );
+    stages.emit("body");
+    await scheduler.yield();
+    const commentsPartPath = resolveCommentsPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+    );
+    const commentsExtendedPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
+      COMMENTS_EXTENDED_PART_PATH,
+    );
+    const commentsIdsPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      COMMENTS_IDS_RELATIONSHIP_TYPE,
+      COMMENTS_IDS_PART_PATH,
+    );
+    const peoplePartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      PEOPLE_RELATIONSHIP_TYPE,
+      PEOPLE_PART_PATH,
+    );
+    const parsedComments = commentsPartPath
+      ? parseCommentsFromOoxml(
+          sourceDocumentXml,
+          {
+            commentsXml: decodeUtf8(sourcePackage.parts.get(commentsPartPath)?.bytes ?? new Uint8Array()),
+            commentsExtendedXml: decodeUtf8(
+              sourcePackage.parts.get(commentsExtendedPartPath ?? "")?.bytes ?? new Uint8Array(),
+            ),
+            commentsIdsXml: decodeUtf8(
+              sourcePackage.parts.get(commentsIdsPartPath ?? "")?.bytes ?? new Uint8Array(),
+            ),
+            peopleXml: decodeUtf8(
+              sourcePackage.parts.get(peoplePartPath ?? "")?.bytes ?? new Uint8Array(),
+            ),
+          },
+        )
+      : {
+          threads: [] as CommentThread[],
+          diagnostics: [] as CommentImportDiagnostic[],
+          definitions: [] as ImportedCommentDefinition[],
+          sourceRootTag: undefined,
+          sourceExtendedRootTag: undefined,
+          sourceIdsRootTag: undefined,
+          sourcePeopleRootTag: undefined,
+          peopleAuthors: [] as string[],
+        };
+    const normalizedRevisions = normalizeImportedRevisionRecords(
+      importedRevisions,
+      normalizedDocument.content,
+      normalizedDocument.preservation.opaqueFragments,
+    );
+    const normalizedComments = normalizeImportedCommentThreads(
+      parsedComments,
+      normalizedDocument.preservation.opaqueFragments,
+      normalizedRevisions.revisions,
+    );
+    stages.emit("styles-numbering-comments");
+    const importedStoryRevisions: ReviewRevisionRecord[] = [];
+    const importedStoryRevisionDiagnostics: ParsedRevisionsResult["diagnostics"] = [];
+    const subPartOpaqueState = createSubPartOpaqueImportState(
+      normalizedDocument.preservation.opaqueFragments,
+      normalizedDocument.diagnostics.warnings,
+    );
+    // ---- Parse sub-parts: headers, footers, footnotes, endnotes, theme ----
+    const headerFooterRefs = parseHeaderFooterReferences(sourceDocumentXml);
+    const parsedHeaders: HeaderDocument[] = [];
+    const parsedFooters: FooterDocument[] = [];
+    const sourceHeaderPaths: Array<{ partPath: string; relationshipId: string }> = [];
+    const sourceFooterPaths: Array<{ partPath: string; relationshipId: string }> = [];
+    const seenSubPartKeys = new Set<string>();
+
+    for (const ref of headerFooterRefs) {
+      const dedupeKey = `${ref.kind}:${ref.variant}:${ref.relationshipId}`;
+      if (seenSubPartKeys.has(dedupeKey)) {
+        continue;
+      }
+      seenSubPartKeys.add(dedupeKey);
+
+      const relationship = documentPart.relationships.find(
+        (r) => r.id === ref.relationshipId && r.targetMode === "internal",
+      );
+      if (!relationship) {
+        continue;
+      }
+
+      const partPath = resolveRelationshipTarget(mainDocumentPath, relationship);
+      const partBytes = sourcePackage.parts.get(partPath)?.bytes;
+      if (!partBytes) {
+        continue;
+      }
+
+      await scheduler.yield();
+      const xml = decodeUtf8(partBytes);
+      if (ref.kind === "header") {
+        const parsedHeaderRevisions = parseRevisionsFromStoryXml(xml);
+        const parsed = parseHeaderXml(xml);
+        parsedHeaders.push({
+          variant: ref.variant,
+          partPath,
+          relationshipId: ref.relationshipId,
+          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
+          blocks: normalizeSubPartOpaqueBlocks(
+            parsed.blocks,
+            normalizedDocument.preservation.opaqueFragments,
+            normalizedDocument.diagnostics.warnings,
+            partPath,
+            subPartOpaqueState,
+          ),
+        });
+        importedStoryRevisions.push(
+          ...parsedHeaderRevisions.revisions.map((revision): ReviewRevisionRecord => ({
+            ...revision,
+            metadata: {
+              ...revision.metadata,
+              storyTarget: {
+                kind: "header" as const,
+                relationshipId: ref.relationshipId,
+                variant: ref.variant,
+                ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
+              },
+            },
+          })),
+        );
+        importedStoryRevisionDiagnostics.push(...parsedHeaderRevisions.diagnostics);
+        sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
+      } else {
+        const parsedFooterRevisions = parseRevisionsFromStoryXml(xml);
+        const parsed = parseFooterXml(xml);
+        parsedFooters.push({
+          variant: ref.variant,
+          partPath,
+          relationshipId: ref.relationshipId,
+          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
+          blocks: normalizeSubPartOpaqueBlocks(
+            parsed.blocks,
+            normalizedDocument.preservation.opaqueFragments,
+            normalizedDocument.diagnostics.warnings,
+            partPath,
+            subPartOpaqueState,
+          ),
+        });
+        importedStoryRevisions.push(
+          ...parsedFooterRevisions.revisions.map((revision): ReviewRevisionRecord => ({
+            ...revision,
+            metadata: {
+              ...revision.metadata,
+              storyTarget: {
+                kind: "footer" as const,
+                relationshipId: ref.relationshipId,
+                variant: ref.variant,
+                ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
+              },
+            },
+          })),
+        );
+        importedStoryRevisionDiagnostics.push(...parsedFooterRevisions.diagnostics);
+        sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
+      }
+    }
+
+    const footnotesPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      FOOTNOTES_RELATIONSHIP_TYPE,
+      FOOTNOTES_PART_PATH,
+    );
+    const footnotesRelationshipId = documentPart.relationships.find(
+      (r) => r.type === FOOTNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
+    )?.id;
+    const endnotesPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      ENDNOTES_RELATIONSHIP_TYPE,
+      ENDNOTES_PART_PATH,
+    );
+    const endnotesRelationshipId = documentPart.relationships.find(
+      (r) => r.type === ENDNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
+    )?.id;
+
+    let footnoteCollection: FootnoteCollection | undefined;
+    if (footnotesPartPath) {
+      footnoteCollection = parseFootnotesXml(
+        decodeUtf8(sourcePackage.parts.get(footnotesPartPath)?.bytes ?? new Uint8Array()),
+      );
+      normalizeFootnoteCollectionOpaqueBlocks(
+        footnoteCollection,
+        "footnote",
+        normalizedDocument.preservation.opaqueFragments,
+        normalizedDocument.diagnostics.warnings,
+        footnotesPartPath,
+        subPartOpaqueState,
+      );
+    }
+    if (endnotesPartPath) {
+      footnoteCollection = parseEndnotesXml(
+        decodeUtf8(sourcePackage.parts.get(endnotesPartPath)?.bytes ?? new Uint8Array()),
+        footnoteCollection,
+      );
+      normalizeFootnoteCollectionOpaqueBlocks(
+        footnoteCollection,
+        "endnote",
+        normalizedDocument.preservation.opaqueFragments,
+        normalizedDocument.diagnostics.warnings,
+        endnotesPartPath,
+        subPartOpaqueState,
+      );
+    }
+    await scheduler.yield();
+
+    const themeRelationship = documentPart.relationships.find(
+      (r) => r.type === "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" &&
+        r.targetMode === "internal",
+    );
+    const themePartPath = themeRelationship
+      ? resolveRelationshipTarget(mainDocumentPath, themeRelationship)
+      : undefined;
+    const parsedTheme =
+      themePartPath && sourcePackage.parts.has(themePartPath)
+        ? parseThemeXml(
+            decodeUtf8(sourcePackage.parts.get(themePartPath)?.bytes ?? new Uint8Array()),
+          )
+        : undefined;
+    const resolvedTheme = parsedTheme ? resolveTheme(parsedTheme) : undefined;
+    const settingsPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      SETTINGS_RELATIONSHIP_TYPE,
+      SETTINGS_PART_PATH,
+    );
+    const parsedSettings =
+      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
+        ? parseSettingsXml(
+            decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array()),
+          )
+        : undefined;
+    const settingsXmlForProtection =
+      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
+        ? decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array())
+        : "";
+    const documentProtection = extractDocumentProtection(settingsXmlForProtection);
+    const importedProtectionSnapshot = buildProtectionSnapshot(documentProtection, protectionRanges);
+
+    // ---- Parse styles.xml for canonical style catalog ----
+    const stylesPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      STYLES_RELATIONSHIP_TYPE,
+      STYLES_PART_PATH,
+    );
+    const parsedStyles =
+      stylesPartPath && sourcePackage.parts.has(stylesPartPath)
+        ? parseStylesXml(
+            decodeUtf8(sourcePackage.parts.get(stylesPartPath)?.bytes ?? new Uint8Array()),
+          )
+        : parseStylesXml("");
+    await scheduler.yield();
+
+    const subParts: SubPartsCatalog | undefined =
+      parsedHeaders.length > 0 ||
+      parsedFooters.length > 0 ||
+      footnoteCollection !== undefined ||
+      parsedTheme !== undefined ||
+      normalizedDocument.finalSectionProperties !== undefined ||
+      resolvedTheme !== undefined ||
+      parsedSettings !== undefined
+        ? {
+            headers: parsedHeaders,
+            footers: parsedFooters,
+            ...(footnoteCollection !== undefined ? { footnoteCollection } : {}),
+            ...(parsedTheme !== undefined ? { theme: parsedTheme } : {}),
+            ...(normalizedDocument.finalSectionProperties !== undefined
+              ? { finalSectionProperties: normalizedDocument.finalSectionProperties }
+              : {}),
+            ...(resolvedTheme !== undefined ? { resolvedTheme } : {}),
+            ...(parsedSettings !== undefined ? { settings: parsedSettings } : {}),
+          }
+        : undefined;
+
+    const timestamp = new Date().toISOString();
+    const translatedWorkflowState = translateClmCommentsToWorkflow({
+      comments: normalizedComments.threads,
+      workflowOverlay: embeddedWorkflowOverlay,
+      workflowMetadata: embeddedWorkflowMetadata,
+      timestamp,
+    });
+    const importedDocument = createImportedCanonicalDocument({
+      documentId: options.documentId,
+      timestamp,
+      numbering: parsedNumbering,
+      media: normalizedDocument.media,
+      content: normalizedDocument.content,
+      subParts,
+      parsedStyles,
+      preservation: {
+        ...normalizedDocument.preservation,
+        packageParts: {
+          ...normalizedDocument.preservation.packageParts,
+          ...collectPreservedPackageParts(sourcePackage, [
+            mainDocumentPath,
+            numberingPartPath,
+            commentsPartPath,
+            commentsExtendedPartPath,
+            commentsIdsPartPath,
+            peoplePartPath,
+          ]),
+        },
+      },
+      diagnostics: {
+        warnings: [
+          ...createBrokenRelationshipWarnings(sourcePackage, mainDocumentPath),
+          ...normalizedDocument.diagnostics.warnings,
+          ...normalizedRevisions.diagnostics.map((diagnostic, index) => ({
+            diagnosticId: `diagnostic:revision-import-${index + 1}`,
+            warningId: `warning:revision-import-${diagnostic.revisionId}`,
+            source: "review" as const,
+            message: diagnostic.message,
+          })),
+          ...importedStoryRevisionDiagnostics.map((diagnostic, index) => ({
+            diagnosticId: `diagnostic:story-revision-import-${index + 1}`,
+            warningId: `warning:story-revision-import-${diagnostic.revisionId}`,
+            source: "review" as const,
+            message: diagnostic.message,
+          })),
+          ...normalizedComments.diagnostics.map((diagnostic, index) => ({
+            diagnosticId: `diagnostic:comment-import-${index + 1}`,
+            warningId: `warning:comment-import-${diagnostic.commentId}`,
+            source: "review" as const,
+            message: diagnostic.message,
+          })),
+        ],
+        errors: [],
+      },
+      review: {
+        comments: toRuntimeCommentRecords(translatedWorkflowState.comments),
+        revisions: toRuntimeRevisionRecords([
+          ...normalizedRevisions.revisions,
+          ...importedStoryRevisions,
+        ]),
+      },
+    });
+    // Stage 0B.1: if the host implements `renderChartPreview`, resolve
+    // chart_preview nodes inline so the first snapshot already carries the
+    // synthesized `previewMediaId`. Fallback-safe: returning null or throwing
+    // is per-chart — the typed badge renders as if the adapter weren't set.
+    const document = (await resolveChartPreviewsForDocument(
+      importedDocument,
+      sourcePackage,
+      options.hostAdapter,
+    )) as CanonicalDocumentEnvelope;
+    const compatibility = buildCompatibilityReport({
+      document,
+      generatedAt: timestamp,
+    });
+    await scheduler.yield();
+    const snapshot = createImportedSnapshot({
+      documentId: options.documentId,
+      editorBuild,
+      timestamp,
+      document,
+      compatibility: toPublicCompatibilityReport(compatibility),
+      protectionSnapshot: importedProtectionSnapshot,
+      sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
+      workflowOverlay: translatedWorkflowState.workflowOverlay,
+      workflowMetadata: translatedWorkflowState.workflowMetadata,
+    });
+    const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
+    if (snapshotIssues.length > 0) {
+      const firstIssue = snapshotIssues[0];
+      return createDiagnosticsSession(
+        options,
+        createValidationImportDiagnostics({
+          message: `DOCX import produced an invalid editor state during validation${firstIssue ? ` (${firstIssue.path}: ${firstIssue.message})` : "."}`,
+          source: "import",
+          details: {
+            issueCount: snapshotIssues.length,
+            firstIssuePath: firstIssue?.path,
+          },
+        }),
+      );
+    }
+    const initialSessionState = editorSessionStateFromPersistedSnapshot(snapshot);
+    const importedState: ImportedDocxState = {
+      sourceBytes: new Uint8Array(sourceBytes),
+      sourcePackage,
+      sourceDocumentXml,
+      sourceDocumentPartPath: mainDocumentPath,
+      sourceDocumentRelationships: documentPart.relationships,
+      sourceDocumentAttributes: extractDocumentRootAttributes(sourceDocumentXml),
+      sourceNumberingPartPath: numberingPartPath,
+      sourceNumberingRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === NUMBERING_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsPartPath: commentsPartPath,
+      sourceCommentsRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === COMMENTS_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsRootTag: normalizedComments.sourceRootTag,
+      sourceCommentsExtendedPartPath: commentsExtendedPartPath,
+      sourceCommentsExtendedRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === COMMENTS_EXTENDED_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsExtendedRootTag: normalizedComments.sourceExtendedRootTag,
+      sourceCommentsIdsPartPath: commentsIdsPartPath,
+      sourceCommentsIdsRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === COMMENTS_IDS_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsIdsRootTag: normalizedComments.sourceIdsRootTag,
+      sourcePeoplePartPath: peoplePartPath,
+      sourcePeopleRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === PEOPLE_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourcePeopleRootTag: normalizedComments.sourcePeopleRootTag,
+      sourcePeopleAuthors: normalizedComments.peopleAuthors,
+      protectionSnapshot: buildProtectionSnapshot(documentProtection, protectionRanges),
+      preservedCommentDefinitions: normalizedComments.preservedDefinitions,
+      blockingCommentDiagnostics: normalizedComments.diagnostics.filter((diagnostic) =>
+        BLOCKING_COMMENT_DIAGNOSTIC_CODES.has(diagnostic.code),
+      ),
+      initialCanonicalSignature: serializeCanonicalDocumentForExport(document),
+      sourceSubPartPaths: {
+        headers: sourceHeaderPaths,
+        footers: sourceFooterPaths,
+        footnotesPartPath,
+        footnotesRelationshipId,
+        endnotesPartPath,
+        endnotesRelationshipId,
+        themePartPath,
+        themeRelationshipId: themeRelationship?.id,
+      },
+    };
+
+    stages.emit("skeleton-ready");
+    return {
+      initialSessionState,
+      initialSnapshot: snapshot,
+      readOnly: false,
+      protectionSnapshot: importedProtectionSnapshot,
+      exportDocx: async (nextSessionState, exportOptions) =>
+        exportDocxEditorSession(importedState, nextSessionState, exportOptions),
+      ...(embeddedWorkflowPayload?.editorState
+        ? { initialEditorStatePayload: embeddedWorkflowPayload.editorState }
+        : {}),
+    };
+  } catch (error) {
+    return createDiagnosticsSession(
+      options,
+      createImportDiagnosticsFromError(error),
+    );
+  }
+}
+
+function loadStageNow(): number {
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
 function exportDocxEditorSession(
   state: ImportedDocxState,
   sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
@@ -1286,7 +1972,9 @@ function exportDocxEditorSession(
   }
 
   ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
-  ensureWorkflowPayloadParts(exportSession, sessionState, currentDocument, state.sourcePackage);
+  // Schema 1.2: pass through editorState payload collected by the runtime channel.
+  const internalEditorState = (options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined)?._editorState;
+  ensureWorkflowPayloadParts(exportSession, sessionState, currentDocument, state.sourcePackage, internalEditorState);
 
   return {
     bytes: exportSession.serialize(),
@@ -3012,11 +3700,13 @@ function ensureWorkflowPayloadParts(
   sessionState: EditorSessionState,
   document: CanonicalDocumentEnvelope,
   sourcePackage: OpcPackage,
+  editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload,
 ): void {
   const payloadParts = buildWorkflowPayloadParts({
     sourcePackage,
     workflowMetadata: sessionState.workflowMetadata,
     workflowOverlay: sessionState.workflowOverlay,
+    editorState,
     documentId: sessionState.documentId,
     createdAt: document.createdAt,
     updatedAt: document.updatedAt,