@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/session/import/loader-types.ts

@@ -0,0 +1,313 @@
+/**
+ * Types + constants shared by the sync (`loadDocxEditorSession`) and
+ * async (`loadDocxEditorSessionAsync`) load paths, plus the downstream
+ * export pipeline (`exportDocxEditorSession`).
+ *
+ * Slice 5e-7.d.0 — relocated from `src/io/docx-session.ts`. The load
+ * bodies move to `src/session/import/load-sync.ts` + `load-async.ts`
+ * in 5e-7.d.1 + .2; this file reserves their shared type destination
+ * first so the body moves only have to deal with behavior, not types.
+ *
+ * P6 compliance for session-layer purity:
+ *   - `telemetryBus` typed as `unknown` (matching the public
+ *     `OpenOptions` pattern in `src/session/types.ts`) so this file
+ *     does not transit `src/runtime/debug/telemetry-bus.ts`. The load
+ *     body narrows to the concrete `TelemetryBus` internally.
+ *   - `laycacheEnvelope` typed as `unknown` for the same reason
+ *     (the concrete `CacheEnvelope` type lives in
+ *     `src/runtime/prerender/cache-envelope.ts`, which is the
+ *     single remaining debt-exception transit inside
+ *     `src/io/docx-session.ts`). Narrowing happens inside the load
+ *     body.
+ *
+ * Re-exported from `src/io/docx-session.ts` for back-compat during
+ * the transition; consumers that import from the legacy path continue
+ * to work unchanged until 5e-9 retires the file.
+ */
+
+import type { EditorSessionState } from "../session-state.ts";
+import type {
+  EditorError,
+  EditorHostAdapter,
+  EditorSurfaceSnapshot,
+  ExportDocxOptions,
+  ExportResult,
+  LoadStage,
+  PersistedEditorSnapshot,
+  ProtectionSnapshot,
+} from "../../api/public-types.ts";
+import type { LoadScheduler } from "../../io/load-scheduler.ts";
+import type {
+  CommentImportDiagnostic,
+  ImportedCommentDefinition,
+} from "../../io/ooxml/parse-comments.ts";
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import type { OpcRelationship } from "../../io/ooxml/part-manifest.ts";
+import type { EditorStatePayload } from "../../io/ooxml/workflow-payload.ts";
+import type {
+  EmbeddedDocumentManifest,
+  ProgressiveSurfaceProjector,
+} from "../types.ts";
+
+/**
+ * Options for `loadDocxEditorSession` (sync). The async variant
+ * (`LoadDocxEditorSessionAsyncOptions`) extends this.
+ */
+export interface LoadDocxEditorSessionOptions {
+  documentId: string;
+  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: 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 the async path.
+   * Other adapter methods (load/saveSession/logEvent) are not consumed by the
+   * loader itself and are carried through unchanged.
+   */
+  hostAdapter?: EditorHostAdapter;
+  /**
+   * Optional telemetry bus. When provided, the loader brackets every
+   * `parseMainDocumentXml` invocation with
+   * `setActiveParseTelemetryBus(bus)` / `setActiveParseTelemetryBus(undefined)`
+   * so the parser emits on the `parse` channel.
+   *
+   * Typed `unknown` at this session-layer boundary (§P6 forbids
+   * `src/runtime/**` imports; the concrete `TelemetryBus` type lives
+   * at `src/runtime/debug/telemetry-bus.ts`). The load body narrows
+   * internally.
+   */
+  telemetryBus?: unknown;
+  /**
+   * P8 Step 7 — explicit opt-in for embedded-document offload. When
+   * `true` AND `hostAdapter.storeEmbeddedDocument` is defined, the
+   * loader runs the offload pass on every `offloadable` manifest:
+   * materialize bytes → compute sha-256 → call `storeEmbeddedDocument`
+   * → persist `bw:embeddings` customXml reference + inline-bytes
+   * fallback.
+   *
+   * Default `false` (or omitted): no offload is performed, even when
+   * `hostAdapter.storeEmbeddedDocument` is defined. Offloadable
+   * manifests fall through to the preservation-store path (identical
+   * semantics to store-only — bytes stay on the parent package).
+   *
+   * Rationale (cross-layer-coord-04 §1.13 + cross-layer-coord-01 §5):
+   * sha-256 + base64-encode of a large offloadable embedding on the
+   * critical path is ~300 ms per MB. A 2.5 MB offloadable embedding
+   * (F52, CCEP EU-Global-IT-Services) would otherwise silently
+   * regress cold-open by ~40 % for every host that supplies an
+   * adapter for chart-preview / save-session / log-event purposes
+   * unrelated to offload. The flag gates the cost behind explicit
+   * intent.
+   *
+   * Re-open path: packages that ALREADY carry `bw:embeddings`
+   * customXml entries from a prior offload rehydrate from those
+   * entries regardless of this flag — that path is sha/base64-free
+   * (the customXml already has the values). The flag only gates
+   * FRESH offload on first-open.
+   */
+  offloadEmbeddedDocuments?: boolean;
+}
+
+/**
+ * Options for `loadDocxEditorSessionAsync`.
+ */
+export interface LoadDocxEditorSessionAsyncOptions
+  extends LoadDocxEditorSessionOptions {
+  /**
+   * Scheduler that the async loader awaits between parse stages.
+   * See `src/io/load-scheduler.ts::createLoadScheduler()`.
+   */
+  scheduler: LoadScheduler;
+  /**
+   * L7 Phase 2.5 Plan B B.6b — optional laycache envelope. When
+   * supplied, the async loader short-circuits the five expensive
+   * parse stages and uses `envelope.canonicalDocument` directly.
+   *
+   * Typed `unknown` at this session-layer boundary (§P6 — concrete
+   * `CacheEnvelope` lives at `src/runtime/prerender/cache-envelope.ts`).
+   * The load body narrows internally.
+   */
+  laycacheEnvelope?: unknown;
+  /**
+   * DI seam for the laycache probe. When set AND no pre-resolved
+   * `laycacheEnvelope` is supplied, the session invokes this
+   * callback on the source bytes. See
+   * `src/session/types.ts::OpenOptions.laycacheProbe` for rationale
+   * (retires the last runtime-layer debt exception).
+   */
+  laycacheProbe?: (
+    bytes: Uint8Array | ArrayBuffer,
+  ) => Promise<{ envelope: unknown } | null>;
+  /**
+   * L7 Phase 2 Finale C2 — progressive initial mount callback.
+   * See field docs on `src/session/types.ts::OpenOptions`
+   * for the full semantics.
+   */
+  onProgressiveSnapshot?: (partial: {
+    surface?: EditorSurfaceSnapshot;
+    phase: "viewport";
+    blocksRealized: number;
+    blocksTotal: number;
+  }) => void;
+  /**
+   * Runtime-side port for progressive-surface synthesis — see
+   * `src/session/types.ts::ProgressiveSurfaceProjector`.
+   */
+  surfaceProjector?: ProgressiveSurfaceProjector;
+  /**
+   * C3b — deferred chart preview resolution.
+   */
+  onChartPreviewsReady?: (
+    resolvedDoc: import("../../model/canonical-document.ts").CanonicalDocument,
+  ) => void;
+}
+
+/**
+ * Shape returned by the sync + async loaders. Consumed by
+ * `DocxSession.open()` + `createDiagnosticsSession` + legacy callers.
+ */
+export interface LoadedDocxEditorSession {
+  initialSessionState: EditorSessionState;
+  initialSnapshot: PersistedEditorSnapshot;
+  fatalError?: EditorError;
+  readOnly: boolean;
+  protectionSnapshot: ProtectionSnapshot;
+  exportDocx: (
+    sessionState: EditorSessionState | PersistedEditorSnapshot,
+    options?: ExportDocxOptions,
+  ) => Promise<ExportResult>;
+  /** Schema 1.2 — editorState block parsed from the 1.2 payload, if present. */
+  initialEditorStatePayload?: EditorStatePayload;
+  /**
+   * P8 Step 6 — embedded-document discovery output. Populated by the
+   * legacy loader via `collectEmbeddedDocuments(sourcePackage,
+   * mainDocumentPath)` immediately after OPC read. Empty on the
+   * laycache short-circuit path (the cached envelope does not carry
+   * the OPC package in a form the discovery walk can use).
+   *
+   * Consumed by `DocxSession.open()` to populate
+   * `OpenResult.embeddedDocuments`.
+   */
+  embeddedDocumentManifests?: readonly EmbeddedDocumentManifest[];
+}
+
+/**
+ * State captured at import time that the export pipeline consumes to
+ * round-trip the package. Carries source bytes, the OPC package
+ * snapshot, per-part relationships, preserved-part manifest, and the
+ * initial canonical signature used for fast-path byte reuse.
+ *
+ * Load path builds this; `exportDocxEditorSession` consumes it via
+ * the closure captured at open time.
+ */
+export interface ImportedDocxState {
+  sourceBytes: Uint8Array;
+  sourcePackage: OpcPackage;
+  sourceDocumentXml: string;
+  sourceDocumentPartPath: string;
+  sourceDocumentRelationships: readonly OpcRelationship[];
+  sourceDocumentAttributes: Record<string, string>;
+  sourceNumberingPartPath?: string;
+  sourceNumberingRelationshipId?: string;
+  /**
+   * Resolved `/word/settings.xml` part path when the source package
+   * carried one. Threaded through to the export path so the settings
+   * serializer can call `replaceOwnedPart` with the right relationship
+   * target.
+   */
+  sourceSettingsPartPath?: string;
+  /**
+   * Original settings.xml bytes decoded as UTF-8. Passed to
+   * `serializeSettingsXml(settings, sourceXml)` as the graft source so
+   * unmodelled top-level children (`<w:defaultTabStop>`,
+   * `<w:documentProtection>`, mail-merge state, etc.) survive verbatim
+   * through round-trip. Undefined when the source package lacked a
+   * settings part.
+   */
+  sourceSettingsXml?: string;
+  sourceCommentsPartPath?: string;
+  sourceCommentsRelationshipId?: string;
+  sourceCommentsRootTag?: string;
+  sourceCommentsExtendedPartPath?: string;
+  sourceCommentsExtendedRelationshipId?: string;
+  sourceCommentsExtendedRootTag?: string;
+  sourceCommentsIdsPartPath?: string;
+  sourceCommentsIdsRelationshipId?: string;
+  sourceCommentsIdsRootTag?: string;
+  sourcePeoplePartPath?: string;
+  sourcePeopleRelationshipId?: string;
+  sourcePeopleRootTag?: string;
+  sourcePeopleAuthors: readonly string[];
+  protectionSnapshot: ProtectionSnapshot;
+  preservedCommentDefinitions: readonly ImportedCommentDefinition[];
+  blockingCommentDiagnostics: readonly CommentImportDiagnostic[];
+  initialCanonicalSignature: string;
+  sourceSubPartPaths: {
+    headers: Array<{ partPath: string; relationshipId: string }>;
+    footers: Array<{ partPath: string; relationshipId: string }>;
+    footnotesPartPath?: string;
+    footnotesRelationshipId?: string;
+    endnotesPartPath?: string;
+    endnotesRelationshipId?: string;
+    themePartPath?: string;
+    themeRelationshipId?: string;
+  };
+  /**
+   * P8 Step 7 — offload entries captured at open time for every
+   * `offloadable` embedded document the host's `storeEmbeddedDocument`
+   * adapter accepted. Empty when no adapter is present, when the
+   * package contained zero offloadable entries, or when every
+   * adapter call failed (each falls back to store-only).
+   *
+   * Type is kept opaque here (`readonly unknown[]`) so
+   * `loader-types.ts` does not transit the embedded-offload module's
+   * concrete types — `src/session/export/embedded-reconstitute.ts`
+   * narrows at the single export-side consumption site.
+   */
+  embeddingOffloadEntries: readonly unknown[];
+  /**
+   * P8 Step 7 — host adapter captured at open time, threaded through
+   * to the export path so `runStatefulExport` can call
+   * `loadEmbeddedDocument` for every offloaded entry. Undefined when
+   * no adapter was supplied; export falls back to the inline-bytes
+   * base64 copy persisted alongside each entry.
+   */
+  hostAdapter?: EditorHostAdapter;
+}
+
+/**
+ * Comment-diagnostic codes that block export when present on imported
+ * comments. Shared between the load path (diagnostic aggregation) and
+ * the export path (assertion).
+ */
+export const BLOCKING_COMMENT_DIAGNOSTIC_CODES = new Set<
+  CommentImportDiagnostic["code"]
+>([
+  "missing_comment_definition",
+  "missing_anchor_reference",
+  "multi_paragraph_anchor_preserve_only",
+  "opaque_anchor_preserve_only",
+  "preserve_only_revision_overlap",
+]);
+
+/**
+ * L7 Phase 2 Finale C2 — progressive initial-mount viewport window
+ * size. Sized to cover the first page of a typical paginated document
+ * (~20 body blocks ≈ 1 page on CCEP-scale templates at default
+ * margins). Blocks beyond this window render as `placeholder-culled`
+ * entries via Phase 2.9's cullBuild flag.
+ */
+export const PROGRESSIVE_VIEWPORT_BLOCKS = 20;