@beyondwork/docx-react-component 1.0.18 → 1.0.19

package/src/io/docx-session.ts

@@ -1,12 +1,14 @@
 import type {
   CompatibilityReport as PublicCompatibilityReport,
   EditorError,
+  EditorSessionState,
   EditorWarning as PublicEditorWarning,
   EditorAnchorProjection as PublicEditorAnchorProjection,
   ExportDocxOptions,
   ExportResult,
   PersistedEditorSnapshot,
 } from "../api/public-types.ts";
+import { editorSessionStateFromPersistedSnapshot } from "../api/session-state.ts";
 import type {
   CanonicalDocumentEnvelope,
   CompatibilityFeatureEntry as InternalCompatibilityFeatureEntry,
@@ -80,6 +82,7 @@ import type {
 import { createReadOnlyDiagnosticsRuntime } from "../runtime/read-only-diagnostics-runtime.ts";
 import {
   WORD_NUMBERING_CONTENT_TYPE,
+  hasSerializableNumberingEntries,
   serializeNumberingXml,
 } from "./export/serialize-numbering.ts";
 import {
@@ -89,6 +92,9 @@ import {
 } from "./ooxml/parse-headers-footers.ts";
 import { parseFootnotesXml, parseEndnotesXml } from "./ooxml/parse-footnotes.ts";
 import { parseThemeXml } from "./ooxml/parse-theme.ts";
+import { resolveTheme } from "./ooxml/parse-theme.ts";
+import { parseSettingsXml } from "./ooxml/parse-settings.ts";
+import { parseStylesXml, type ParseStylesResult } from "./ooxml/parse-styles.ts";
 import {
   serializeHeaderXml,
   serializeFooterXml,
@@ -102,6 +108,11 @@ import {
   WORD_ENDNOTES_CONTENT_TYPE,
 } from "./export/serialize-footnotes.ts";
 import { createPersistedSourcePackage } from "./source-package-provenance.ts";
+import { validatePersistedEditorSnapshot } from "../model/snapshot.ts";
+import {
+  createSyntheticDocxNullNumberingCatalog,
+  DOCX_NULL_NUMBERING_INSTANCE_ID,
+} from "./ooxml/numbering-sentinels.ts";
 
 const MAIN_DOCUMENT_PATH = "/word/document.xml";
 const NUMBERING_PART_PATH = "/word/numbering.xml";
@@ -149,22 +160,29 @@ const FOOTNOTES_RELATIONSHIP_TYPE =
   "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";
 const ENDNOTES_RELATIONSHIP_TYPE =
   "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";
+const SETTINGS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
+const STYLES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+const STYLES_PART_PATH = "/word/styles.xml";
 const FOOTNOTES_PART_PATH = "/word/footnotes.xml";
 const ENDNOTES_PART_PATH = "/word/endnotes.xml";
+const SETTINGS_PART_PATH = "/word/settings.xml";
 
 interface LoadDocxEditorSessionOptions {
   documentId: string;
   sourceLabel?: string;
   bytes: Uint8Array | ArrayBuffer;
-  editorBuild: string;
+  editorBuild?: string;
 }
 
 export interface LoadedDocxEditorSession {
+  initialSessionState: EditorSessionState;
   initialSnapshot: PersistedEditorSnapshot;
   fatalError?: EditorError;
   readOnly: boolean;
   exportDocx: (
-    snapshot: PersistedEditorSnapshot,
+    sessionState: EditorSessionState | PersistedEditorSnapshot,
     options?: ExportDocxOptions,
   ) => Promise<ExportResult>;
 }
@@ -220,6 +238,10 @@ const BLOCKING_COMMENT_DIAGNOSTIC_CODES = new Set<CommentImportDiagnostic["code"
 export function loadDocxEditorSession(
   options: LoadDocxEditorSessionOptions,
 ): LoadedDocxEditorSession {
+  const editorBuild =
+    typeof options.editorBuild === "string" && options.editorBuild.length > 0
+      ? options.editorBuild
+      : "dev";
   const sourceBytes = toUint8Array(options.bytes);
   let sourcePackage: OpcPackage;
 
@@ -404,6 +426,7 @@ export function loadDocxEditorSession(
           variant: ref.variant,
           partPath,
           relationshipId: ref.relationshipId,
+          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
           blocks: parsed.blocks,
         });
         sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
@@ -413,6 +436,7 @@ export function loadDocxEditorSession(
           variant: ref.variant,
           partPath,
           relationshipId: ref.relationshipId,
+          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
           blocks: parsed.blocks,
         });
         sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
@@ -466,17 +490,54 @@ export function loadDocxEditorSession(
             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;
+
+    // ---- 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("");
 
     const subParts: SubPartsCatalog | undefined =
       parsedHeaders.length > 0 ||
       parsedFooters.length > 0 ||
       footnoteCollection !== undefined ||
-      parsedTheme !== 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;
 
@@ -488,6 +549,7 @@ export function loadDocxEditorSession(
       media: normalizedDocument.media,
       content: normalizedDocument.content,
       subParts,
+      parsedStyles,
       preservation: {
         ...normalizedDocument.preservation,
         packageParts: {
@@ -532,12 +594,28 @@ export function loadDocxEditorSession(
     });
     const snapshot = createImportedSnapshot({
       documentId: options.documentId,
-      editorBuild: options.editorBuild,
+      editorBuild,
       timestamp,
       document,
       compatibility: toPublicCompatibilityReport(compatibility),
       sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
     });
+    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,
@@ -597,10 +675,11 @@ export function loadDocxEditorSession(
     };
 
     return {
+      initialSessionState,
       initialSnapshot: snapshot,
       readOnly: false,
-      exportDocx: async (nextSnapshot, exportOptions) =>
-        exportDocxEditorSession(importedState, nextSnapshot, exportOptions),
+      exportDocx: async (nextSessionState, exportOptions) =>
+        exportDocxEditorSession(importedState, nextSessionState, exportOptions),
     };
   } catch (error) {
     return createDiagnosticsSession(
@@ -612,14 +691,16 @@ export function loadDocxEditorSession(
 
 function exportDocxEditorSession(
   state: ImportedDocxState,
-  snapshot: PersistedEditorSnapshot,
+  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
   options?: ExportDocxOptions,
 ): ExportResult {
-  if (snapshot.compatibility.blockExport) {
+  const sessionState = toEditorSessionState(sessionStateOrSnapshot);
+
+  if (sessionState.compatibility.blockExport) {
     throw new Error("DOCX export is blocked by the current compatibility report.");
   }
 
-  const currentDocument = snapshot.canonicalDocument as CanonicalDocumentEnvelope;
+  const currentDocument = sessionState.canonicalDocument as CanonicalDocumentEnvelope;
   if (
     serializeCanonicalDocumentForExport(currentDocument) ===
       state.initialCanonicalSignature &&
@@ -628,7 +709,10 @@ function exportDocxEditorSession(
     return {
       bytes: new Uint8Array(state.sourceBytes),
       mimeType: DOCX_MIME_TYPE,
-      fileName: options?.fileName ?? `${snapshot.documentId}.docx`,
+      fileName: options?.fileName ?? `${sessionState.documentId}.docx`,
+      delivery: {
+        mode: "exported-bytes-only",
+      },
     };
   }
   if (state.blockingCommentDiagnostics.length > 0) {
@@ -660,6 +744,7 @@ function exportDocxEditorSession(
     {
       documentAttributes: state.sourceDocumentAttributes,
       media: currentDocument.media as MediaCatalog,
+      finalSectionProperties: currentDocument.subParts?.finalSectionProperties,
     },
   );
   const revisionDocument = serializeRuntimeRevisionsIntoDocumentXml(
@@ -717,7 +802,9 @@ function exportDocxEditorSession(
     state.sourcePeoplePartPath ?? PEOPLE_PART_PATH;
   const numberingPartPath =
     state.sourceNumberingPartPath ?? NUMBERING_PART_PATH;
-  const serializedNumberingXml = hasNumberingEntries(currentDocument.numbering as NumberingCatalog)
+  const serializedNumberingXml = hasSerializableNumberingEntries(
+    currentDocument.numbering as NumberingCatalog,
+  )
     ? serializeNumberingXml(currentDocument.numbering as NumberingCatalog)
     : undefined;
   const nextRelationships = withDocumentRelatedParts(
@@ -923,10 +1010,21 @@ function exportDocxEditorSession(
   return {
     bytes: exportSession.serialize(),
     mimeType: DOCX_MIME_TYPE,
-    fileName: options?.fileName ?? `${snapshot.documentId}.docx`,
+    fileName: options?.fileName ?? `${sessionState.documentId}.docx`,
+    delivery: {
+      mode: "exported-bytes-only",
+    },
   };
 }
 
+function toEditorSessionState(
+  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
+): EditorSessionState {
+  return "sessionVersion" in sessionStateOrSnapshot
+    ? sessionStateOrSnapshot
+    : editorSessionStateFromPersistedSnapshot(sessionStateOrSnapshot);
+}
+
 function createImportedCanonicalDocument(input: {
   documentId: string;
   timestamp: string;
@@ -934,23 +1032,21 @@ function createImportedCanonicalDocument(input: {
   media: CanonicalDocumentEnvelope["media"];
   content: CanonicalDocumentEnvelope["content"];
   subParts?: SubPartsCatalog;
+  parsedStyles?: ParseStylesResult;
   preservation: CanonicalDocumentEnvelope["preservation"];
   diagnostics: CanonicalDocumentEnvelope["diagnostics"];
   review: CanonicalDocumentEnvelope["review"];
 }): CanonicalDocumentEnvelope {
-  const paragraphStyles = Object.fromEntries(
-    [...collectReferencedParagraphStyleIds(input.content, input.subParts)]
-      .sort((left, right) => left.localeCompare(right))
-      .map((styleId) => [
-        styleId,
-        {
-          styleId,
-          displayName: styleId,
-          kind: "paragraph" as const,
-          isDefault: styleId === "Normal",
-        },
-      ]),
+  const numbering = ensureImportedNumberingCatalogSupportsContent(
+    input.numbering,
+    input.content,
   );
+
+  // Use package-backed style catalog when available; fall back to synthetic
+  // styles derived from referenced styleId values when styles.xml is missing
+  // or could not be parsed.
+  const styles = buildStylesCatalog(input.parsedStyles, input.content, input.subParts);
+
   return {
     schemaVersion: "cds/1.0.0",
     docId: createCanonicalDocumentId(input.documentId),
@@ -959,12 +1055,8 @@ function createImportedCanonicalDocument(input: {
     metadata: {
       customProperties: {},
     },
-    styles: {
-      paragraphs: paragraphStyles,
-      characters: {},
-      tables: {},
-    },
-    numbering: input.numbering,
+    styles,
+    numbering,
     media: input.media,
     content: input.content,
     review: input.review,
@@ -974,6 +1066,136 @@ function createImportedCanonicalDocument(input: {
   };
 }
 
+// Canonical model styleId validation pattern — styleIds that don't match
+// are excluded from the catalog to avoid snapshot validation failures.
+const VALID_STYLE_ID = /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/;
+
+function buildStylesCatalog(
+  parsedStyles: ParseStylesResult | undefined,
+  content: CanonicalDocumentEnvelope["content"],
+  subParts?: SubPartsCatalog,
+): CanonicalDocumentEnvelope["styles"] {
+  if (parsedStyles?.fromPackage) {
+    // Package-backed catalog: filter entries whose styleId does not satisfy
+    // the canonical model pattern (e.g. numeric-only ids from Word).
+    const catalog = filterValidStyleIds(parsedStyles.catalog);
+
+    // Merge in any referenced styleIds that the package styles.xml did not
+    // define (rare but defensive).
+    const referencedIds = collectReferencedParagraphStyleIds(content, subParts);
+    for (const styleId of referencedIds) {
+      if (!catalog.paragraphs[styleId] && VALID_STYLE_ID.test(styleId)) {
+        catalog.paragraphs[styleId] = {
+          styleId,
+          displayName: styleId,
+          kind: "paragraph",
+          isDefault: styleId === "Normal",
+        };
+      }
+    }
+    return {
+      ...catalog,
+      fromPackage: true,
+    };
+  }
+
+  // Synthetic fallback: no styles.xml available
+  const paragraphStyles = Object.fromEntries(
+    [...collectReferencedParagraphStyleIds(content, subParts)]
+      .sort((left, right) => left.localeCompare(right))
+      .filter((styleId) => VALID_STYLE_ID.test(styleId))
+      .map((styleId) => [
+        styleId,
+        {
+          styleId,
+          displayName: styleId,
+          kind: "paragraph" as const,
+          isDefault: styleId === "Normal",
+        },
+      ]),
+  );
+  return {
+    paragraphs: paragraphStyles,
+    characters: {},
+    tables: {},
+    fromPackage: false,
+  };
+}
+
+function filterValidStyleIds(
+  catalog: CanonicalDocumentEnvelope["styles"],
+): CanonicalDocumentEnvelope["styles"] {
+  const filterRecord = <T extends { styleId: string }>(
+    record: Record<string, T>,
+  ): Record<string, T> => {
+    const result: Record<string, T> = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (VALID_STYLE_ID.test(key)) {
+        result[key] = value;
+      }
+    }
+    return result;
+  };
+
+  return {
+    paragraphs: filterRecord(catalog.paragraphs),
+    characters: filterRecord(catalog.characters),
+    tables: filterRecord(catalog.tables),
+    ...(catalog.latentStyles ? { latentStyles: catalog.latentStyles } : {}),
+    ...(catalog.fromPackage !== undefined ? { fromPackage: catalog.fromPackage } : {}),
+  };
+}
+
+function ensureImportedNumberingCatalogSupportsContent(
+  catalog: NumberingCatalog,
+  content: CanonicalDocumentEnvelope["content"],
+): NumberingCatalog {
+  if (
+    catalog.instances[DOCX_NULL_NUMBERING_INSTANCE_ID] ||
+    !collectReferencedNumberingInstanceIds(content).has(DOCX_NULL_NUMBERING_INSTANCE_ID)
+  ) {
+    return catalog;
+  }
+
+  const syntheticNullCatalog = createSyntheticDocxNullNumberingCatalog();
+  return {
+    abstractDefinitions: {
+      ...catalog.abstractDefinitions,
+      ...syntheticNullCatalog.abstractDefinitions,
+    },
+    instances: {
+      ...catalog.instances,
+      ...syntheticNullCatalog.instances,
+    },
+  };
+}
+
+function collectReferencedNumberingInstanceIds(
+  content: CanonicalDocumentEnvelope["content"],
+): Set<string> {
+  const numberingInstanceIds = new Set<string>();
+
+  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
+    for (const block of blocks) {
+      if (block.type === "paragraph" && block.numbering?.numberingInstanceId) {
+        numberingInstanceIds.add(block.numbering.numberingInstanceId);
+      }
+      if (block.type === "table") {
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            visitBlocks(cell.children);
+          }
+        }
+      } else if (block.type === "sdt" || block.type === "custom_xml") {
+        visitBlocks(block.children);
+      }
+    }
+  };
+
+  visitBlocks(content.children);
+  return numberingInstanceIds;
+}
+
 function collectReferencedParagraphStyleIds(
   content: CanonicalDocumentEnvelope["content"],
   subParts?: SubPartsCatalog,
@@ -1110,20 +1332,26 @@ function createDiagnosticsSession(
   diagnostics: ImportDiagnosticsResult,
 ): LoadedDocxEditorSession {
   const timestamp = new Date().toISOString();
+  const editorBuild =
+    typeof options.editorBuild === "string" && options.editorBuild.length > 0
+      ? options.editorBuild
+      : "dev";
   const runtime = createReadOnlyDiagnosticsRuntime({
     documentId: options.documentId,
     sourceLabel: options.sourceLabel,
-    editorBuild: options.editorBuild,
+    editorBuild,
     generatedAt: timestamp,
     diagnostics,
   });
   const initialSnapshot = runtime.getPersistedSnapshot();
+  const initialSessionState = editorSessionStateFromPersistedSnapshot(initialSnapshot);
 
   return {
+    initialSessionState,
     initialSnapshot,
     fatalError: diagnostics.fatalError,
     readOnly: true,
-    exportDocx: async (_snapshot, exportOptions) => runtime.exportDocx(exportOptions),
+    exportDocx: async (_sessionState, exportOptions) => runtime.exportDocx(exportOptions),
   };
 }
 
@@ -1670,13 +1898,6 @@ function createEmptyNumberingCatalog(): NumberingCatalog {
   };
 }
 
-function hasNumberingEntries(catalog: NumberingCatalog): boolean {
-  return (
-    Object.keys(catalog.abstractDefinitions ?? {}).length > 0 ||
-    Object.keys(catalog.instances ?? {}).length > 0
-  );
-}
-
 function collectBrokenInternalRelationshipIssues(
   sourcePackage: OpcPackage,
   mainDocumentPath?: string,