@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/api/v3/runtime/document.ts

@@ -0,0 +1,282 @@
+/**
+ * @endStateApi v3 — `runtime.document` family.
+ *
+ * See docs/reference/public-api.md § runtime.document. Three functions:
+ * `load` (partial — runtime pre-load is the caller's responsibility; v3
+ * exposes a re-mount semantic later), `export` (live; delegates to
+ * `runtime.exportDocx`), `validate` (partial; read live, write mock).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type {
+  EditorError,
+  ExportDocxOptions,
+  ExportResult,
+  PersistedEditorSnapshot,
+} from "../../public-types.ts";
+import { mockPayload } from "../_mocks.ts";
+import type { ApiV3FnMetadata, MockPayload } from "../_layer-metadata.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+import { loadDocxSessionAsync } from "../../../session/import/loader.ts";
+import { createLoadScheduler } from "../../../io/load-scheduler.ts";
+
+/* ================================================================== */
+/*  load                                                              */
+/* ================================================================== */
+
+export interface LoadInput {
+  readonly bytes: Uint8Array | ArrayBuffer;
+  /**
+   * Document identity for the newly-loaded session. Required by
+   * `loadDocxSessionAsync` — when omitted, v3 synthesizes a stable
+   * `v3-load-<timestamp>` id so agents calling without host-assigned
+   * ids still get deterministic-enough output.
+   */
+  readonly documentId?: string;
+  readonly sourceLabel?: string;
+}
+
+/**
+ * Live result of loading a DOCX package via the session-layer loader
+ * (`src/session/import/loader.ts::loadDocxSessionAsync`). Under the
+ * L07 Option-B contract (arch §R8) v3 does NOT construct a new
+ * `DocumentRuntime` — `createDocumentRuntime` stays synchronous and
+ * requires a fully-loaded `EditorSessionState`. The v3 `load()`
+ * returns the serializable `snapshot` + status so callers can mount
+ * a new runtime themselves or persist / rehydrate via
+ * `DocxSession.reopenFromSnapshot` (L01 coord §2).
+ *
+ * Every field is live from the actual parse:
+ *   - `documentId` — echoes the input (or synthesized default).
+ *   - `bytes` — byte-length of the source package.
+ *   - `readOnly` — protection state the loader detected.
+ *   - `embeddedDocumentsCount` — count of embedded sub-documents
+ *     discovered via P8 embedded-document discovery.
+ *   - `snapshot` — the `PersistedEditorSnapshot` the loader produced.
+ *   - `fatalError` — present when `status === "fatal"`.
+ *   - `status` — `"loaded"` on success, `"fatal"` when the package
+ *     couldn't be parsed (corrupt bytes, unsupported schema, etc.).
+ */
+export interface LoadResult {
+  readonly documentId: string;
+  readonly bytes: number;
+  readonly readOnly: boolean;
+  readonly embeddedDocumentsCount: number;
+  readonly snapshot: PersistedEditorSnapshot;
+  readonly fatalError?: EditorError;
+  readonly status: "loaded" | "fatal";
+}
+
+export const loadMetadata: ApiV3FnMetadata = {
+  name: "runtime.document.load",
+  status: "live",
+  sourceLayer: "package-session",
+  // Full live — direct delegation to loadDocxSessionAsync. No adapter
+  // debt: v3 doesn't construct a runtime (Option B contract, §R8),
+  // but the parse itself is the shipped session-layer contract.
+  // Returns the serializable snapshot + fatalError + readOnly fields
+  // the loader produced; v3 is a thin shape-projection over that.
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-document-load-live-post-eb7d14fa",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "surface-refresh", expectedDelta: "editor surface replaces with newly-loaded document" },
+  agentMetadata: { readOrMutate: "compound", boundedScope: "session", auditCategory: "document-load" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.document.load. Graduation (2026-04-22, post-eb7d14fa): `live` via direct delegation to `loadDocxSessionAsync` (src/session/import/loader.ts). Returns a PersistedEditorSnapshot the caller can pass to DocxSession.reopenFromSnapshot or persist for later rehydrate. Note per arch §R8 Option B: v3 does NOT construct the receiving DocumentRuntime — that's the caller's job via createDocumentRuntime(initialSessionState).",
+};
+
+/* ================================================================== */
+/*  export                                                            */
+/* ================================================================== */
+
+export const exportMetadata: ApiV3FnMetadata = {
+  name: "runtime.document.export",
+  status: "live",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "services/debug/lib/session-manager.test.ts",
+    probeScript: "services/debug/scripts/probe-channel-emissions.ts",
+    commit: "6aca0666",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "toast", expectedDelta: "toast shows export bytes size + completion" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "document-export" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§Runtime API § runtime.document.export",
+};
+
+/* ================================================================== */
+/*  validate                                                          */
+/* ================================================================== */
+
+export interface ValidateResult {
+  readonly reportVersion: "compatibility-report/1";
+  readonly blockExport: boolean;
+  readonly warningCount: number;
+  readonly errorCount: number;
+  readonly featureEntriesCount: number;
+  readonly interactionGuard: {
+    readonly mode: string;
+    readonly readOnly: boolean;
+  };
+  readonly __mock?: true;
+}
+
+export const validateMetadata: ApiV3FnMetadata = {
+  name: "runtime.document.validate",
+  status: "live-with-adapter",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "phase-p-prime",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "hash",
+    shapeDescription: "Fallback ValidateResult with zeroed counts when any of the three runtime reads is unavailable; never returned on a healthy runtime.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "warning-added", expectedDelta: "compatibility drawer summary updates" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "document-validate" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.document.validate. Adapter composes three shipped runtime reads — getCompatibilityReport() + getWarnings() + getInteractionGuardSnapshot() — into one bundled ValidateResult. Promotes to `live` when a first-class runtime.validate() lands.",
+};
+
+/* ================================================================== */
+/*  family factory                                                    */
+/* ================================================================== */
+
+export function createDocumentFamily(runtime: RuntimeApiHandle) {
+  return {
+    async load(input: LoadInput): Promise<LoadResult> {
+      // @endStateApi — live. Delegates directly to the session-layer
+      // loader `loadDocxSessionAsync`. v3 projects the returned
+      // `LoadedDocxEditorSession` into the serializable `LoadResult`
+      // shape — drops the `exportDocx` closure (R5: no runtime-
+      // instance leakage) and surfaces `snapshot` + fatalError + read-
+      // only for callers that mount via `createDocumentRuntime(
+      // initialSessionState)` themselves (Option B, §R8) or rehydrate
+      // via `DocxSession.reopenFromSnapshot(snapshot)` (L01 coord §2).
+      const byteLength = input.bytes instanceof Uint8Array
+        ? input.bytes.byteLength
+        : input.bytes.byteLength;
+      const documentId = input.documentId ?? `v3-load-${Date.now()}`;
+      const loaded = await loadDocxSessionAsync({
+        bytes: input.bytes,
+        documentId,
+        ...(input.sourceLabel ? { sourceLabel: input.sourceLabel } : {}),
+        scheduler: createLoadScheduler(),
+        telemetryBus: runtime.debug.bus,
+      });
+      const result: LoadResult = {
+        documentId,
+        bytes: byteLength,
+        readOnly: loaded.readOnly,
+        embeddedDocumentsCount: loaded.embeddedDocumentManifests?.length ?? 0,
+        snapshot: loaded.initialSnapshot,
+        status: loaded.fatalError ? "fatal" : "loaded",
+        ...(loaded.fatalError ? { fatalError: loaded.fatalError } : {}),
+      };
+      emitUxResponse(runtime, {
+        apiFn: loadMetadata.name,
+        intent: loadMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: loadMetadata.uxIntent.expectedDelta,
+        actualDelta: {
+          kind: "surface-refresh",
+          payload: { documentId: result.documentId, bytes: result.bytes, status: result.status },
+        },
+      });
+      return result;
+    },
+
+    async export(options?: ExportDocxOptions): Promise<ExportResult> {
+      // @endStateApi — live. Delegates to the shipped runtime export path.
+      const result = await runtime.exportDocx(options);
+      emitUxResponse(runtime, {
+        apiFn: exportMetadata.name,
+        intent: exportMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: exportMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "toast", payload: { bytes: result.bytes?.byteLength ?? 0 } },
+      });
+      return result;
+    },
+
+    validate(): ValidateResult & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. Composes three shipped runtime
+      // reads into a bundled ValidateResult:
+      //   - getCompatibilityReport() for blockExport + counts + feature entries
+      //     (with getRenderSnapshot().compatibility as a secondary fallback)
+      //   - getWarnings() augments the warning count with runtime-emitted ones
+      //   - getInteractionGuardSnapshot() for mode + readOnly
+      // Falls back to a mock-flagged shape only when both the compat read
+      // and the guard read are unavailable (e.g. pre-mount). The adapter
+      // promotes to `live` when a first-class runtime.validate() surfaces.
+      const report = runtime.getCompatibilityReport() as
+        | {
+            blockExport?: boolean;
+            warningCount?: number;
+            errorCount?: number;
+            featureEntries?: ReadonlyArray<unknown>;
+          }
+        | undefined
+        | null;
+      const snapshotCompat = runtime.getRenderSnapshot().compatibility;
+      const bundledReport = report ?? snapshotCompat;
+      const warnings = runtime.getWarnings();
+      const guard = runtime.getInteractionGuardSnapshot() as
+        | { mode?: string; readOnly?: boolean }
+        | undefined
+        | null;
+      if (!bundledReport && !guard) {
+        const fallback = mockPayload(
+          "no compatibility report or interaction guard available (pre-mount or test double)",
+          "ValidateResult",
+          {
+            reportVersion: "compatibility-report/1" as const,
+            blockExport: false,
+            warningCount: 0,
+            errorCount: 0,
+            featureEntriesCount: 0,
+            interactionGuard: { mode: "unknown", readOnly: false },
+          },
+        );
+        emitUxResponse(runtime, {
+          apiFn: validateMetadata.name,
+          intent: validateMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "mock",
+          uiVisible: true,
+          expectedDelta: validateMetadata.uxIntent.expectedDelta,
+        });
+        return fallback;
+      }
+      const result: ValidateResult = {
+        reportVersion: "compatibility-report/1",
+        blockExport: bundledReport?.blockExport ?? false,
+        warningCount: (bundledReport?.warningCount ?? 0) + warnings.length,
+        errorCount: bundledReport?.errorCount ?? 0,
+        featureEntriesCount: bundledReport?.featureEntries?.length ?? 0,
+        interactionGuard: {
+          mode: guard?.mode ?? "unknown",
+          readOnly: guard?.readOnly ?? false,
+        },
+      };
+      emitUxResponse(runtime, {
+        apiFn: validateMetadata.name,
+        intent: validateMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: validateMetadata.uxIntent.expectedDelta,
+      });
+      return result;
+    },
+  };
+}

package/src/api/v3/runtime/formatting.ts

@@ -0,0 +1,186 @@
+/**
+ * @endStateApi v3 — `runtime.formatting` family.
+ *
+ * getEffective (live) / resolveRunWithProvenance (live). Adapter delegates
+ * to Layer-03's `resolveEffectiveFormatting` façade + `FormattingContext`
+ * provenance path. No new logic lives here — the adapter only routes
+ * nodeRefs from the public API surface to the already-shipped L03 entry
+ * points.
+ *
+ * Cross-layer-coord reference: `docs/plans/cross-layer-coord-03.md` §2
+ * (L07 runtime.formatting.* public surface).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  resolveEffectiveFormatting,
+  createFormattingContext,
+  type EffectiveFormatting,
+  type RunProvenance,
+} from "../../../runtime/formatting/index.ts";
+import {
+  findParagraphByBlockId,
+  resolveDirectRunFormattingAtSegment,
+} from "../../../runtime/formatting/document-lookup.ts";
+import type { RuntimeTelemetryEvent } from "../../../runtime/debug/types.ts";
+
+/**
+ * Public nodeRef shape for `runtime.formatting.getEffective`. Structurally
+ * a subset of L03's internal `NodeRef` — the `field` kind's optional
+ * `pageGraph` is omitted from the public surface because threading the
+ * layout page-graph through is a separate integration tracked in the
+ * cross-layer-coord doc. Callers passing `{ kind: "field", ... }` get a
+ * `refreshStatus: "unresolved"` result, which is honest for now.
+ */
+export type FormattingNodeRef =
+  | { readonly kind: "paragraph"; readonly blockId: string }
+  | { readonly kind: "run"; readonly blockId: string; readonly runId: string }
+  | { readonly kind: "table"; readonly blockId: string }
+  | {
+      readonly kind: "table-cell";
+      readonly blockId: string;
+      readonly rowIndex: number;
+      readonly cellIndex: number;
+    }
+  | { readonly kind: "field"; readonly blockId: string; readonly runId: string }
+  | {
+      readonly kind: "drawing-frame";
+      readonly blockId: string;
+      readonly inlineId: string;
+    };
+
+export interface FormattingGetEffectiveOpts {
+  readonly revisionMarkupMode?: "clean" | "simple" | "all";
+}
+
+export const getEffectiveMetadata: ApiV3FnMetadata = {
+  name: "runtime.formatting.getEffective",
+  status: "live",
+  sourceLayer: "formatting-semantics",
+  // Direct delegation to `resolveEffectiveFormatting` — the Layer-03
+  // external façade. L03's cascade-parity + entry-delegation tests prove
+  // behavioral parity with the production hot path (`FormattingContext`).
+  liveEvidence: {
+    runnerTest:
+      "test/runtime/formatting/entry-delegation.test.ts,test/runtime/formatting/cascade-parity.test.ts,test/api/v3/runtime/formatting-adapter.test.ts",
+    commit: "refactor-03-runtime-formatting-adapter-2026-04-22",
+  },
+  // State-classes (Slice X2, f6051c07). Formatting output is derived
+  // from the canonical document (styles + revisions + theme etc.); it
+  // lives in the canonical tree and has no session-shared or local-pref
+  // surface. Derived read → no broadcastsVia.
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "formatting-read",
+  },
+  rwdReference:
+    "§Runtime API § runtime.formatting.getEffective. Adapter over Layer-03's resolveEffectiveFormatting façade — same code path the production hot path (FormattingContext) exercises.",
+};
+
+export const subscribeTelemetryMetadata: ApiV3FnMetadata = {
+  name: "runtime.formatting.subscribeTelemetry",
+  status: "live",
+  sourceLayer: "formatting-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/formatting-adapter.test.ts",
+    commit: "refactor-07-coord-03-formatting-subscribe-2026-04-22",
+  },
+  // Derived from canonical document (cascade resolution). Subscribe is
+  // a pass-through to the telemetry bus's `formatting` channel —
+  // consumers observe cache-miss / cascade-resolve events without
+  // importing the bus directly. The channel itself exists on the bus;
+  // L07 owns the v3 surface that gates access to it per the R-exposed
+  // patterns.
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "formatting-subscribe",
+  },
+  rwdReference:
+    "§Runtime API § runtime.formatting.subscribeTelemetry. Pass-through to handle.debug.bus — enables the 'formatting' channel and forwards events to the listener. Returned closure unsubscribes. Used by L10 debug pane + agent-facing observers without reaching into the bus module directly.",
+};
+
+export const resolveRunWithProvenanceMetadata: ApiV3FnMetadata = {
+  name: "runtime.formatting.resolveRunWithProvenance",
+  status: "live",
+  sourceLayer: "formatting-semantics",
+  // Live delegation to FormattingContext.resolveRunWithProvenance. L03
+  // provenance test pins the per-field source map across the four
+  // cascade tiers (direct / characterStyle / style / docDefaults).
+  liveEvidence: {
+    runnerTest:
+      "test/runtime/formatting/provenance.test.ts,test/api/v3/runtime/formatting-adapter.test.ts",
+    commit: "refactor-03-runtime-formatting-adapter-2026-04-22",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "formatting-read",
+  },
+  rwdReference:
+    "§Runtime API § runtime.formatting.resolveRunWithProvenance. Agent-facing provenance view — `source ∈ {direct, characterStyle, style, docDefaults}` plus `sourceId` for style tiers. Substrate for ai.explainFormatting (L09).",
+};
+
+export function createFormattingFamily(runtime: RuntimeApiHandle) {
+  return {
+    getEffective(
+      nodeRef: FormattingNodeRef,
+      opts?: FormattingGetEffectiveOpts,
+    ): EffectiveFormatting {
+      // @endStateApi — live. Delegates to L03's external façade against
+      // the current canonical document. Read-only; no side effects.
+      const doc = runtime.getCanonicalDocument();
+      return resolveEffectiveFormatting(doc, nodeRef, {
+        ...(opts?.revisionMarkupMode ? { revisionMarkupMode: opts.revisionMarkupMode } : {}),
+      });
+    },
+
+    subscribeTelemetry(
+      channel: "formatting",
+      listener: (event: RuntimeTelemetryEvent) => void,
+    ): () => void {
+      // @endStateApi — live. Pass-through to the runtime's telemetry bus.
+      // Enables the channel if it's off (otherwise the subscription
+      // attaches but never fires). Returns the bus's own unsubscribe
+      // closure — callers must retain + invoke it.
+      const bus = runtime.debug.bus;
+      if (!bus.isEnabled(channel)) {
+        bus.enable(channel);
+      }
+      return bus.subscribe([channel], listener);
+    },
+
+    resolveRunWithProvenance(input: {
+      readonly blockId: string;
+      readonly runId: string;
+    }): RunProvenance | null {
+      // @endStateApi — live. Looks up the canonical paragraph + inline
+      // at (blockId, runId), then calls FormattingContext.resolveRun
+      // WithProvenance to get the { run, properties } map. Returns null
+      // when the lookup misses (unknown blockId or segment out of range)
+      // — callers differentiate that from a real resolution with no
+      // populated fields.
+      const doc = runtime.getCanonicalDocument();
+      const foundPara = findParagraphByBlockId(doc, input.blockId);
+      if (!foundPara) return null;
+      const direct = resolveDirectRunFormattingAtSegment(foundPara.paragraph, input.runId);
+      const ctx = createFormattingContext(doc);
+      return ctx.resolveRunWithProvenance({
+        paragraphStyleId: foundPara.paragraph.styleId,
+        characterStyleId: direct?.characterStyleId,
+        direct,
+      });
+    },
+  };
+}