@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/session/session.ts

@@ -1,5 +1,5 @@
 /**
- * `DocxSession` — the reserved Layer-01 public entry class.
+ * `DocxSession` — the Layer-01 package/session public entry class.
  *
  * Shape matches `docs/architecture/01-package-session.md` § Public
  * entry points:
@@ -8,49 +8,28 @@
  *   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.
+ * Current state: `open()`, `export()`, `validate()`, and
+ * `reopenFromSnapshot()` are wired against in-session loader/export
+ * implementations. `OpenResult` carries the open-time export/dispose
+ * handles directly.
  *
  * 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.
+ * `src/ui` / `src/ui-tailwind`, `src/shell`, `src/core`, or
+ * `src/review`. The purity checker enforces this with zero debt
+ * exceptions; runtime/presentation hooks enter through typed options.
  */
 
 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.
+// Session reaches the load pipeline directly through the in-layer
+// loader. The `src/io/docx-session.ts` path is a back-compat shim, not
+// a dependency of this class.
 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.
+// Runtime-facing hooks are dependency-injected. `OpenOptions.laycacheProbe`
+// prevents a direct runtime/prerender import, and `OpenResult` carries
+// the open-time export/dispose handles directly.
 import type { EditorSessionState } from "./session-state.ts";
 import type {
   EmbeddedDocumentManifest,
@@ -117,9 +96,9 @@ export const SessionNotWiredError = SessionNotOpenError;
  * 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
+ * handle, including the stateful `exportDocx` function produced by
+ * the in-session loader/export pipeline. `export(sessionState, opts)`
+ * dispatches through that captured function 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
@@ -134,8 +113,8 @@ export const SessionNotWiredError = SessionNotOpenError;
 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()`.
+   * can reach the captured `OpenResult.exportDocx` function. Cleared
+   * on `dispose()`.
    *
    * The caller's `sessionState` argument to `export()` is passed
    * through verbatim; this slot is only the dispatch anchor, not a
@@ -149,11 +128,9 @@ export class DocxSession {
    * 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.
+   * Implementation delegates to the in-layer async loader in
+   * `src/session/import/loader.ts`; callers do not reach into the
+   * back-compat `src/io/docx-session.ts` shim.
    */
   async open(
     bytes: Uint8Array | ArrayBuffer,
@@ -295,9 +272,9 @@ export class DocxSession {
     };
 
     // 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()`.
+    // stateful `exportDocx` function without the caller threading the
+    // `OpenResult` back through. Overwritten on re-open; cleared by
+    // `dispose()`.
     this.lastOpenResult = result;
 
     return result;
@@ -316,8 +293,8 @@ export class DocxSession {
    * 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.
+   * Dispatch: the method reaches the `OpenResult.exportDocx` function
+   * 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
@@ -332,12 +309,9 @@ export class DocxSession {
    * 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.
+   * P6 discipline: dispatch goes through the captured `OpenResult`
+   * field. The session layer does not import the compatibility
+   * `src/io/docx-session.ts` shim or any runtime/presentation module.
    */
   async export(
     sessionState: EditorSessionState,

package/src/session/types.ts

@@ -4,8 +4,8 @@
  * These types mirror the reserved shape in
  * `docs/architecture/01-package-session.md` § "Public entry points".
  * They are the contract consumers see; the implementation in
- * `src/session/session.ts` may still delegate transitionally to the
- * legacy `src/io/docx-session.ts` while the extraction completes.
+ * `src/session/session.ts` delegates to in-layer loader/export
+ * modules.
  *
  * P6 clean: imports only from `src/api/**` (type-only), `src/model/**`,
  * `src/io/**`, and `src/preservation/**`.
@@ -31,10 +31,9 @@ import type { LoadSchedulerBackend } from "../io/load-scheduler.ts";
 import type { PreservationStore } from "../model/canonical-document.ts";
 import type { EditorSessionState } from "./session-state.ts";
 
-// Re-export legacy types so downstream consumers that still need them
-// during the transition can reach them from the session barrel. These
-// are explicitly transitional and scheduled for removal in Slice 5 once
-// the legacy `src/io/docx-session.ts` is deleted.
+// Re-export back-compat public types so downstream consumers can reach
+// them from the session barrel instead of the `src/io/docx-session.ts`
+// shim.
 export type {
   EditorHostAdapter,
   ExportDocxOptions,
@@ -307,13 +306,9 @@ export type PreservationSnapshot = PreservationStore;
  * doc exactly: session state + canonical document + compatibility
  * report + preservation snapshot + embedded-document manifest (P8).
  *
- * Every field here is part of the reserved Layer-01 public contract.
- * The transitional legacy-session handle that in-tree services still
- * need during the Slice-4 → Slice-5 migration is carried through a
- * WeakMap-backed accessor (`getLegacyOpenView`) in the
- * `src/session/_internal-legacy.ts` module — NOT as a public field on
- * this shape. The architecture doc has no `_legacy` escape hatch,
- * and public consumers must not see one.
+ * Every field here is part of the Layer-01 public contract. The
+ * open-time export/dispose handles are explicit fields so callers do
+ * not need any private legacy escape hatch.
  */
 export interface OpenResult {
   readonly sessionState: EditorSessionState;

package/src/shell/session-bootstrap.ts

@@ -52,28 +52,27 @@ import {
   type RuntimeDebugFacet,
 } from "../runtime/debug/runtime-debug-facet.ts";
 // Slice 5c flipped the async DOM warm path to `DocxSession.open()`.
-// The two remaining sync call sites (SSR/Node `createRuntime`
-// fallback + `resolvePackageBackedExportSession`) were isolated
-// behind `src/session/_sync-legacy.ts` in Slice 5e-3 so the UI layer
-// no longer imports directly from the legacy file. The shim + its
-// debt exception in `ci-check-session-layer-purity.mjs` go away at
-// Slice 5e-9 together with the legacy file.
+// The remaining sync call site is the SSR/Node `createRuntime`
+// fallback for raw DOCX bytes. Snapshot/session source-package reopen
+// is async via `DocxSession.reopenFromSnapshot()` so presentation
+// surfaces never decode persisted package bytes themselves.
 import type { CacheEnvelope } from "../runtime/prerender/cache-envelope.ts";
 import { tryReadLaycacheEnvelope } from "../runtime/prerender/customxml-probe.ts";
 import { createEditorSurfaceSnapshot } from "../runtime/surface-projection.ts";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
 import type { ProgressiveSurfaceProjector } from "../session/types.ts";
-import { DocxSession } from "../session/index.ts";
+import {
+  DocxSession,
+  isReopenBarrier,
+  type OpenResult,
+  type ReopenBarrier,
+} from "../session/index.ts";
 // Slice 5e-11 item-4: `_internal-legacy.ts` retired. All fields that
 // were reached through `getLegacyOpenView` are now public on
 // `OpenResult` directly; a tiny local adapter maps `OpenResult` into
 // the `LoadedDocxEditorSession` shape the downstream shell code
 // still expects.
 import { openDocxSync } from "../session/_sync-legacy.ts";
-import {
-  decodePersistedSourcePackageBytes,
-  hasValidPersistedSourcePackageDigest,
-} from "../io/source-package-provenance.ts";
 import {
   createEditorViewStateSnapshot,
   createViewState,
@@ -81,7 +80,7 @@ import {
 import { hydrateEditorStateFromEnvelope } from "../runtime/editor-state-integration.ts";
 import {
   recordPerfSample,
-} from "../ui-tailwind/editor-surface/perf-probe.ts";
+} from "../runtime/telemetry/perf-probe.ts";
 import {
   downloadExportResult,
   withExportDelivery,
@@ -100,7 +99,15 @@ export interface ResolvedSource {
    * load. Undefined in SSR / Node test fallback — `createRuntime` then
    * does the classic synchronous load.
    */
-  preloadedDocxSession?: ReturnType<typeof openDocxSync>;
+  preloadedDocxSession?: LoadedDocxEditorSession;
+  preloadedDocxDispose?: () => void;
+  /**
+   * Snapshot/session sources must be reopened asynchronously before the
+   * runtime paints. When Layer 01 returns a typed barrier, keep it here
+   * so the sync runtime can expose an export-blocking compatibility
+   * posture without trying a second legacy reopen.
+   */
+  preloadedSnapshotExportBarrier?: SnapshotExportBarrier;
   /**
    * L7 Phase 2.7 — when the editor-runtime-boundary probe finds a
    * laycache envelope in `/customXml/item1.xml`, its `graph` is stashed
@@ -149,11 +156,13 @@ type InternalWordReviewEditorRuntime = WordReviewEditorRuntime & {
 };
 
 type PackageBackedDocxSession = ReturnType<typeof openDocxSync>;
+type LoadedDocxEditorSession = ReturnType<typeof openDocxSync>;
 
 interface SnapshotExportBarrier {
   reason:
     | "missing_source_package_provenance"
-    | "invalid_source_package_provenance";
+    | "invalid_source_package_provenance"
+    | "snapshot_reopen_unavailable";
   message: string;
 }
 
@@ -302,6 +311,81 @@ export async function __resolveWordReviewEditorSource(
   };
 }
 
+function adaptOpenResultToLoadedSession(
+  openResult: OpenResult,
+): LoadedDocxEditorSession {
+  return {
+    initialSessionState: openResult.sessionState,
+    initialSnapshot: openResult.initialSnapshot,
+    readOnly: openResult.readOnly,
+    ...(openResult.fatalError !== undefined
+      ? { fatalError: openResult.fatalError }
+      : {}),
+    protectionSnapshot: openResult.protectionSnapshot,
+    exportDocx: openResult.exportDocx,
+    embeddedDocumentManifests: openResult.embeddedDocuments,
+    ...(openResult.initialEditorStatePayload !== undefined
+      ? {
+          initialEditorStatePayload:
+            openResult.initialEditorStatePayload as NonNullable<
+              LoadedDocxEditorSession["initialEditorStatePayload"]
+            >,
+        }
+      : {}),
+  };
+}
+
+function snapshotExportBarrierFromReopenBarrier(
+  barrier: ReopenBarrier,
+): SnapshotExportBarrier {
+  if (barrier.reason === "no-source-package") {
+    return {
+      reason: "missing_source_package_provenance",
+      message:
+        "DOCX export is blocked because this session was loaded without embedded source package provenance.",
+    };
+  }
+  return {
+    reason: "invalid_source_package_provenance",
+    message: barrier.message,
+  };
+}
+
+export async function __preloadSnapshotSourceForRuntime(args: {
+  documentId: string;
+  source: ResolvedSource;
+  editorBuild?: string;
+}): Promise<void> {
+  if (args.source.initialDocx !== undefined || args.source.preloadedDocxSession) {
+    return;
+  }
+
+  const snapshot =
+    args.source.initialSessionState ?? args.source.initialSnapshot;
+  if (!snapshot) {
+    args.source.preloadedSnapshotExportBarrier = {
+      reason: "missing_source_package_provenance",
+      message:
+        "DOCX export is blocked because this session does not carry a snapshot or session state to reopen.",
+    };
+    return;
+  }
+
+  const reopened = await new DocxSession().reopenFromSnapshot(snapshot, {
+    documentId: args.documentId,
+    sourceLabel: args.source.sourceLabel,
+    editorBuild: args.editorBuild ?? "dev",
+  });
+  if (isReopenBarrier(reopened)) {
+    args.source.preloadedSnapshotExportBarrier =
+      snapshotExportBarrierFromReopenBarrier(reopened);
+    return;
+  }
+
+  args.source.preloadedDocxSession = adaptOpenResultToLoadedSession(reopened);
+  args.source.preloadedDocxDispose = reopened.dispose;
+}
+
 export function __createFallbackRuntime(args: CreateRuntimeArgs): WordReviewEditorRuntime {
   return createRuntime(args);
 }
@@ -545,30 +629,7 @@ export function useEditorRuntimeBoundary(
               });
             },
           });
-          // Slice 5e-11 item-4: adapter maps `OpenResult` → the
-          // `LoadedDocxEditorSession` shape the downstream shell
-          // code expects. Two field-name mismatches exist:
-          // `sessionState` / `initialSessionState`, and
-          // `embeddedDocuments` / `embeddedDocumentManifests`.
-          const preloadView: ReturnType<typeof openDocxSync> = {
-            initialSessionState: openResult.sessionState,
-            initialSnapshot: openResult.initialSnapshot,
-            readOnly: openResult.readOnly,
-            ...(openResult.fatalError !== undefined
-              ? { fatalError: openResult.fatalError }
-              : {}),
-            protectionSnapshot: openResult.protectionSnapshot,
-            exportDocx: openResult.exportDocx,
-            embeddedDocumentManifests: openResult.embeddedDocuments,
-            ...(openResult.initialEditorStatePayload !== undefined
-              ? {
-                  initialEditorStatePayload:
-                    openResult.initialEditorStatePayload as NonNullable<
-                      ReturnType<typeof openDocxSync>["initialEditorStatePayload"]
-                    >,
-                }
-              : {}),
-          };
+          const preloadView = adaptOpenResultToLoadedSession(openResult);
           loadDisposeRef.current = openResult.dispose ?? null;
           if (cancelled) {
             openResult.dispose?.();
@@ -577,6 +638,7 @@ export function useEditorRuntimeBoundary(
           }
           recordPerfSample("loadSession.laycacheProbe");
           source.preloadedDocxSession = preloadView;
+          source.preloadedDocxDispose = openResult.dispose;
           if (pendingChartPreviewDocRef.current) {
             source.preloadedDocxSession.initialSessionState = {
               ...source.preloadedDocxSession.initialSessionState,
@@ -594,6 +656,27 @@ export function useEditorRuntimeBoundary(
           }
         }
 
+        if (
+          source.initialDocx === undefined &&
+          source.preloadedDocxSession === undefined &&
+          (source.initialSessionState !== undefined ||
+            source.initialSnapshot !== undefined)
+        ) {
+          await __preloadSnapshotSourceForRuntime({
+            documentId,
+            source,
+            editorBuild: "dev",
+          });
+          if (cancelled) {
+            source.preloadedDocxDispose?.();
+            source.preloadedDocxSession = undefined;
+            source.preloadedDocxDispose = undefined;
+            return;
+          }
+          loadDisposeRef.current =
+            source.preloadedDocxDispose ?? loadDisposeRef.current;
+        }
+
         const nextRuntime = createRuntime(
           {
             documentId,
@@ -822,10 +905,10 @@ function createRuntime(
     : undefined;
   const initialSessionState =
     args.source.initialSessionState ??
-    docxSession?.initialSessionState ??
     (args.source.initialSnapshot
       ? editorSessionStateFromPersistedSnapshot(args.source.initialSnapshot)
-      : editorSessionStateFromPersistedSnapshot(
+      : docxSession?.initialSessionState ??
+        editorSessionStateFromPersistedSnapshot(
           createFallbackPersistedSnapshot(
             args.documentId,
             args.source.sourceLabel ?? "Generated shell snapshot",
@@ -1087,6 +1170,7 @@ function createLoadingRuntimeBridge(input: {
     subscribeToEvents: () => () => undefined,
     emitBlockedCommand: () => undefined,
     emitTransientWarning: () => undefined,
+    now: () => new Date().toISOString(),
     getRenderSnapshot: () => {
       const progressive = input.progressiveSurfaceRef?.current;
       if (progressive == null) return input.snapshot;
@@ -1177,6 +1261,22 @@ function createLoadingRuntimeBridge(input: {
       getRailSegments: () => [],
       getAllRailSegments: () => [],
       getAllScopeCardModels: () => [],
+      getReviewOverlayLane: (kind) => ({
+        kind,
+        status: "unavailable",
+        entries: [],
+        revision: 0,
+        source: "unavailable",
+        reason: "overlay lanes are unavailable before runtime hydration",
+      }),
+      subscribeReviewOverlayLane: (kind) => {
+        if (kind === "presence") {
+          throw new Error(
+            "runtime.workflow.subscribeReviewOverlayLane: presence is awareness-owned; use the awareness-backed presence lane source",
+          );
+        }
+        return () => undefined;
+      },
     },
     geometry: inertGeometryFacet,
     getLayoutFacet: () => inertLayoutFacet,
@@ -1888,6 +1988,14 @@ function resolvePackageBackedExportSession(args: CreateRuntimeArgs): {
   session?: PackageBackedDocxSession;
   barrier?: SnapshotExportBarrier;
 } {
+  if (args.source.preloadedDocxSession) {
+    return { session: args.source.preloadedDocxSession };
+  }
+
+  if (args.source.preloadedSnapshotExportBarrier) {
+    return { barrier: args.source.preloadedSnapshotExportBarrier };
+  }
+
   const sourcePackage =
     args.source.initialSessionState?.sourcePackage ??
     args.source.initialSnapshot?.sourcePackage;
@@ -1901,47 +2009,13 @@ function resolvePackageBackedExportSession(args: CreateRuntimeArgs): {
     };
   }
 
-  try {
-    const bytes = decodePersistedSourcePackageBytes(sourcePackage);
-    if (!hasValidPersistedSourcePackageDigest(sourcePackage, bytes)) {
-      return {
-        barrier: {
-          reason: "invalid_source_package_provenance",
-          message:
-            "DOCX export is blocked because the embedded source package provenance failed its integrity check.",
-        },
-      };
-    }
-
-    const session = openDocxSync({
-      documentId: args.documentId,
-      sourceLabel: sourcePackage.sourceLabel ?? args.source.sourceLabel,
-      bytes,
-      editorBuild:
-        args.source.initialSessionState?.editorBuild ??
-        args.source.initialSnapshot?.editorBuild ??
-        "dev",
-    });
-    if (session.readOnly || session.fatalError) {
-      return {
-        barrier: {
-          reason: "invalid_source_package_provenance",
-          message:
-            "DOCX export is blocked because the embedded source package provenance is no longer loadable as a valid package-backed session.",
-        },
-      };
-    }
-
-    return { session };
-  } catch {
-    return {
-      barrier: {
-        reason: "invalid_source_package_provenance",
-        message:
-          "DOCX export is blocked because the embedded source package provenance could not be decoded into a package-backed session.",
-      },
-    };
-  }
+  return {
+    barrier: {
+      reason: "snapshot_reopen_unavailable",
+      message:
+        "DOCX export is blocked because the snapshot source package was not reopened before runtime creation.",
+    },
+  };
 }
 
 function applySessionExportBarrier(