@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/session/session.ts

@@ -0,0 +1,532 @@
+/**
+ * `DocxSession` — the reserved Layer-01 public entry class.
+ *
+ * Shape matches `docs/architecture/01-package-session.md` § Public
+ * entry points:
+ *
+ *   open(bytes, opts?) → Promise<OpenResult>
+ *   export(doc,   opts?) → Promise<ExportResult>
+ *   validate(doc, opts?) → ValidationReport
+ *
+ * Slice-4 state: `open()` is wired and additionally attaches a
+ * module-private legacy view (accessed via
+ * `src/session/_internal-legacy.ts`) for in-tree services that still
+ * need the stateful `exportDocx` closure. `export()` and `validate()`
+ * throw `SessionNotWiredError` — the architecture reserves them as
+ * stateless, which requires a new pipeline that lands in Slice 5.
+ *
+ * P6 discipline: `src/session` must not import from `src/runtime`,
+ * `src/ui` / `src/ui-tailwind`, `src/core`, or `src/review`. This file transits
+ * `src/io/docx-session.ts` (legacy integration orchestrator) under a
+ * documented debt exception — the legacy file itself still imports
+ * forbidden runtime/review surfaces (see `src/io/docx-session.ts:35–43`
+ * and architecture doc §P6 "debt exception"). The exception closes in
+ * Slice 5 when the legacy file is deleted; the purity checker warns
+ * (not errors) on this specific transit, and a session-transit test
+ * pins the exception so any accidental reintroduction is caught.
+ */
+
+import type { CanonicalDocument } from "../model/canonical-document.ts";
+import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
+// Slice 5e-8.a: session.ts now reaches the load pipeline directly
+// via `src/session/import/loader.ts` (in-layer). The legacy transit
+// through `src/io/docx-session.ts` is retired along with the
+// debt-exception entry for this file in the purity CI guard.
+import { loadDocxSessionAsync } from "./import/loader.ts";
+import type { LoadDocxEditorSessionAsyncOptions } from "./import/loader-types.ts";
+import { createLoadScheduler } from "../io/load-scheduler.ts";
+// P6 debt exception: the laycache probe lives in
+// `src/runtime/prerender/` because its `CacheEnvelope` type
+// transitively references `CompatibilityReport` (core) and
+// `RuntimePageGraph` (runtime/layout). Relocating those shared
+// types is a layer-04/05 concern. The transit is pinned in
+// `scripts/ci-check-session-layer-purity.mjs::DEBT_EXCEPTIONS` so
+// CI surfaces the debt on every run.
+// Slice 5e-11 item-1: the laycache probe is now dependency-injected
+// via `OpenOptions.laycacheProbe` — session no longer imports from
+// `src/runtime/prerender/**`. This retires the last P6 debt
+// exception for Layer 01. See `docs/plans/cross-layer-coord-01.md §1`.
+// Slice 5e-11 item-4: the WeakMap-backed `_internal-legacy.ts`
+// accessor has been retired. `initialSnapshot`,
+// `initialEditorStatePayload?`, `exportDocx`, and `dispose?` are
+// public fields on `OpenResult` now; `DocxSession.export` + `dispose`
+// route through the captured `lastOpenResult` directly.
+import type { EditorSessionState } from "./session-state.ts";
+import type {
+  EmbeddedDocumentManifest,
+  ExportOptions,
+  ExportResult,
+  OpenOptions,
+  OpenResult,
+  PreservationSnapshot,
+  ReopenBarrier,
+  ValidateOptions,
+  ValidationFinding,
+  ValidationReport,
+} from "./types.ts";
+import type { PersistedEditorSnapshot } from "../api/public-types.ts";
+import {
+  decodePersistedSourcePackageBytes,
+  hasValidPersistedSourcePackageDigest,
+} from "../io/source-package-provenance.ts";
+
+/**
+ * Thrown from `DocxSession.export` when called on an instance that has
+ * not yet called `open()` (or whose capture has been cleared by
+ * `dispose()`).
+ *
+ * Layer-01 export is session-bound: `open()` captures the
+ * `ImportedDocxState` (source bytes, `OpcPackage`, per-part
+ * relationships, preserved-part manifest) that the export pipeline
+ * needs in order to round-trip. Calling `export(sessionState)` on an
+ * instance that never ran `open()` has no state to dispatch through.
+ *
+ * The architecture doc (`docs/architecture/01-package-session.md` §
+ * "Public entry points") deliberately reserves `export(sessionState)`
+ * rather than `export(doc)`: `EditorSessionState` carries the
+ * session-level fields (`workflowOverlay`, `workflowMetadata`,
+ * `warningLog`, `protectionSnapshot`) that the layer bakes into
+ * `customXml/itemN.xml` on export, which are not part of
+ * `CanonicalDocument`. A cross-session `export(doc)` overload is
+ * deliberately omitted from this phase — it requires a byte-free
+ * preservation contract (Layer-02 extension) that has not shipped.
+ */
+export class SessionNotOpenError extends Error {
+  constructor() {
+    super(
+      "DocxSession.export(sessionState) requires DocxSession.open(bytes) to have been called on this session instance first. " +
+        "Open the source package through this session, then call export(sessionState) with the runtime's current session state.",
+    );
+    this.name = "SessionNotOpenError";
+  }
+}
+
+/**
+ * Legacy alias for `SessionNotOpenError`. Kept for one release window
+ * so callers that were catching the 5e-4 `SessionNotWiredError` for
+ * `export` continue to work.
+ *
+ * @deprecated use `SessionNotOpenError` — this alias goes away with
+ * Slice 5e-9 when the legacy file is deleted.
+ */
+export const SessionNotWiredError = SessionNotOpenError;
+
+/**
+ * Reserved Layer-01 entry class. `open()` and `export()` are async per
+ * the architecture reservation; `validate()` is synchronous because it
+ * runs against an already-loaded canonical document.
+ *
+ * Session-bound export model: `open()` captures the `OpenResult`
+ * handle (which carries the `LegacyOpenView.exportDocx` closure +
+ * `ImportedDocxState`). `export(sessionState, opts)` dispatches
+ * through that captured closure with the caller-supplied session
+ * state — the runtime's current state, carrying any
+ * `workflowOverlay` / `workflowMetadata` edits made between open and
+ * export. A session instance that has not been `open`ed throws
+ * `SessionNotOpenError`.
+ *
+ * Re-opening on the same instance overwrites the capture; `export()`
+ * always dispatches through the most recent open. In practice hosts
+ * construct one `DocxSession` per document and keep it alive for the
+ * runtime's lifetime (see `services/debug/lib/doc-loader.ts` for the
+ * reference pattern).
+ */
+export class DocxSession {
+  /**
+   * Most recent `open()` result — captured so `export(sessionState)`
+   * can reach the `LegacyOpenView.exportDocx` closure via the
+   * `src/session/_internal-legacy.ts` WeakMap. Cleared on `dispose()`.
+   *
+   * The caller's `sessionState` argument to `export()` is passed
+   * through verbatim; this slot is only the dispatch anchor, not a
+   * source of truth for export data.
+   */
+  private lastOpenResult?: OpenResult;
+
+  /**
+   * Open a DOCX package from bytes. Returns the canonical document,
+   * session state, compatibility report, preservation snapshot, and
+   * the embedded-document manifest list populated from
+   * `collectEmbeddedDocuments` (P8).
+   *
+   * Implementation delegates to the legacy async loader
+   * (`loadDocxEditorSessionAsync`) while Slices 2–4 extract parse/
+   * serialize orchestration into `src/session/import/**` +
+   * `src/session/export/**`. The signature here is stable — the body
+   * can swap to the new orchestrator without consumers noticing.
+   */
+  async open(
+    bytes: Uint8Array | ArrayBuffer,
+    opts: OpenOptions = {},
+  ): Promise<OpenResult> {
+    // CLAUDE.md Performance Invariant 10: colocate the probe with the
+    // loader so nothing blocking can be inserted between them. When
+    // `opts.tryLaycacheEnvelope` is true AND `opts.laycacheProbe` is
+    // supplied, run the probe here; the result becomes
+    // `laycacheEnvelope` on the legacy loader options. An explicitly
+    // supplied `opts.laycacheEnvelope` wins over the probe so custom
+    // caching layers still work.
+    //
+    // The probe itself is dependency-injected (Slice 5e-11 item-1) so
+    // session does not import from `src/runtime/prerender/**`. The
+    // shell / prerender entry point passes `tryReadLaycacheEnvelope`
+    // as the probe.
+    let resolvedLaycacheEnvelope: unknown = opts.laycacheEnvelope;
+    if (
+      resolvedLaycacheEnvelope === undefined &&
+      opts.tryLaycacheEnvelope === true &&
+      opts.laycacheProbe
+    ) {
+      const probeResult = await opts.laycacheProbe(bytes);
+      if (probeResult) {
+        resolvedLaycacheEnvelope = probeResult.envelope;
+      }
+    }
+
+    // Scheduler created here so its `dispose` can be handed back to
+    // the caller via `LegacyOpenView.dispose`. Interactive hosts
+    // (editor-runtime-boundary in Slice 5c) call it on unmount to
+    // cancel pending idle chart-preview callbacks; one-shot callers
+    // like `prerenderDocument` can omit the call because the sync
+    // backend has nothing to cancel.
+    const scheduler =
+      opts.schedulerBackend !== undefined
+        ? createLoadScheduler({ backendOverride: opts.schedulerBackend })
+        : createLoadScheduler();
+
+    const legacyOptions: LoadDocxEditorSessionAsyncOptions = {
+      bytes,
+      documentId: opts.documentId ?? mintTransientDocumentId(),
+      ...(opts.sourceLabel !== undefined
+        ? { sourceLabel: opts.sourceLabel }
+        : {}),
+      ...(opts.editorBuild !== undefined
+        ? { editorBuild: opts.editorBuild }
+        : {}),
+      ...(opts.hostAdapter !== undefined
+        ? { hostAdapter: opts.hostAdapter }
+        : {}),
+      ...(opts.offloadEmbeddedDocuments !== undefined
+        ? { offloadEmbeddedDocuments: opts.offloadEmbeddedDocuments }
+        : {}),
+      ...(opts.onLoadStage !== undefined
+        ? { onLoadStage: opts.onLoadStage }
+        : {}),
+      ...(opts.telemetryBus !== undefined
+        ? {
+            // The public `OpenOptions.telemetryBus` is typed `unknown`
+            // so this barrel does not drag runtime-layer types into
+            // the session surface. The legacy loader narrows it back
+            // to the concrete `TelemetryBus` shape internally.
+            telemetryBus:
+              opts.telemetryBus as LoadDocxEditorSessionAsyncOptions["telemetryBus"],
+          }
+        : {}),
+      ...(resolvedLaycacheEnvelope !== undefined
+        ? {
+            laycacheEnvelope:
+              resolvedLaycacheEnvelope as LoadDocxEditorSessionAsyncOptions["laycacheEnvelope"],
+          }
+        : {}),
+      ...(opts.onChartPreviewsReady !== undefined
+        ? { onChartPreviewsReady: opts.onChartPreviewsReady }
+        : {}),
+      ...(opts.onProgressiveSnapshot !== undefined
+        ? { onProgressiveSnapshot: opts.onProgressiveSnapshot }
+        : {}),
+      ...(opts.surfaceProjector !== undefined
+        ? { surfaceProjector: opts.surfaceProjector }
+        : {}),
+      // Session class picks the scheduler so callers do not have to.
+      // DOM + Node both work: `createLoadScheduler()` auto-detects the
+      // best backend (scheduler.yield → MessageChannel → setTimeout →
+      // sync). `opts.schedulerBackend` pins the backend when the caller
+      // needs determinism (e.g. `prerenderDocument` forces `"sync"`).
+      //
+      // Scheduler disposal: carried through `LegacyOpenView.dispose`
+      // so interactive hosts can cancel pending idle chart-preview
+      // callbacks on unmount (Performance Invariant 9). Disposing
+      // here would race with the loader's own post-return idle work.
+      scheduler,
+    };
+    const legacy = await loadDocxSessionAsync(legacyOptions);
+
+    const sessionState = legacy.initialSessionState;
+    const canonicalDocument =
+      sessionState.canonicalDocument as CanonicalDocument;
+    const preservation: PreservationSnapshot =
+      canonicalDocument.preservation;
+
+    // P8 Step 6: embedded-document discovery runs inside the legacy
+    // loader and surfaces here via `legacy.embeddedDocumentManifests`.
+    // The array is empty when the package has no embeddings or the
+    // loader short-circuited on a laycache envelope.
+    const embeddedDocuments: readonly EmbeddedDocumentManifest[] =
+      legacy.embeddedDocumentManifests ?? [];
+
+    // Slice 5e-11 item-4: the remaining `LegacyOpenView` fields
+    // (`initialSnapshot`, `initialEditorStatePayload`, `exportDocx`,
+    // `dispose`) graduate to `OpenResult` directly per L06's
+    // `OpenResult` shape decision (`docs/architecture/06-workflow-
+    // review.md` §"Open-time surface"). The WeakMap-backed
+    // `_internal-legacy.ts` is retired.
+    const result: OpenResult = {
+      sessionState,
+      canonicalDocument,
+      compatibility: sessionState.compatibility,
+      preservation,
+      embeddedDocuments,
+      // Slice 5e-1 legacy-view graduates.
+      readOnly: legacy.readOnly,
+      ...(legacy.fatalError !== undefined
+        ? { fatalError: legacy.fatalError }
+        : {}),
+      protectionSnapshot: legacy.protectionSnapshot,
+      ...(resolvedLaycacheEnvelope !== undefined
+        ? { laycacheEnvelope: resolvedLaycacheEnvelope }
+        : {}),
+      // Slice 5e-11 item-4 graduates.
+      initialSnapshot: legacy.initialSnapshot,
+      ...(legacy.initialEditorStatePayload !== undefined
+        ? { initialEditorStatePayload: legacy.initialEditorStatePayload }
+        : {}),
+      exportDocx: legacy.exportDocx,
+      dispose: () => scheduler.dispose(),
+    };
+
+    // Capture the open result so `export(sessionState)` can reach the
+    // legacy view's stateful `exportDocx` closure without the caller
+    // threading the `OpenResult` back through. Overwritten on re-open;
+    // cleared by `dispose()`.
+    this.lastOpenResult = result;
+
+    return result;
+  }
+
+  /**
+   * Serialize an editor session state to a DOCX package.
+   *
+   * Per the architecture (`docs/architecture/01-package-session.md` §
+   * "Public entry points"), `export` takes the full `EditorSessionState`
+   * — not just a `CanonicalDocument` — because the session-level fields
+   * `workflowOverlay`, `workflowMetadata`, `warningLog`, and
+   * `protectionSnapshot` are bakery-inputs to `customXml/itemN.xml` on
+   * export, and live outside the canonical model. The runtime calls
+   * `session.export(runtime.getSessionState(), opts)` and the session
+   * passes `sessionState` straight through to the stateful export
+   * pipeline — no splice, no hidden state-carry.
+   *
+   * Dispatch: the method reaches the `LegacyOpenView.exportDocx`
+   * closure captured during the most recent `open()` on this instance.
+   * That closure holds the `ImportedDocxState` (source bytes,
+   * `OpcPackage`, per-part relationships, preserved-part manifest)
+   * that the pipeline needs in order to round-trip. When
+   * `sessionState.canonicalDocument` is referentially the same object
+   * as was produced at open time and every other field is unchanged,
+   * the legacy pipeline hits its byte-reuse fast path (identical
+   * `initialCanonicalSignature` + `canReuse`) and returns the source
+   * bytes directly.
+   *
+   * Throws `SessionNotOpenError` when called before `open()` on this
+   * instance. Cross-session export (a session state whose source bytes
+   * this instance never saw) is a later Layer-01 follow-up: it needs a
+   * byte-free preservation contract that has not shipped.
+   *
+   * P6 discipline: dispatch goes through `getLegacyOpenView(result).
+   * exportDocx(...)` — the WeakMap-backed accessor at
+   * `src/session/_internal-legacy.ts`. No direct import of
+   * `exportDocxEditorSession` from `src/io/docx-session.ts` is added
+   * beyond the `session.ts → docx-session.ts` debt exception already
+   * present for `open()`'s legacy transit.
+   */
+  async export(
+    sessionState: EditorSessionState,
+    opts: ExportOptions = {},
+  ): Promise<ExportResult> {
+    const captured = this.lastOpenResult;
+    if (!captured) {
+      throw new SessionNotOpenError();
+    }
+    // Slice 5e-11 item-4: `exportDocx` is a public field on
+    // `OpenResult` now. The WeakMap-backed accessor was retired when
+    // the remaining legacy-view fields graduated.
+    return captured.exportDocx(sessionState, opts);
+  }
+
+  /**
+   * Release resources captured by the most recent `open()`. Clears
+   * the session's internal capture and forwards to `OpenResult.dispose`
+   * (which cancels pending idle chart-preview callbacks scheduled by
+   * the load scheduler — CLAUDE.md Performance Invariant 9).
+   *
+   * After `dispose()`, a subsequent `export(sessionState)` on this
+   * instance throws `SessionNotOpenError` until `open()` is called
+   * again.
+   */
+  dispose(): void {
+    const captured = this.lastOpenResult;
+    if (!captured) return;
+    captured.dispose?.();
+    this.lastOpenResult = undefined;
+  }
+
+  /**
+   * Rehydrate a Layer-01 session from a previously-persisted
+   * `EditorSessionState` or `PersistedEditorSnapshot`.
+   *
+   * Shipped in Slice 5e-11 item-2 in response to the L07 Option-B
+   * decision (`docs/architecture/07-runtime-api.md` §Seam-reality).
+   * Replaces the manual decode-bytes-and-call-loadDocxSessionSync
+   * dance that `src/shell/session-bootstrap.ts::resolvePackageBackedExportSession`
+   * had to do by reaching across the Layer-01 boundary.
+   *
+   * Behaviour:
+   *   1. Extract the persisted `sourcePackage` envelope from the
+   *      snapshot. If absent → return `ReopenBarrier { reason: "no-source-package" }`.
+   *   2. Base64-decode the bytes via `decodePersistedSourcePackageBytes`.
+   *      If decode throws → return `ReopenBarrier { reason: "corrupted-bytes" }`.
+   *   3. Digest-check via `hasValidPersistedSourcePackageDigest`. On
+   *      mismatch → return `ReopenBarrier { reason: "invalid-digest" }`.
+   *   4. Forward the bytes to `loadDocxSessionAsync`. Any fatal parse
+   *      error surfaces on the returned `OpenResult.fatalError` as
+   *      normal — NOT as a barrier (the rehydrate path produced a
+   *      valid `OpenResult`; the LOAD decided it was unusable).
+   *
+   * Never throws. Barriers are always returned as data so callers
+   * can diff / display / persist without try-catch envelopes.
+   *
+   * On success, the returned `OpenResult` is captured on this
+   * instance the same way `open()` does — subsequent `export()` and
+   * `dispose()` calls operate on the rehydrated session.
+   */
+  async reopenFromSnapshot(
+    snapshot: PersistedEditorSnapshot | EditorSessionState,
+    opts: OpenOptions = {},
+  ): Promise<OpenResult | ReopenBarrier> {
+    const sourcePackage = snapshot.sourcePackage;
+    if (!sourcePackage) {
+      return {
+        reason: "no-source-package",
+        message:
+          "Cannot reopen from snapshot — the persisted session carries no embedded source-package envelope.",
+      };
+    }
+    let bytes: Uint8Array;
+    try {
+      bytes = decodePersistedSourcePackageBytes(sourcePackage);
+    } catch (err) {
+      return {
+        reason: "corrupted-bytes",
+        message: `Failed to decode source-package bytes: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+    if (!hasValidPersistedSourcePackageDigest(sourcePackage, bytes)) {
+      return {
+        reason: "invalid-digest",
+        message:
+          "Source-package digest check failed — the persisted snapshot has been tampered with or the schema drifted.",
+      };
+    }
+    return this.open(bytes, {
+      ...opts,
+      ...(opts.documentId === undefined
+        ? { documentId: snapshot.documentId }
+        : {}),
+      ...(opts.sourceLabel === undefined && sourcePackage.sourceLabel
+        ? { sourceLabel: sourcePackage.sourceLabel }
+        : {}),
+      ...(opts.editorBuild === undefined && "editorBuild" in snapshot
+        ? { editorBuild: snapshot.editorBuild }
+        : {}),
+    });
+  }
+
+  /**
+   * Validate a canonical document against the compatibility engine.
+   *
+   * Slice 5e-4 wired this through the existing
+   * `buildCompatibilityReport` machinery. The method is synchronous
+   * per the architecture reservation and is a pure function of the
+   * canonical document — no session state is read.
+   *
+   * `ok` is `false` when the report's `blockExport` flag is set OR
+   * any finding carries `severity === "error"`. Consumer surfaces
+   * (agents, CI gates) can rely on this single boolean to decide
+   * whether the document is export-blocked.
+   */
+  validate(
+    doc: CanonicalDocument,
+    _opts: ValidateOptions = {},
+  ): ValidationReport {
+    const report = buildCompatibilityReport({
+      // `buildCompatibilityReport` accepts the richer
+      // `CanonicalDocumentEnvelope` shape; a `CanonicalDocument` is a
+      // structural subset, so the cast is safe at the boundary.
+      document: doc as unknown as Parameters<
+        typeof buildCompatibilityReport
+      >[0]["document"],
+      generatedAt: new Date().toISOString(),
+    });
+
+    const findings: ValidationFinding[] = [
+      ...report.featureEntries.map<ValidationFinding>((entry) => ({
+        code: entry.featureEntryId,
+        severity: featureClassToSeverity(entry.featureClass),
+        message: entry.message,
+        ...(entry.featureKey !== undefined
+          ? { featureKey: entry.featureKey }
+          : {}),
+      })),
+      ...report.warnings.map<ValidationFinding>((warning) => ({
+        code: warning.code,
+        severity: "warning" as const,
+        message: warning.message,
+      })),
+      ...report.errors.map<ValidationFinding>((error) => ({
+        code: error.code,
+        severity: "error" as const,
+        message: error.message,
+      })),
+    ];
+
+    const ok =
+      !report.blockExport &&
+      !findings.some((finding) => finding.severity === "error");
+
+    return { ok, findings };
+  }
+}
+
+/**
+ * Map `CompatibilityFeatureClass` onto the narrower severity tri-state
+ * the `ValidationFinding` contract exposes. Fatal / blocking classes
+ * become `"error"`; partially-supported / warning-esque classes become
+ * `"warning"`; everything else is informational.
+ */
+function featureClassToSeverity(
+  featureClass: string,
+): ValidationFinding["severity"] {
+  if (
+    featureClass === "unsupported-fatal" ||
+    featureClass === "unsupported-blocking" ||
+    featureClass === "unsupported-blocking-export"
+  ) {
+    return "error";
+  }
+  if (
+    featureClass === "unsupported-partial" ||
+    featureClass === "supported-partial" ||
+    featureClass === "preserve-only"
+  ) {
+    return "warning";
+  }
+  return "info";
+}
+
+function mintTransientDocumentId(): string {
+  // The session class does not own stable document identity; hosts
+  // that need round-trip-stable ids pass `opts.documentId`. This
+  // fallback is for ad-hoc opens (tests, one-off conversions).
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `docx-session-${Date.now().toString(36)}-${rand}`;
+}