@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/session/types.ts

@@ -0,0 +1,499 @@
+/**
+ * Layer 01 public type surface for `src/session/**`.
+ *
+ * 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.
+ *
+ * P6 clean: imports only from `src/api/**` (type-only), `src/model/**`,
+ * `src/io/**`, and `src/preservation/**`.
+ */
+
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+} from "../model/canonical-document.ts";
+import type {
+  CompatibilityReport,
+  EditorError,
+  EditorHostAdapter,
+  EditorSurfaceSnapshot,
+  ExportDocxOptions,
+  ExportResult,
+  LoadStage,
+  PersistedEditorSnapshot,
+  ProtectionSnapshot,
+} from "../api/public-types.ts";
+import type { EmbeddingKind } from "../io/ooxml/classify-embedding.ts";
+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.
+export type {
+  EditorHostAdapter,
+  ExportDocxOptions,
+  ExportResult,
+  LoadStage,
+  PersistedEditorSnapshot,
+};
+
+// ---------------------------------------------------------------------------
+// Runtime-side projection ports
+// ---------------------------------------------------------------------------
+
+/**
+ * Input passed by the session load path to a caller-supplied
+ * `ProgressiveSurfaceProjector`. The session carries the body-stage
+ * normalized root content plus the viewport accounting it has already
+ * computed; the projector assembles a provisional canonical envelope
+ * and calls the runtime-layer `createEditorSurfaceSnapshot` with a
+ * default selection + `MAIN_STORY_TARGET`.
+ *
+ * Kept deliberately minimal — extending the contract requires a
+ * coordinated change in the session load path + every consumer.
+ */
+export interface ProgressiveSurfaceProjectorInput {
+  /** Body-stage normalized root content. */
+  rootContent: DocumentRootNode;
+  /** Document id stamped on the provisional canonical envelope. */
+  documentId: string;
+  /** First-paint viewport size (blocks in the windowed view). */
+  blocksRealized: number;
+  /** Total block count in the normalized document. */
+  blocksTotal: number;
+}
+
+/**
+ * Runtime-side port invoked by the session to synthesize the
+ * progressive surface without pulling `src/runtime/**` into the session
+ * layer. The UI boundary implements it by binding in
+ * `createEditorSurfaceSnapshot` + a default selection + the main story
+ * target; tests bind the same runtime helper directly.
+ */
+export type ProgressiveSurfaceProjector = (
+  input: ProgressiveSurfaceProjectorInput,
+) => EditorSurfaceSnapshot;
+
+// ---------------------------------------------------------------------------
+// Reserved Layer-01 options + results (architecture §Public entry points)
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for `DocxSession.open(bytes, opts)`.
+ *
+ * Field list mirrors the legacy `LoadDocxEditorSessionOptions` minus
+ * `bytes` (now a positional arg) and minus options that are specific to
+ * the internal async scheduler (the session class handles scheduler
+ * selection itself). Hosts pass their adapter and optional telemetry
+ * bus; everything else is wired from the session internals.
+ */
+export interface OpenOptions {
+  /**
+   * Stable document identifier minted by the host. Flows through to
+   * `EditorSessionState.documentId` + `OpenResult.sessionState`.
+   */
+  documentId?: string;
+  /** Human-readable label, surfaced in telemetry only. */
+  sourceLabel?: string;
+  /** Optional editor build identifier; default is the package version. */
+  editorBuild?: string;
+  /** Host adapter for chart previews, session storage, logging. */
+  hostAdapter?: EditorHostAdapter;
+  /**
+   * P8 Step 7 — explicit opt-in for embedded-document offload at
+   * load time. When `true` AND `hostAdapter.storeEmbeddedDocument`
+   * is defined, the session materialises every `offloadable`
+   * embedded document, computes sha-256, calls the adapter, and
+   * persists the `bw:embeddings` customXml reference + inline-bytes
+   * fallback.
+   *
+   * Default `false`. Offload is OFF unless the host opts in
+   * explicitly — supplying a `hostAdapter` for other purposes
+   * (chart-preview, save-session, log-event) never silently
+   * activates offload work.
+   *
+   * Rationale: per cross-layer-coord-04 §1.13, sha-256 +
+   * base64-encode of a large (2.5 MB) offloadable embedding adds
+   * ~300 ms to cold-open. Hosts that genuinely want offload opt in;
+   * hosts that only want the adapter for other purposes pay zero.
+   */
+  offloadEmbeddedDocuments?: boolean;
+  /** Per-stage load instrumentation callback. */
+  onLoadStage?: (stage: LoadStage, durationMs: number) => void;
+  /**
+   * Optional telemetry bus. When supplied, the loader brackets every
+   * `parseMainDocumentXml` invocation with `setActiveParseTelemetryBus`
+   * so the parser emits on the `parse` channel. Typically the same
+   * bus is also passed to `createDocumentRuntime({ telemetryBus })`
+   * so one bus spans both load and runtime observers.
+   *
+   * Type signature uses `unknown` so the public session barrel does
+   * not drag in runtime-layer type dependencies; the loader narrows
+   * to the concrete `TelemetryBus` shape internally.
+   */
+  telemetryBus?: unknown;
+  /**
+   * L7 Phase 2.5 Plan B B.6b — optional laycache envelope. When
+   * supplied, the loader skips the five expensive parse stages and
+   * uses the envelope's canonical document directly. Prefer
+   * `tryLaycacheEnvelope: true` over this — with that option the
+   * session runs the probe itself. Callers still wanting to supply
+   * a pre-probed envelope (e.g. a custom caching layer) can pass it
+   * here; when both are set, this wins.
+   *
+   * Type is `unknown` so the session barrel does not drag runtime
+   * layer types into its surface; the loader narrows to the concrete
+   * `CacheEnvelope` internally.
+   */
+  laycacheEnvelope?: unknown;
+  /**
+   * Run `tryReadLaycacheEnvelope(bytes)` inside `DocxSession.open()`
+   * before dispatching to the legacy loader. When the probe returns a
+   * validated envelope, the loader short-circuits the five expensive
+   * parse stages and uses the cached `canonicalDocument` directly;
+   * when it returns null, the full parse runs. The probe itself is
+   * ~20–50 ms on extra-large documents.
+   *
+   * CLAUDE.md Performance Invariant 10: do not insert blocking work
+   * between the probe and the loader. Setting this to `true` keeps
+   * the two colocated inside the session; callers MUST NOT run a
+   * manual probe before `open()` and then also set this flag.
+   *
+   * Default: `false` (skip the probe; full parse). `laycacheEnvelope`
+   * takes precedence when both are set.
+   */
+  tryLaycacheEnvelope?: boolean;
+  /**
+   * Callback that runs the laycache-envelope probe on the source
+   * bytes. When `tryLaycacheEnvelope: true` is set AND this callback
+   * is supplied, the session invokes it (before the full parse) to
+   * check whether the package carries a pre-computed laycache
+   * envelope. On a hit, the returned `{ envelope }` is used as the
+   * short-circuit source; on a miss, full parse runs.
+   *
+   * Typed as a function returning `unknown` so this session-layer
+   * option does not transit `src/runtime/prerender/**` (the concrete
+   * `CacheEnvelope` type + `tryReadLaycacheEnvelope` implementation
+   * both live under runtime, which §P6 forbids session imports
+   * against). The shell / prerender entry-point wires the concrete
+   * probe; session narrows opaquely.
+   *
+   * Slice 5e-11 item-1 introduced this DI seam to retire the last
+   * `src/session/session.ts → src/runtime/prerender/customxml-probe.ts`
+   * debt exception (cross-layer-coord-01 §1).
+   */
+  laycacheProbe?: (
+    bytes: Uint8Array | ArrayBuffer,
+  ) => Promise<{ envelope: unknown } | null>;
+  /**
+   * Host-adapter Stage 0B.1: optional callback invoked when chart
+   * previews have finished resolving off the critical path. Fires
+   * with the canonical document that carries the resolved previews;
+   * the UI uses this to hydrate the runtime's chart-preview facet
+   * without blocking first paint.
+   *
+   * CLAUDE.md Performance Invariant 9 — do NOT `await` this, and do
+   * not rely on it for first-paint correctness. When omitted,
+   * chart-preview synthesis runs inline on the load path.
+   */
+  onChartPreviewsReady?: (resolvedDoc: CanonicalDocument) => void;
+  /**
+   * C2c progressive-snapshot callback. When supplied AND no cached
+   * laycache envelope is in play, the loader fires this once after
+   * the body-normalize stage with a viewport-windowed surface snapshot
+   * so the UI can paint the first page before the full session
+   * resolves. CLAUDE.md Performance Invariant 8 pins the caller-side
+   * wiring: the callback MUST be fed through `React.startTransition`
+   * and the state slot MUST be cleared before committing the full
+   * runtime, or the progressive render turns into a blocking flicker.
+   *
+   * Only fires on the cold path — `laycacheEnvelope` set (either
+   * explicitly or via `tryLaycacheEnvelope`) skips the synthesis
+   * because the short-circuit is already fast enough that a
+   * pre-commit adds more overhead than it saves.
+   */
+  onProgressiveSnapshot?: (partial: {
+    /**
+     * Projected surface. Only populated when `surfaceProjector` is also
+     * supplied — the session layer does not own surface projection
+     * (architecture §P6: session imports are forbidden from
+     * `src/runtime/**`). Consumers that need the projected surface
+     * either supply a `surfaceProjector` (recommended) or project the
+     * surface themselves from the normalized content available on the
+     * final `OpenResult`.
+     */
+     surface?: EditorSurfaceSnapshot;
+    phase: "viewport";
+    blocksRealized: number;
+    blocksTotal: number;
+  }) => void;
+  /**
+   * Runtime-side port that projects a viewport-windowed
+   * `EditorSurfaceSnapshot` from the body-stage normalized content.
+   *
+   * When supplied with `onProgressiveSnapshot`, the session invokes
+   * this port to synthesize the surface before firing the callback.
+   * When absent, the session skips the projection and the callback
+   * fires with `surface: undefined`. This keeps the session layer
+   * P6-clean — surface projection lives in `src/runtime/**`; the
+   * session never reaches into it.
+   *
+   * The `editor-runtime-boundary.ts` load path binds the real
+   * projector (`createEditorSurfaceSnapshot` + default selection +
+   * `MAIN_STORY_TARGET`) and passes it through here.
+   */
+  surfaceProjector?: ProgressiveSurfaceProjector;
+  /**
+   * Override the load scheduler backend. When supplied, the session
+   * constructs the internal scheduler with `backendOverride` set to
+   * this value; otherwise auto-detect picks the best backend for the
+   * current environment (scheduler.yield → MessageChannel →
+   * setTimeout → sync).
+   *
+   * The only caller today is `prerenderDocument` in
+   * `src/runtime/prerender/**`, which forces `"sync"` so the staged
+   * loader runs without yielding in Node / SSR contexts where
+   * determinism matters. Hosts that open interactively should omit
+   * this field and let auto-detect run.
+   */
+  schedulerBackend?: LoadSchedulerBackend;
+}
+
+/**
+ * Options for `DocxSession.export(doc, opts)`.
+ *
+ * Reserved as an alias of `ExportDocxOptions` for now. Slice 4 wires
+ * export orchestration into `src/session/export/**` and promotes any
+ * new fields here; the alias keeps the public surface stable.
+ */
+export type ExportOptions = ExportDocxOptions;
+
+/**
+ * Options for `DocxSession.validate(doc, opts)`.
+ *
+ * Reserved for Slice 4's export-validation work; the validate entry
+ * runs the compatibility engine against a provided canonical document
+ * without opening a package. Currently empty; fields expand as the
+ * validator wires in.
+ */
+export interface ValidateOptions {
+  /**
+   * Optional profile selector — future validator can emit different
+   * report shapes for different target consumers (UI diagnostics panel
+   * vs. CI gate vs. export-blocking check).
+   */
+  profile?: "default" | "export-blocking";
+}
+
+/**
+ * Reserved opaque snapshot of the preservation store as it stood at
+ * open time. Carries enough information to drive round-trip on export.
+ *
+ * The concrete shape is an alias of the existing `PreservationStore`
+ * model type; exposed here so Layer 01 owns the snapshot contract even
+ * while the store implementation lives in `src/preservation/**` /
+ * `src/model/**`.
+ */
+export type PreservationSnapshot = PreservationStore;
+
+/**
+ * Result of `DocxSession.open(bytes, opts)`. Mirrors the architecture
+ * 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.
+ */
+export interface OpenResult {
+  readonly sessionState: EditorSessionState;
+  readonly canonicalDocument: CanonicalDocument;
+  readonly compatibility: CompatibilityReport;
+  readonly preservation: PreservationSnapshot;
+  readonly embeddedDocuments: readonly EmbeddedDocumentManifest[];
+  /**
+   * `true` when the source package declared document protection that
+   * makes editing invalid on open (e.g. `readOnly` protection
+   * setting). Callers use this to surface a non-interactive view of
+   * the document without reaching into the transitional legacy view.
+   *
+   * Slice 5e-1 promoted this off `LegacyOpenView`.
+   */
+  readonly readOnly: boolean;
+  /**
+   * Populated when the parse pipeline produced an unrecoverable error
+   * that leaves the session unusable for editing (e.g. OPC structure
+   * rejected, main-document.xml not parseable). The session is still
+   * returned so callers can show a diagnostic snapshot; presence of
+   * this field signals "do not enter the normal runtime path".
+   *
+   * Slice 5e-1 promoted this off `LegacyOpenView`.
+   */
+  readonly fatalError?: EditorError;
+  /**
+   * Snapshot of `/word/settings.xml` document-protection state at
+   * open time. Downstream code uses this to gate command availability
+   * without re-reading the package.
+   *
+   * Slice 5e-1 promoted this off `LegacyOpenView`.
+   */
+  readonly protectionSnapshot: ProtectionSnapshot;
+  /**
+   * When an internal `tryLaycacheEnvelope` probe hit OR the caller
+   * supplied an explicit `laycacheEnvelope` option, the resolved
+   * envelope is surfaced here so callers can extract auxiliary data
+   * such as the cached layout graph (for `seedLayoutCache`) without
+   * re-running the probe.
+   *
+   * Typed `unknown` so the session barrel does not drag runtime-layer
+   * `CacheEnvelope` types into its public surface; callers cast to
+   * the concrete shape at the consumption site.
+   */
+  readonly laycacheEnvelope?: unknown;
+  /**
+   * Persisted snapshot of the initial session state. Stable
+   * serialization envelope that hosts can hand to `load()` on a later
+   * mount to rehydrate the same document. Used by snapshot-based
+   * persistence flows (session-bootstrap, validator orchestrator,
+   * debug harness). Graduated from `LegacyOpenView.initialSnapshot`
+   * in Slice 5e-11 item-4.
+   */
+  readonly initialSnapshot: PersistedEditorSnapshot;
+  /**
+   * Schema-1.2 editor-state payload parsed from the source package's
+   * `customXml/item1.xml` at open time, if present. Hosts use this
+   * to rehydrate per-document editor overlays (workflow metadata,
+   * scope definitions, host annotations). Present only when the
+   * source package carried the schema-1.2 envelope; absent for
+   * non-workflow-enabled documents.
+   *
+   * Graduated from `LegacyOpenView.initialEditorStatePayload` per the
+   * L06 `OpenResult` shape decision (2026-04-22, `docs/architecture/
+   * 06-workflow-review.md` §"Open-time surface").
+   *
+   * Typed `unknown` so the session barrel does not drag the
+   * `EditorStatePayload` type from `src/io/ooxml/workflow-payload.ts`
+   * into its public surface; callers cast at the consumption site.
+   */
+  readonly initialEditorStatePayload?: unknown;
+  /**
+   * Export closure bound to this session's captured
+   * `ImportedDocxState`. Equivalent to
+   * `docxSession.export(sessionState, opts)` — the convenience
+   * method avoids requiring hosts to retain a reference to the
+   * `DocxSession` instance when they only hold the `OpenResult`.
+   * Same result, same byte-reuse fast path, same reconstitute
+   * pipeline.
+   */
+  readonly exportDocx: (
+    sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
+    opts?: ExportOptions,
+  ) => Promise<ExportResult>;
+  /**
+   * Releases any pending idle callbacks the load scheduler queued
+   * during parse. Callers SHOULD invoke on unmount to cancel
+   * in-flight off-critical-path work (chart-preview resolution,
+   * etc.) — CLAUDE.md Performance Invariant 9. Optional because the
+   * sync scheduler backend (used by `prerenderDocument`) has nothing
+   * to cancel.
+   *
+   * Equivalent to calling `docxSession.dispose()` on the owning
+   * `DocxSession` instance.
+   */
+  readonly dispose?: () => void;
+}
+
+/**
+ * Sentinel returned by `DocxSession.reopenFromSnapshot()` when the
+ * rehydrate path cannot produce a usable `OpenResult`. Never thrown —
+ * always returned as a data value so callers can diff + display
+ * without a try/catch envelope.
+ *
+ * Discriminant: presence of `reason` — the `OpenResult` shape has no
+ * `reason` field. Consumers: `if ("reason" in result) { /* barrier *\/ }`.
+ */
+export interface ReopenBarrier {
+  /**
+   * Coarse-grained reason enum. Stable across minor versions;
+   * additive changes only. Hosts typically map this to a localized
+   * UI message and/or an audit event.
+   */
+  readonly reason:
+    | "no-source-package"
+    | "invalid-digest"
+    | "corrupted-bytes"
+    | "unsupported-schema";
+  /**
+   * Human-readable explanation tied to `reason`. Stable enough for
+   * surfacing verbatim in diagnostic logs. Not localised.
+   */
+  readonly message: string;
+}
+
+/**
+ * Type guard helper — narrows `OpenResult | ReopenBarrier` to the
+ * barrier arm. The discriminant is the presence of `reason`.
+ */
+export function isReopenBarrier(
+  result: OpenResult | ReopenBarrier,
+): result is ReopenBarrier {
+  return (result as Partial<ReopenBarrier>).reason !== undefined;
+}
+
+/**
+ * Result of `DocxSession.validate(doc, opts)`.
+ *
+ * Reserved shape — Slice 4 implements the runner and decides whether
+ * findings carry line/column context or only stable codes. The field
+ * list here is the minimum the architecture needs: a severity-tagged
+ * record list plus a pass/fail verdict.
+ */
+export interface ValidationReport {
+  readonly ok: boolean;
+  readonly findings: readonly ValidationFinding[];
+}
+
+export interface ValidationFinding {
+  readonly code: string;
+  readonly severity: "info" | "warning" | "error";
+  readonly message: string;
+  readonly featureKey?: string;
+}
+
+// ---------------------------------------------------------------------------
+// P8 · Embedded-document manifest (architecture §P8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-entry shape for every embedded OLE object or `w:altChunk` target
+ * discovered on open. Matches the reservation at
+ * `docs/architecture/01-package-session.md` § Public entry points:
+ *   - `id` stable across open/export (derived from content fingerprint)
+ *   - `kind` three-way classification from `classifyEmbedding()`
+ *   - `progId`, `mimeType`, `filename` are signal-best-effort metadata
+ *   - `size` is the byte length of the underlying package part
+ *   - `relationshipId` points to the owning rId in the main-document
+ *     relationships (or the containing story for altChunk targets)
+ *   - `bytes()` is lazy — the part bytes are materialized on demand,
+ *     never eagerly copied at open time (Performance Invariant 9)
+ */
+export interface EmbeddedDocumentManifest {
+  readonly id: string;
+  readonly kind: EmbeddingKind;
+  readonly progId?: string;
+  readonly mimeType?: string;
+  readonly filename?: string;
+  readonly size: number;
+  readonly relationshipId: string;
+  readonly bytes: () => Uint8Array;
+}

package/src/shell/chart-snapshots.ts

@@ -0,0 +1,96 @@
+/**
+ * Shell helper — chart-snapshot projection.
+ *
+ * Walks a `CanonicalDocument` and projects the chart-preview inlines into
+ * public-API `ChartSnapshot` records. Consumers: the React editor ref
+ * (`getChartSnapshots` / `getChartSnapshot`) and any headless consumer
+ * that needs chart reads without mounting the editor.
+ *
+ * This lives in `src/shell/` rather than `src/ui/` because it's a pure
+ * projection between the canonical document (L02) and the public API
+ * (L07 reads) — no DOM, no React, no presentation. `src/ui/` is the
+ * presentation layer; keeping this helper outside it retires two
+ * substrate-reach-through imports (`runtime/chart/chart-model-store` +
+ * `runtime/chart/chart-snapshot`) from the Layer-11 boundary register.
+ */
+
+import type { CanonicalDocument } from "../model/canonical-document.ts";
+import type { ChartSnapshot } from "../api/public-types.ts";
+import { stableChartId } from "../runtime/chart/chart-model-store.ts";
+import { projectChartSnapshot } from "../runtime/chart/chart-snapshot.ts";
+
+type BlockArray = CanonicalDocument["content"]["children"];
+
+export function collectChartSnapshots(doc: CanonicalDocument): ChartSnapshot[] {
+  const results: ChartSnapshot[] = [];
+  collectChartSnapshotsFromBlocks(doc.content.children, results);
+  return results;
+}
+
+/**
+ * Walk the canonical document, compute each chart_preview's stableChartId,
+ * and project a snapshot for the first matching id. Short-circuits on
+ * match so the happy path is O(k) in blocks-until-match rather than the
+ * O(N) the `collect().find()` fallback incurred for every ref call. For
+ * hosts that call `getChartSnapshot` in a tight loop over many chartIds,
+ * this reduces the cost from O(N²) to O(N·k).
+ */
+export function lookupChartSnapshot(
+  doc: CanonicalDocument,
+  chartId: string,
+): ChartSnapshot | null {
+  return lookupChartSnapshotInBlocks(doc.content.children, chartId);
+}
+
+function lookupChartSnapshotInBlocks(
+  blocks: BlockArray,
+  chartId: string,
+): ChartSnapshot | null {
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      for (const inline of block.children) {
+        if (inline.type === "chart_preview" && inline.parsedData) {
+          const id = stableChartId(inline.rawXml);
+          if (id === chartId) {
+            return projectChartSnapshot(id, inline.parsedData);
+          }
+        }
+      }
+    } else if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const found = lookupChartSnapshotInBlocks(cell.children, chartId);
+          if (found) return found;
+        }
+      }
+    } else if (block.type === "sdt" || block.type === "custom_xml") {
+      const found = lookupChartSnapshotInBlocks(block.children, chartId);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function collectChartSnapshotsFromBlocks(
+  blocks: BlockArray,
+  results: ChartSnapshot[],
+): void {
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      for (const inline of block.children) {
+        if (inline.type === "chart_preview" && inline.parsedData) {
+          const chartId = stableChartId(inline.rawXml);
+          results.push(projectChartSnapshot(chartId, inline.parsedData));
+        }
+      }
+    } else if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectChartSnapshotsFromBlocks(cell.children, results);
+        }
+      }
+    } else if (block.type === "sdt" || block.type === "custom_xml") {
+      collectChartSnapshotsFromBlocks(block.children, results);
+    }
+  }
+}

package/src/shell/media-previews.ts

@@ -0,0 +1,85 @@
+/**
+ * Shell helper — media-preview catalog construction.
+ *
+ * Builds the inline `data:` URLs the mounted editor feeds to image
+ * render paths. Reads the persisted source-package bytes, verifies the
+ * digest, walks the OPC parts table, and projects each canonical media
+ * item into a `MediaPreviewDescriptor`.
+ *
+ * SVG is included in the browser-safe content-type allowlist — Chromium
+ * sandboxes SVGs loaded via `<img src="data:image/svg+xml;base64,…">`
+ * (no script execution, no external refs), so XSS surface matches PNG.
+ * Required for CCEP-synthesized chart previews (Stage 0B) and hosts
+ * that ship `.svg` inside `word/media/`.
+ *
+ * Lives in `src/shell/` so the three `io/**` substrate imports stay
+ * outside the L11 boundary register — package decoding is a shell
+ * concern, not a presentation one.
+ */
+
+import type { CanonicalDocument } from "../model/canonical-document.ts";
+import type { PersistedSourcePackage } from "../model/snapshot.ts";
+import type { MediaPreviewDescriptor } from "../ui-tailwind/editor-surface/pm-state-from-snapshot";
+import {
+  decodePersistedSourcePackageBytes,
+  hasValidPersistedSourcePackageDigest,
+} from "../io/source-package-provenance.ts";
+import { readOpcPackage } from "../io/opc/package-reader.ts";
+
+const BROWSER_SAFE_PREVIEW_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/gif",
+  "image/webp",
+  "image/bmp",
+  "image/svg+xml",
+]);
+
+export function buildMediaPreviews(
+  sourcePackage: PersistedSourcePackage | null | undefined,
+  canonicalDocument: CanonicalDocument,
+): Record<string, MediaPreviewDescriptor> {
+  if (!sourcePackage) {
+    return {};
+  }
+  try {
+    const bytes = decodePersistedSourcePackageBytes(sourcePackage);
+    if (!hasValidPersistedSourcePackageDigest(sourcePackage, bytes)) {
+      return {};
+    }
+    const opc = readOpcPackage(bytes);
+    const previews: Record<string, MediaPreviewDescriptor> = {};
+    for (const item of Object.values(canonicalDocument.media.items)) {
+      const contentType = item.contentType?.toLowerCase();
+      const part = opc.parts.get(item.packagePartName);
+      if (
+        !part?.bytes ||
+        !contentType ||
+        !BROWSER_SAFE_PREVIEW_TYPES.has(contentType)
+      ) {
+        continue;
+      }
+      previews[item.mediaId] = {
+        src: createImageDataUrl(contentType, part.bytes),
+        ...(item.widthEmu !== undefined ? { widthEmu: item.widthEmu } : {}),
+        ...(item.heightEmu !== undefined ? { heightEmu: item.heightEmu } : {}),
+      };
+    }
+    return previews;
+  } catch {
+    return {};
+  }
+}
+
+function createImageDataUrl(contentType: string, bytes: Uint8Array): string {
+  return `data:${contentType};base64,${bytesToBase64(bytes)}`;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    binary += String.fromCharCode(bytes[index] ?? 0);
+  }
+  return btoa(binary);
+}