@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/session/import/canonical-assembly.ts

@@ -0,0 +1,227 @@
+/**
+ * Canonical-assembly helpers — the layer that turns parsed OOXML
+ * primitives into a `CanonicalDocument` envelope + `PersistedEditorSnapshot`
+ * + `EditorSessionState` triple.
+ *
+ * Slice 5e-6c of refactor/01 package-session. Extracted from
+ * `src/io/docx-session.ts`:
+ *
+ * - `toEditorSessionState` — lift a `PersistedEditorSnapshot` to an
+ *   `EditorSessionState` via the api/session-state helper, or pass a
+ *   live `EditorSessionState` through unchanged.
+ * - `createImportedCanonicalDocument` — compose the canonical document
+ *   from parsed content + styles + numbering + fieldRegistry + media
+ *   + preservation + diagnostics + review.
+ * - `createImportedSnapshot` — wrap a `CanonicalDocument` + session-
+ *   level state (compatibility / protection / sourcePackage /
+ *   workflow overlay + metadata) into a `PersistedEditorSnapshot`.
+ * - `ensureImportedNumberingCatalogSupportsContent` — back-fill the
+ *   synthetic `num:0` numbering instance when the package omitted it
+ *   but content references it (DOCX-null-numbering sentinel).
+ * - `collectReferencedNumberingInstanceIds` — walk the canonical
+ *   content tree and collect every referenced `numberingInstanceId`.
+ *
+ * Contract P6 clean: imports only from `src/model/**`, `src/io/**`,
+ * `src/api/**` (public types + session-state factory). No runtime,
+ * UI, core, or review imports.
+ */
+
+import type {
+  BlockNode,
+  CanonicalDocument,
+  NumberingCatalog,
+  SubPartsCatalog,
+} from "../../model/canonical-document.ts";
+import { createCanonicalDocumentId } from "../../model/canonical-document.ts";
+import type {
+  EditorSessionState,
+  PersistedEditorSnapshot,
+  ProtectionSnapshot,
+} from "../../api/public-types.ts";
+import { editorSessionStateFromPersistedSnapshot } from "../../api/session-state.ts";
+import { buildFieldRegistry } from "../../io/ooxml/parse-fields.ts";
+import type { ParseStylesResult } from "../../io/ooxml/parse-styles.ts";
+import {
+  createSyntheticDocxNullNumberingCatalog,
+  DOCX_NULL_NUMBERING_INSTANCE_ID,
+} from "../../io/ooxml/numbering-sentinels.ts";
+import { buildStylesCatalog } from "./styles-consolidation.ts";
+
+/** Lift a `PersistedEditorSnapshot` to an `EditorSessionState`, or pass
+ * a live `EditorSessionState` through unchanged. Used by export paths
+ * that accept either shape from their caller. */
+export function toEditorSessionState(
+  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
+): EditorSessionState {
+  return "sessionVersion" in sessionStateOrSnapshot
+    ? sessionStateOrSnapshot
+    : editorSessionStateFromPersistedSnapshot(sessionStateOrSnapshot);
+}
+
+/** Walk the canonical content tree and collect every referenced
+ * `numberingInstanceId`. Used to determine whether the DOCX-null
+ * numbering sentinel (`num:0`) must be back-filled. */
+export function collectReferencedNumberingInstanceIds(
+  content: CanonicalDocument["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;
+}
+
+/** Back-fill the synthetic DOCX-null numbering instance when the
+ * package's `numbering.xml` omitted it but the content references
+ * `num:0`. No-op when either (a) the catalog already defines it, or
+ * (b) the content does not reference it. */
+export function ensureImportedNumberingCatalogSupportsContent(
+  catalog: NumberingCatalog,
+  content: CanonicalDocument["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,
+    },
+    ...(catalog.numPicBullets !== undefined ? { numPicBullets: catalog.numPicBullets } : {}),
+  };
+}
+
+/** Compose the canonical document envelope from the parsed OOXML
+ * primitives. Produces a `docId` via the deterministic hash of
+ * `documentId`, builds the styles catalog + fieldRegistry, and
+ * back-fills the DOCX-null numbering sentinel if referenced.
+ *
+ * Pure function over the inputs — no I/O, no wall-clock reads. The
+ * caller supplies the `timestamp` so import-time provenance is
+ * captured once at the outer orchestrator. */
+export function createImportedCanonicalDocument(input: {
+  documentId: string;
+  timestamp: string;
+  numbering: CanonicalDocument["numbering"];
+  media: CanonicalDocument["media"];
+  content: CanonicalDocument["content"];
+  subParts?: SubPartsCatalog;
+  parsedStyles?: ParseStylesResult;
+  fontTable?: CanonicalDocument["fontTable"];
+  preservation: CanonicalDocument["preservation"];
+  diagnostics: CanonicalDocument["diagnostics"];
+  review: CanonicalDocument["review"];
+}): CanonicalDocument {
+  const numbering = ensureImportedNumberingCatalogSupportsContent(
+    input.numbering,
+    input.content,
+  );
+
+  const styles = buildStylesCatalog(input.parsedStyles, input.content, input.subParts);
+
+  // Build the canonical field registry from the assembled {content,
+  // styles, subParts}. The registry is deterministic given those three
+  // inputs, so it belongs on the canonical envelope (architecture §02
+  // D1). Earlier call sites relied on the runtime to recompute the
+  // registry on the first content-changing command; that left
+  // `canonicalDocument.fieldRegistry` undefined immediately after
+  // import, forcing every read-model that consumes fields (document
+  // outline, TOC snapshot, collab fingerprint) to maintain a fallback
+  // walk. Computing here closes the import-truth drop.
+  const fieldRegistry = buildFieldRegistry({
+    content: input.content,
+    styles,
+    ...(input.subParts !== undefined ? { subParts: input.subParts } : {}),
+  });
+  const hasFields =
+    fieldRegistry.supported.length > 0 || fieldRegistry.preserveOnly.length > 0;
+
+  return {
+    schemaVersion: "cds/1.0.0",
+    docId: createCanonicalDocumentId(input.documentId),
+    createdAt: input.timestamp,
+    updatedAt: input.timestamp,
+    metadata: {
+      customProperties: {},
+    },
+    styles,
+    numbering,
+    media: input.media,
+    content: input.content,
+    review: input.review,
+    preservation: input.preservation,
+    diagnostics: input.diagnostics,
+    ...(input.subParts !== undefined ? { subParts: input.subParts } : {}),
+    ...(input.fontTable !== undefined ? { fontTable: input.fontTable } : {}),
+    ...(hasFields ? { fieldRegistry } : {}),
+  };
+}
+
+/** Wrap a `CanonicalDocument` + session-level state into a
+ * `PersistedEditorSnapshot`. Session-level = compatibility report,
+ * protection snapshot, source-package provenance, workflow overlay,
+ * workflow metadata. */
+export function createImportedSnapshot(input: {
+  documentId: string;
+  editorBuild: string;
+  timestamp: string;
+  document: CanonicalDocument;
+  compatibility: PersistedEditorSnapshot["compatibility"];
+  protectionSnapshot: ProtectionSnapshot;
+  sourcePackage?: PersistedEditorSnapshot["sourcePackage"];
+  workflowOverlay?: PersistedEditorSnapshot["workflowOverlay"];
+  workflowMetadata?: PersistedEditorSnapshot["workflowMetadata"];
+  /** W10 — class-A overlay-visibility policies parsed from customXml. */
+  visibilityPolicies?: PersistedEditorSnapshot["visibilityPolicies"];
+  /** X5 — class-A markup-mode policy parsed from customXml. */
+  markupModePolicy?: PersistedEditorSnapshot["markupModePolicy"];
+}): PersistedEditorSnapshot {
+  return {
+    snapshotVersion: "persisted-editor-snapshot/2",
+    schemaVersion: input.document.schemaVersion,
+    documentId: input.documentId,
+    docId: input.document.docId,
+    createdAt: input.document.createdAt,
+    updatedAt: input.document.updatedAt,
+    savedAt: input.timestamp,
+    editorBuild: input.editorBuild,
+    canonicalDocument: input.document,
+    compatibility: input.compatibility,
+    warningLog: input.compatibility.warnings,
+    protectionSnapshot: input.protectionSnapshot,
+    sourcePackage: input.sourcePackage,
+    workflowOverlay: input.workflowOverlay,
+    workflowMetadata: input.workflowMetadata,
+    ...(input.visibilityPolicies && input.visibilityPolicies.length > 0
+      ? { visibilityPolicies: input.visibilityPolicies }
+      : {}),
+    ...(input.markupModePolicy
+      ? { markupModePolicy: input.markupModePolicy }
+      : {}),
+  };
+}

package/src/session/import/diagnostics-session.ts

@@ -0,0 +1,54 @@
+/**
+ * `createDiagnosticsSession` — builds a fatal-error read-only session
+ * state for the load path's error branches. Invoked from 16 sites
+ * inside the sync + async loaders when parse / OPC / validation
+ * diagnostics block normal open.
+ *
+ * Slice 5e-7.d.2 — relocated from `src/io/docx-session.ts`. Pure
+ * glue between `createReadOnlyDiagnosticsRuntime` (already at
+ * `src/session/import/read-only-diagnostics.ts` from 5e-7.c) and the
+ * `LoadedDocxEditorSession` + `LegacyOpenView.exportDocx` shape the
+ * legacy load path expects. No new runtime / core / review imports.
+ *
+ * P6-clean.
+ */
+
+import { editorSessionStateFromPersistedSnapshot } from "../../api/session-state.ts";
+import type { ImportDiagnosticsResult } from "../../validation/import-diagnostics.ts";
+import { createReadOnlyDiagnosticsRuntime } from "./read-only-diagnostics.ts";
+import type {
+  LoadDocxEditorSessionOptions,
+  LoadedDocxEditorSession,
+} from "./loader-types.ts";
+import { EMPTY_PROTECTION_SNAPSHOT } from "../shared/protection.ts";
+
+export function createDiagnosticsSession(
+  options: LoadDocxEditorSessionOptions,
+  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,
+    generatedAt: timestamp,
+    diagnostics,
+  });
+  const initialSnapshot = runtime.getPersistedSnapshot();
+  const initialSessionState =
+    editorSessionStateFromPersistedSnapshot(initialSnapshot);
+
+  return {
+    initialSessionState,
+    initialSnapshot,
+    fatalError: diagnostics.fatalError,
+    readOnly: true,
+    protectionSnapshot: EMPTY_PROTECTION_SNAPSHOT,
+    exportDocx: async (_sessionState, exportOptions) =>
+      runtime.exportDocx(exportOptions),
+  };
+}

package/src/session/import/embedded-discovery.ts

@@ -0,0 +1,225 @@
+/**
+ * Embedded-document discovery — scaffold for P8 Step 6.
+ *
+ * Enumerates every embedded part referenced from the main document's
+ * relationship list, covering two relationship families per
+ * `docs/architecture/01-package-session.md` §P8:
+ *
+ *   - OLE / package embeddings (`relationships/oleObject`,
+ *     `relationships/package`) — binary OLE streams and native OOXML
+ *     sub-packages (Word sub-doc, Excel workbook, PowerPoint deck).
+ *   - `w:altChunk` targets (`relationships/aFChunk`) — alternate-format
+ *     input chunks: HTML fragments, RTF, plain text, XHTML, or nested
+ *     OOXML that Word should render in-place.
+ *
+ * Each discovered entry is classified by `classifyEmbedding()` into
+ * one of three kinds (`digestible` / `offloadable` / `store-only`)
+ * and packaged into the reserved `EmbeddedDocumentManifest` shape
+ * from `src/session/types.ts`.
+ *
+ * Status: ADDITIVE SCAFFOLD. Nothing in the load path calls this yet.
+ * Step 6 promotes the output onto `OpenResult.embeddedDocuments`. The
+ * function is exercised by targeted tests to pin the discovery
+ * contract before it goes live on the critical path.
+ *
+ * P6 clean. Depends only on:
+ *   - src/io/opc/package-reader.ts (allowed)
+ *   - src/io/ooxml/classify-embedding.ts (allowed)
+ *   - src/io/ooxml/parse-ole-relationship.ts (allowed)
+ *   - src/io/ooxml/part-manifest.ts (allowed)
+ *   - src/session/types.ts (peer session module; type-only)
+ */
+
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import {
+  classifyEmbedding,
+  type EmbeddingKind,
+} from "../../io/ooxml/classify-embedding.ts";
+import { OLE_RELATIONSHIP_TYPES } from "../../io/ooxml/parse-ole-relationship.ts";
+import { resolveRelationshipTarget } from "../../io/ooxml/part-manifest.ts";
+import type { EmbeddedDocumentManifest } from "../types.ts";
+
+/**
+ * Relationship type URIs for `w:altChunk` targets. ECMA-376 §17.17
+ * reserves `aFChunk` as the canonical URI; some tooling emits legacy
+ * URIs with slightly different casing — kept in the set to stay
+ * tolerant of producer drift.
+ */
+export const ALT_CHUNK_RELATIONSHIP_TYPES: ReadonlySet<string> = new Set([
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/aFChunk",
+]);
+
+/**
+ * Per-discovery provenance — which relationship family the entry came
+ * from. Consumers (Step 7 offload, export-side reconstitute, truth
+ * comparator) need to distinguish OLE from altChunk even though both
+ * flow through the same `EmbeddedDocumentManifest`.
+ */
+export type EmbeddedDocumentSource = "ole-embedding" | "alt-chunk";
+
+export interface InternalEmbeddedDocumentEntry {
+  /** Provenance of the discovery. */
+  readonly source: EmbeddedDocumentSource;
+  /** Absolute package part path (e.g. `/word/embeddings/chart.xlsx`). */
+  readonly partPath: string;
+  /** Content-Type declared in `[Content_Types].xml`, when known. */
+  readonly contentType: string | null;
+  /** Three-kind classification. */
+  readonly kind: EmbeddingKind;
+  /** Relationship id pointing at the part from the host story. */
+  readonly relationshipId: string;
+  /** Full relationship type URI. */
+  readonly relationshipType: string;
+  /** Path-tail filename (e.g. `chart.xlsx`). */
+  readonly filename?: string;
+  /** Byte length of the underlying package part. */
+  readonly size: number;
+}
+
+export interface EmbeddedDiscoveryResult {
+  /**
+   * Internal discovery records keyed by part path. Useful for test
+   * assertions and for consumers that need the relationship-family
+   * provenance. Step 6 does not expose this directly.
+   */
+  readonly entries: ReadonlyMap<string, InternalEmbeddedDocumentEntry>;
+  /**
+   * Public manifest list in the architecture-reserved shape. This is
+   * what Step 6 surfaces on `OpenResult.embeddedDocuments`.
+   */
+  readonly manifests: readonly EmbeddedDocumentManifest[];
+}
+
+/**
+ * Walk the main document's relationships, identify every OLE/package
+ * and altChunk target, and return both the internal discovery records
+ * and the public manifest list.
+ *
+ * Discovery strategy:
+ *   1. Locate the main document part; bail with empty result if absent.
+ *   2. For each relationship whose type is in
+ *      `OLE_RELATIONSHIP_TYPES` or `ALT_CHUNK_RELATIONSHIP_TYPES`,
+ *      resolve the target to an absolute package path.
+ *   3. Look up the target part in the OPC package. Skip external /
+ *      unresolved targets.
+ *   4. Classify via `classifyEmbedding()`.
+ *   5. Emit a manifest entry with `bytes()` as a lazy accessor —
+ *      no eager copy at discovery time (Performance Invariant 9).
+ */
+export function collectEmbeddedDocuments(
+  sourcePackage: OpcPackage,
+  mainDocumentPath: string,
+): EmbeddedDiscoveryResult {
+  const mainDocumentPart = sourcePackage.parts.get(mainDocumentPath);
+  if (!mainDocumentPart) {
+    return { entries: new Map(), manifests: [] };
+  }
+
+  const entries = new Map<string, InternalEmbeddedDocumentEntry>();
+  const manifests: EmbeddedDocumentManifest[] = [];
+
+  for (const rel of mainDocumentPart.relationships) {
+    if (rel.targetMode !== "internal") continue;
+
+    const source = classifyRelationshipSource(rel.type);
+    if (!source) continue;
+
+    const targetPath = resolveRelationshipTarget(mainDocumentPath, rel);
+    const part = sourcePackage.parts.get(targetPath);
+    if (!part) continue;
+    // Idempotence — a part might be referenced twice; keep the first
+    // relationship record to avoid duplicate manifest entries. The
+    // second relationship id is still preserved on the export side
+    // through the existing preservation store.
+    if (entries.has(targetPath)) continue;
+
+    const filename = extractFilename(rel.target);
+    const size = part.bytes?.byteLength ?? 0;
+    const kind = classifyEmbedding({
+      contentType: part.contentType ?? undefined,
+      relationshipType: rel.type,
+      targetPath: targetPath,
+    });
+
+    const internal: InternalEmbeddedDocumentEntry = {
+      source,
+      partPath: targetPath,
+      contentType: part.contentType,
+      kind,
+      relationshipId: rel.id,
+      relationshipType: rel.type,
+      ...(filename !== undefined ? { filename } : {}),
+      size,
+    };
+    entries.set(targetPath, internal);
+
+    const manifest: EmbeddedDocumentManifest = {
+      id: mintManifestId(targetPath, rel.id, size),
+      kind,
+      ...(filename !== undefined ? { filename } : {}),
+      ...(part.contentType ? { mimeType: part.contentType } : {}),
+      size,
+      relationshipId: rel.id,
+      // Lazy byte accessor — required by Performance Invariant 9.
+      // Allocates a fresh Uint8Array copy per call so callers cannot
+      // mutate the package store.
+      bytes: () => {
+        const raw = part.bytes;
+        if (!raw || raw.byteLength === 0) return new Uint8Array(0);
+        return new Uint8Array(raw);
+      },
+    };
+    manifests.push(manifest);
+  }
+
+  return { entries, manifests };
+}
+
+function classifyRelationshipSource(
+  relationshipType: string,
+): EmbeddedDocumentSource | null {
+  if (OLE_RELATIONSHIP_TYPES.has(relationshipType)) return "ole-embedding";
+  if (ALT_CHUNK_RELATIONSHIP_TYPES.has(relationshipType)) return "alt-chunk";
+  return null;
+}
+
+function extractFilename(target: string): string | undefined {
+  if (!target) return undefined;
+  const slashIdx = target.lastIndexOf("/");
+  const backslashIdx = target.lastIndexOf("\\");
+  const idx = Math.max(slashIdx, backslashIdx);
+  const name = idx >= 0 ? target.slice(idx + 1) : target;
+  return name.length > 0 ? name : undefined;
+}
+
+/**
+ * Stable manifest id. Derived from part path + relationship id + size
+ * so re-opens of the same fixture produce identical ids — required by
+ * architecture §P8 ("id: string; // stable across load/export").
+ * Uses a pair of rolling 32-bit hashes (FNV-1a variants) rather than a
+ * counter so the id survives load-order changes, and does not depend
+ * on `node:crypto` so the session module stays browser-compatible.
+ */
+function mintManifestId(
+  partPath: string,
+  relationshipId: string,
+  size: number,
+): string {
+  const material = `${partPath}
${relationshipId}
${size}`;
+  const a = fnv1a(material, 0x811c9dc5);
+  const b = fnv1a(material, 0x1b873593);
+  return `emb:${toHex8(a)}${toHex8(b)}`;
+}
+
+function fnv1a(input: string, seed: number): number {
+  let hash = seed >>> 0;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+function toHex8(value: number): string {
+  return (value >>> 0).toString(16).padStart(8, "0");
+}