@beyondwork/docx-react-component 1.0.67 → 1.0.70

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

@@ -0,0 +1,63 @@
+/**
+ * @endStateApi v3 — `runtime.table` family.
+ *
+ * Single function: `getSelectionDescriptor(state)`. Read-only projection
+ * that inspects the current PM `EditorState` and returns a typed
+ * descriptor (`TableSelectionDescriptor`) when the selection is inside
+ * a table — block index, cell coords, rect bounds — or null otherwise.
+ * Thin pass-through over `getTableSelectionDescriptor` from
+ * `src/runtime/table-commands.ts` so L11's PM surface can migrate to
+ * the v3 seam (coord-11 §4.3).
+ *
+ * PM-command exports (addRowBefore/After, deleteRow, addColumnBefore/
+ * After, deleteColumn, mergeCells, splitCell, toggleHeader*) stay on
+ * the runtime module for now — they are PM-native `Command` values
+ * that the editor's keymap dispatches, not agent-callable functions.
+ * Exposing them via v3 is out of scope for this slice; the one L11
+ * import this family retires is the `getTableSelectionDescriptor` +
+ * type import on `tw-prosemirror-surface.tsx`.
+ *
+ * Pure-function read — `stateClass: "C-local"` + `persistsTo: "none"`.
+ * No UxResponse emission.
+ */
+
+import type { EditorState } from "prosemirror-state";
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  getTableSelectionDescriptor,
+  type TableSelectionDescriptor,
+} from "../../../runtime/table-commands.ts";
+
+// Re-export so L11 consumers don't peek into `src/runtime/table-commands.ts`
+// for the type either.
+export type { TableSelectionDescriptor };
+
+export const getSelectionDescriptorMetadata: ApiV3FnMetadata = {
+  name: "runtime.table.getSelectionDescriptor",
+  status: "live",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-table-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "table-selection-read",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.table.getSelectionDescriptor. Direct delegation to getTableSelectionDescriptor (src/runtime/table-commands.ts). Inspects the PM EditorState and returns a typed descriptor when the selection resolves inside a table, or null otherwise.",
+};
+
+export function createTableFamily(_runtime: RuntimeApiHandle) {
+  return {
+    getSelectionDescriptor(state: EditorState): TableSelectionDescriptor | null {
+      // @endStateApi — live.
+      return getTableSelectionDescriptor(state);
+    },
+  };
+}

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

@@ -0,0 +1,434 @@
+/**
+ * @endStateApi v3 — `runtime.workflow` family.
+ *
+ * queryScopes (live) / getMarkup (live) / getGuard (live) /
+ * createScope (live-with-adapter) / attachMetadata (live-with-adapter) /
+ * getVisibilityPolicy · getVisibilityPolicies · setVisibilityPolicy ·
+ * clearVisibilityPolicy (live — W10 state-classes X1).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type {
+  OverlayKind,
+  OverlayVisibilityPolicy,
+  WorkflowMarkupModePolicy,
+} from "../../public-types.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+import { createScopeFromBlockId } from "../../../runtime/workflow/scope-writer.ts";
+import { attachScopeMetadata } from "../../../runtime/workflow/metadata-writer.ts";
+
+export const queryScopesMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.queryScopes",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: { runnerTest: "test/runtime/debug/build-debug-inspector-snapshot.test.ts", commit: "6aca0666" },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "scope-list" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.queryScopes",
+};
+
+export const getMarkupMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.getMarkup",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "phase-p-prime",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "markup-read" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.getMarkup",
+};
+
+export const getGuardMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.getGuard",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    // Direct parity test — asserts v3.getGuard delegates to
+    // handle.getInteractionGuardSnapshot() and returns the exact
+    // InteractionGuardSnapshot shape (effectiveMode + blockedReasons).
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "refactor-07-adversarial-closure-2026-04-22",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "guard-read" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.getGuard",
+};
+
+export interface CreateScopeInput {
+  readonly blockId: string;
+  readonly mode?: "edit" | "suggest" | "comment" | "view";
+  readonly label?: string;
+  /**
+   * Coord-06 §13d — per-scope edge stickiness. Defaults to
+   * `{ start: 1, end: -1 }` (greedy — absorbs boundary inserts, the
+   * pre-§13d shipped shape). Use `{ start: -1, end: 1 }` for a
+   * fixed-position anchor (signature-block / template-slot / system-
+   * paragraph semantics — rejects boundary inserts; cursor work doesn't
+   * leak in). Agents pick per scope family per coord-09 §1.14.
+   */
+  readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+}
+
+export interface CreateScopeResult {
+  readonly scopeId: string;
+  readonly status: "created" | "block-not-found";
+}
+
+export const createScopeMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.createScope",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-live.test.ts",
+    commit: "609ffec2",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "scope-created", expectedDelta: "rail shows new scope chip; editor surface refreshes" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "selection", auditCategory: "scope-creation" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.createScope",
+};
+
+export interface AttachMetadataInput {
+  readonly scopeId: string;
+  readonly metadataId: string;
+  readonly value?: Record<string, unknown>;
+}
+
+export interface AttachMetadataResult {
+  readonly status: "attached" | "scope-not-found";
+  readonly entryId?: string;
+}
+
+export const attachMetadataMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.attachMetadata",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-attach-metadata-live.test.ts",
+    commit: "609ffec2",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "scope card shows new metadata field" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "metadata-write" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.attachMetadata",
+};
+
+export const getVisibilityPolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.getVisibilityPolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/visibility-policy-roundtrip.test.ts",
+    commit: "state-classes-x1",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "policy-read" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.getVisibilityPolicy",
+};
+
+export const getVisibilityPoliciesMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.getVisibilityPolicies",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/visibility-policy-roundtrip.test.ts",
+    commit: "state-classes-x1",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "policy-read" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.getVisibilityPolicies",
+};
+
+export const setVisibilityPolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.setVisibilityPolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/visibility-policy-roundtrip.test.ts",
+    commit: "state-classes-x1",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "overlay visibility follows authored policy on all subscribed surfaces",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "document", auditCategory: "policy-write" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.setVisibilityPolicy",
+};
+
+export const subscribeVisibilityPolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.subscribeVisibilityPolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/visibility-policy-subscribe.test.ts",
+    commit: "state-classes-x1-subscribe",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "policy-read" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.subscribeVisibilityPolicy",
+};
+
+export const clearVisibilityPolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.clearVisibilityPolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/visibility-policy-roundtrip.test.ts",
+    commit: "state-classes-x1",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "overlay visibility reverts to class-C local default",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "document", auditCategory: "policy-write" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.clearVisibilityPolicy",
+};
+
+// ---------------------------------------------------------------------------
+// X5 · markup-mode policy metadata
+// ---------------------------------------------------------------------------
+
+export const getMarkupModePolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.getMarkupModePolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/markup-mode-policy-roundtrip.test.ts",
+    commit: "state-classes-x5",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "policy-read" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.getMarkupModePolicy",
+};
+
+export const setMarkupModePolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.setMarkupModePolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/markup-mode-policy-roundtrip.test.ts",
+    commit: "state-classes-x5",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "revision markup surfaces switch to the authored mode on all subscribed surfaces",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "document", auditCategory: "policy-write" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.setMarkupModePolicy",
+};
+
+export const subscribeMarkupModePolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.subscribeMarkupModePolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/runtime/workflow/markup-mode-policy-roundtrip.test.ts",
+    commit: "state-classes-x5",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "policy-read" },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.subscribeMarkupModePolicy",
+};
+
+export function createWorkflowFamily(runtime: RuntimeApiHandle) {
+  return {
+    queryScopes(filter?: unknown) {
+      // @endStateApi — live.
+      return runtime.queryScopes(filter as never);
+    },
+
+    getMarkup() {
+      // @endStateApi — live. Delegates to the workflow markup snapshot
+      // (separate from getWorkflowOverlay(), which returns overlay state).
+      return runtime.getWorkflowMarkupSnapshot();
+    },
+
+    getGuard() {
+      // @endStateApi — live.
+      return runtime.getInteractionGuardSnapshot();
+    },
+
+    createScope(input: CreateScopeInput): CreateScopeResult {
+      // @endStateApi — live-with-adapter. Resolves blockId → anchor via the
+      // surface snapshot then delegates to runtime.addScope (layer-06
+      // scope-writer). Status discriminator surfaces "block-not-found" /
+      // "no-surface" instead of inventing an anchor.
+      const adapterResult = createScopeFromBlockId(runtime, {
+        blockId: input.blockId,
+        mode: input.mode,
+        label: input.label,
+        ...(input.assoc ? { assoc: input.assoc } : {}),
+      });
+      emitUxResponse(runtime, {
+        apiFn: createScopeMetadata.name,
+        intent: createScopeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: createScopeMetadata.uxIntent.expectedDelta,
+        actualDelta:
+          adapterResult.status === "created"
+            ? { kind: "inline-change", payload: { scopeId: adapterResult.scopeId } }
+            : undefined,
+      });
+      if (adapterResult.status !== "created") {
+        return { scopeId: "", status: adapterResult.status };
+      }
+      return { scopeId: adapterResult.scopeId, status: "created" };
+    },
+
+    getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null {
+      // @endStateApi — live. Class-A policy read; composition with
+      // class-C local preference lives in L10 (`ui.overlays.getVisibility`).
+      return runtime.getVisibilityPolicy(kind);
+    },
+
+    getVisibilityPolicies(): readonly OverlayVisibilityPolicy[] {
+      // @endStateApi — live.
+      return runtime.getVisibilityPolicies();
+    },
+
+    setVisibilityPolicy(policy: OverlayVisibilityPolicy): { changed: boolean } {
+      // @endStateApi — live. Author a class-A policy; persists on next
+      // exportDocx via `customXml/item1.xml` (bw:overlayVisibility) and
+      // broadcasts via CRDT when collab is attached.
+      const changed = runtime.setVisibilityPolicy(policy);
+      if (changed) {
+        emitUxResponse(runtime, {
+          apiFn: setVisibilityPolicyMetadata.name,
+          intent: setVisibilityPolicyMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: setVisibilityPolicyMetadata.uxIntent.expectedDelta,
+          actualDelta: { kind: "inline-change", payload: { kind: policy.kind } },
+        });
+      }
+      return { changed };
+    },
+
+    subscribeVisibilityPolicy(listener: () => void): () => void {
+      // @endStateApi — live. Fires after set/clear/replace policy mutations.
+      // Chained by L10 X3's ui.overlays.subscribeVisibility so UI surfaces
+      // re-fire when authoring tools mutate policy mid-session.
+      return runtime.subscribeVisibilityPolicy(listener);
+    },
+
+    getMarkupModePolicy(): WorkflowMarkupModePolicy | null {
+      // @endStateApi — live. Class-A markup-mode policy read; composition
+      // with class-C local preference lives in L10 X5.
+      return runtime.getMarkupModePolicy();
+    },
+
+    setMarkupModePolicy(
+      policy: WorkflowMarkupModePolicy | null,
+    ): { changed: boolean } {
+      // @endStateApi — live. Authors (or clears) the class-A policy;
+      // persists on next exportDocx via customXml/item1.xml (bw:markupModePolicy).
+      const changed = runtime.setMarkupModePolicy(policy);
+      if (changed) {
+        emitUxResponse(runtime, {
+          apiFn: setMarkupModePolicyMetadata.name,
+          intent: setMarkupModePolicyMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: setMarkupModePolicyMetadata.uxIntent.expectedDelta,
+          actualDelta: {
+            kind: "inline-change",
+            payload: { mode: policy?.mode ?? null, enforcement: policy?.enforcement ?? null },
+          },
+        });
+      }
+      return { changed };
+    },
+
+    subscribeMarkupModePolicy(listener: () => void): () => void {
+      // @endStateApi — live. Fires after setMarkupModePolicy mutations.
+      return runtime.subscribeMarkupModePolicy(listener);
+    },
+
+    clearVisibilityPolicy(kind: OverlayKind): { changed: boolean } {
+      // @endStateApi — live.
+      const changed = runtime.clearVisibilityPolicy(kind);
+      if (changed) {
+        emitUxResponse(runtime, {
+          apiFn: clearVisibilityPolicyMetadata.name,
+          intent: clearVisibilityPolicyMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: clearVisibilityPolicyMetadata.uxIntent.expectedDelta,
+          actualDelta: { kind: "inline-change", payload: { kind } },
+        });
+      }
+      return { changed };
+    },
+
+    attachMetadata(input: AttachMetadataInput): AttachMetadataResult {
+      // @endStateApi — live-with-adapter. Reuses the target scope's anchor
+      // and dispatches through runtime.setWorkflowMetadataEntries (layer-06
+      // metadata-writer). Status discriminator surfaces "scope-not-found"
+      // when the scopeId is absent from the overlay.
+      const adapterResult = attachScopeMetadata(runtime, {
+        scopeId: input.scopeId,
+        metadataId: input.metadataId,
+        value: input.value,
+      });
+      emitUxResponse(runtime, {
+        apiFn: attachMetadataMetadata.name,
+        intent: attachMetadataMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: attachMetadataMetadata.uxIntent.expectedDelta,
+        actualDelta:
+          adapterResult.status === "attached"
+            ? { kind: "inline-change", payload: { entryId: adapterResult.entryId } }
+            : undefined,
+      });
+      if (adapterResult.status === "attached") {
+        return { status: "attached", entryId: adapterResult.entryId };
+      }
+      return { status: "scope-not-found" };
+    },
+  };
+}

package/src/api/v3/ui/_context.ts

@@ -0,0 +1,86 @@
+/**
+ * Internal — shared UI API instance state.
+ *
+ * Every family factory (session / surface / viewport / overlays / chrome /
+ * debug) closes over one `UiApiContext` so bind/release lifecycle mutations
+ * observed in `ui.session` are visible to the rest of the surface. The
+ * context itself is NOT exported from the barrel — consumers reach state
+ * through the public methods (U8: no internal controllers cross the
+ * boundary).
+ */
+
+import type { MockPayload } from "../_layer-metadata.ts";
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { UiController, ViewportState } from "./_types.ts";
+
+export interface BindingState {
+  controller: UiController;
+  released: boolean;
+}
+
+export interface UiApiContext {
+  readonly handle: RuntimeApiHandle;
+  binding: BindingState | null;
+}
+
+export function createUiApiContext(handle: RuntimeApiHandle): UiApiContext {
+  return {
+    handle,
+    binding: null,
+  };
+}
+
+/**
+ * Mock-flagged zeroed ViewportState used by `ui.viewport.get` and
+ * `ui.surface.getViewport` when neither `handle.geometry.getViewport()`
+ * nor `controller.getViewport()` produces a value (headless / pre-paint).
+ * Single definition so both families agree on the fallback shape.
+ */
+export const DEFAULT_VIEWPORT: ViewportState & MockPayload = Object.freeze({
+  __mock: true,
+  reason: "neither handle.geometry nor controller.getViewport hook produced a value; pre-paint / headless default.",
+  shape: "ViewportState",
+  scrollTop: 0,
+  scrollLeft: 0,
+  width: 0,
+  height: 0,
+  zoom: 1,
+  devicePixelRatio: 1,
+} as const);
+
+/**
+ * Shared viewport composition — reads scroll / dpr / zoom from
+ * `handle.geometry.getViewport()` and layers controller-provided
+ * width / height on top. Used by both `ui.viewport.get` and
+ * `ui.surface.getViewport` so the two families agree on one source of
+ * truth.
+ *
+ * Per DS §8.3 (runtime owns truth), we trust `handle.geometry`'s
+ * contract — optional chaining handles absent accessors; a thrown
+ * `getViewport()` is a real runtime regression and is allowed to
+ * propagate. This mirrors the discipline applied to
+ * `ui.chrome.getPosture` by Slice 12.
+ *
+ * NOTE on zoom units: `ViewportState.zoom` is currently the
+ * `pxPerTwip` density from the geometry facet (physical pixels per
+ * OOXML twip, ~0.0667 at 100% zoom / 96 dpi) — NOT a 1.0-is-100%
+ * ratio. No consumer reads this semantically yet; when one does, this
+ * field either renames to `pxPerTwip` or divides by a baseline. Flagged
+ * as drift in review M1.
+ */
+export function readComposedViewport(ctx: UiApiContext): ViewportState {
+  const hook = ctx.binding?.controller.getViewport;
+  const fromController = hook ? hook() : null;
+  const fromGeometry = ctx.handle.geometry?.getViewport?.() ?? null;
+
+  if (!fromGeometry && !fromController) return DEFAULT_VIEWPORT;
+
+  return {
+    scrollTop: fromGeometry?.scrollTopPx ?? fromController?.scrollTop ?? 0,
+    scrollLeft: fromGeometry?.scrollLeftPx ?? fromController?.scrollLeft ?? 0,
+    width: fromController?.width ?? 0,
+    height: fromController?.height ?? 0,
+    zoom: fromGeometry?.pxPerTwip ?? fromController?.zoom ?? 1,
+    devicePixelRatio: fromGeometry?.dpr ?? fromController?.devicePixelRatio ?? 1,
+  };
+}

package/src/api/v3/ui/_create.ts

@@ -0,0 +1,65 @@
+/**
+ * @endStateApi v3 — `createUiApi(handle, factory)` entry point.
+ *
+ * The UI API (layer 10) is the first-class mounted-surface contract —
+ * session binding, selection/viewport hooks, geometry-backed overlay
+ * primitives, chrome posture composition, debug-service attachment.
+ *
+ * Slice 2 (current) — session + surface live. Slice 3 wires viewport +
+ * overlays through the geometry facet; Slice 4 composes chrome posture;
+ * Slice 5 ships the debug attachment + Phase Q UX.
+ *
+ * This factory is standalone today. Refactor/07 Slice 2 extends
+ * `createApiV3` to accept a `UiControllerFactory` and compose the UI
+ * namespace into the root API — the staircase in master plan §2 is
+ * `/07 Slice 1` (RuntimeApiHandle) → `/10 Slice 1` (reservation) →
+ * `/07 Slice 2` (createApiV3 extension).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3Ui, UiControllerFactory } from "./_types.ts";
+import { createUiApiContext } from "./_context.ts";
+import { createSessionFamily } from "./session.ts";
+import { createSurfaceFamily } from "./surface.ts";
+import { createViewportFamily } from "./viewport.ts";
+import { createOverlaysFamily } from "./overlays.ts";
+import { createChromeFamily } from "./chrome.ts";
+import { createDebugFamily } from "./debug.ts";
+import { createScopeFamily } from "./scope.ts";
+
+/**
+ * @endStateApi
+ * Construct the UI API surface. The optional `factory` runs exactly once
+ * to produce the initial controller if the caller wants the binding wired
+ * eagerly. Most callers pass no factory and use `api.session.bind(...)`
+ * themselves after the handle's runtime reaches a mountable state.
+ */
+export function createUiApi(
+  handle: RuntimeApiHandle,
+  factory?: UiControllerFactory,
+): ApiV3Ui {
+  const ctx = createUiApiContext(handle);
+
+  if (factory) {
+    const controller = factory(handle);
+    ctx.binding = { controller, released: false };
+  }
+
+  const api: ApiV3Ui = {
+    session: createSessionFamily(ctx),
+    surface: createSurfaceFamily(ctx),
+    viewport: createViewportFamily(ctx),
+    overlays: createOverlaysFamily(ctx),
+    chrome: createChromeFamily(ctx),
+    debug: createDebugFamily(ctx),
+    scope: createScopeFamily(ctx),
+  };
+  Object.freeze(api.session);
+  Object.freeze(api.surface);
+  Object.freeze(api.viewport);
+  Object.freeze(api.overlays);
+  Object.freeze(api.chrome);
+  Object.freeze(api.debug);
+  Object.freeze(api.scope);
+  return Object.freeze(api);
+}