@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/api/v3/ui/overlays-visibility.ts

@@ -0,0 +1,170 @@
+/**
+ * @endStateApi v3 — `ui.overlays.getVisibility / setLocalPreference /
+ * resetLocalPreference / subscribeVisibility` (U9, state-classes X3).
+ *
+ * The single composition site for overlay visibility. Merges:
+ *   - class-A policy  → `handle.getVisibilityPolicy(kind)` (L06 X1).
+ *   - class-C preference → per-UI-API-instance Map in the factory closure.
+ *
+ * No renderer, chrome surface, or presentation component duplicates
+ * this logic — `ui.overlays.getVisibility` is the only path per
+ * architecture 10 §U9.
+ *
+ * Storage shape (closure-local, per `createUiApi(handle)` instance):
+ *   - `localPrefs: Map<OverlayKind, boolean>` — user's explicit pref.
+ *   - `subscribers: Map<OverlayKind, Set<UiListener<OverlayVisibility>>>` —
+ *     listeners fired on pref changes.
+ *
+ * Composition pseudocode (architecture 10 §U9 + `00-overview.md §9.1`):
+ *
+ *   policy = handle.getVisibilityPolicy(kind)        // may be null
+ *   pref   = localPrefs.get(kind)                    // may be undefined
+ *
+ *   # debug-panel special case: debugMode gate wins over everything.
+ *   if kind === "debug-panel" and debugMode === "off":
+ *     → { state: "forced-off", reason: "policy-enforcement" }
+ *
+ *   # Policy enforcement is a hard override.
+ *   if policy.enforcement === "always":
+ *     → { state: "forced-on",  reason: "policy-enforcement" }
+ *   if policy.enforcement === "never":
+ *     → { state: "forced-off", reason: "policy-enforcement" }
+ *
+ *   # "authored-default" cedes to local preference.
+ *   if pref === true:   → { state: "visible", reason: "user-preference" }
+ *   if pref === false:  → { state: "hidden",  reason: "user-preference" }
+ *
+ *   # No preference → use policy default (or intrinsic default if no policy).
+ *   defaultOn = policy.defaultOn ?? INTRINSIC_DEFAULTS[kind]
+ *   → defaultOn ? visible : hidden, reason: "policy-default"
+ *
+ * Subscribe fan-out is local-preference-only in this slice. Policy
+ * changes and debugMode changes do not wake listeners yet — consumers
+ * that depend on either re-read visibility on their own cadence.
+ * Follow-up slice will subscribe to the L06 policy telemetry bus and
+ * fan out on `workflow.visibility_policy_changed`.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { OverlayKind, OverlayVisibilityPolicy } from "../../public-types.ts";
+import type {
+  OverlayVisibility,
+  UiListener,
+  UiUnsubscribe,
+} from "./_types.ts";
+import type { UiApiContext } from "./_context.ts";
+
+/**
+ * Intrinsic defaults — used when no class-A policy has been authored for
+ * a kind. Mirrors the docs/wiki convention: scope/comment/tracked-changes
+ * on; suggestions + debug-panel off; presence on (collab default).
+ */
+const INTRINSIC_DEFAULT_ON: Readonly<Record<OverlayKind, boolean>> = {
+  "scope-rail": true,
+  "comments": true,
+  "tracked-changes": true,
+  "suggestions": false,
+  "debug-panel": false,
+  "presence": true,
+};
+
+/**
+ * Per-instance visibility state. `createUiApi(handle)` constructs one of
+ * these; it closes over the overlays family.
+ */
+export interface OverlaysVisibilityState {
+  readonly localPrefs: Map<OverlayKind, boolean>;
+  readonly subscribers: Map<OverlayKind, Set<UiListener<OverlayVisibility>>>;
+}
+
+export function createOverlaysVisibilityState(): OverlaysVisibilityState {
+  return {
+    localPrefs: new Map(),
+    subscribers: new Map(),
+  };
+}
+
+/**
+ * Read the current effective debugMode from the bound controller's host
+ * posture slice. Mirrors the default handling in `chrome.ts::getPosture`
+ * — unbound / no hook / no debugMode field all resolve to `"off"` per
+ * U6 + CLAUDE.md Protected Invariants.
+ */
+function readDebugMode(ctx: UiApiContext): "off" | "top-bar" | "full" {
+  return ctx.binding?.controller.getHostPosture?.()?.debugMode ?? "off";
+}
+
+function readPolicy(
+  handle: RuntimeApiHandle,
+  kind: OverlayKind,
+): OverlayVisibilityPolicy | null {
+  // `getVisibilityPolicy` is on `RuntimeApiHandle` (Layer 06 X1 +
+  // L07 roster update). Read directly — no cast. The function itself
+  // returns null on unknown/unset policy, so the handle covers the
+  // pre-paint case too.
+  return handle.getVisibilityPolicy(kind) ?? null;
+}
+
+/**
+ * Compose the OverlayVisibility record for a single kind. Pure except
+ * for the handle / ctx reads — no side effects, no allocation beyond
+ * the result object.
+ */
+export function composeOverlayVisibility(
+  ctx: UiApiContext,
+  state: OverlaysVisibilityState,
+  kind: OverlayKind,
+): OverlayVisibility {
+  // debug-panel: when debugMode is "off" the panel is forced off
+  // regardless of policy or preference (CLAUDE.md Protected Invariant).
+  if (kind === "debug-panel" && readDebugMode(ctx) === "off") {
+    return { state: "forced-off", reason: "policy-enforcement" };
+  }
+
+  const policy = readPolicy(ctx.handle, kind);
+  const pref = state.localPrefs.get(kind);
+
+  // Hard policy overrides.
+  if (policy?.enforcement === "always") {
+    return { state: "forced-on", reason: "policy-enforcement" };
+  }
+  if (policy?.enforcement === "never") {
+    return { state: "forced-off", reason: "policy-enforcement" };
+  }
+
+  // authored-default / no policy: local preference wins if expressed.
+  if (pref === true) {
+    return { state: "visible", reason: "user-preference" };
+  }
+  if (pref === false) {
+    return { state: "hidden", reason: "user-preference" };
+  }
+
+  // No preference — fall back to policy default, else intrinsic default.
+  const defaultOn = policy?.defaultOn ?? INTRINSIC_DEFAULT_ON[kind];
+  return defaultOn
+    ? { state: "visible", reason: "policy-default" }
+    : { state: "hidden", reason: "policy-default" };
+}
+
+/**
+ * Notify all subscribers for a kind with the current composed visibility.
+ * Called after `setLocalPreference` / `resetLocalPreference`.
+ */
+export function notifyVisibilitySubscribers(
+  ctx: UiApiContext,
+  state: OverlaysVisibilityState,
+  kind: OverlayKind,
+): void {
+  const listeners = state.subscribers.get(kind);
+  if (!listeners || listeners.size === 0) return;
+  const visibility = composeOverlayVisibility(ctx, state, kind);
+  for (const listener of listeners) {
+    try {
+      listener(visibility);
+    } catch {
+      // Isolate listener errors — one broken subscriber must not block
+      // the rest of the notification chain.
+    }
+  }
+}

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

@@ -0,0 +1,427 @@
+/**
+ * @endStateApi v3 — `ui.overlays` family (layer 10).
+ *
+ * Resolution order per OverlayAnchorQuery.kind:
+ *
+ *   - Id-keyed kinds (block / scope / comment / revision / page):
+ *     `handle.geometry.getAnchor(AnchorQuery)` directly; controller
+ *     hook is the fallback when geometry returns null. Slice 11
+ *     promoted these to `live` against geometry.
+ *
+ *   - `kind: "selection"`: controller hook first (the shell-side
+ *     `ShellOverlayAnchorBridge` populated by
+ *     `useShellSelectionAnchorBridge` — carries tool-aware anchor
+ *     semantics via `resolveSelectionAnchor`). `handle.geometry.
+ *     getSelectionRects` is the headless / pre-mount fallback that
+ *     returns the raw range rect without tool-context awareness.
+ *     Flicker-remediation 2026-04-22 flipped this order (previously
+ *     geometry-first), because raw-rects pre-empted the bridge's
+ *     tool-aware anchor for structural tools (image, table-cell).
+ *
+ *   - subscribe: live-with-adapter. Delegates to the bound
+ *     controller's `subscribeOverlays` hook. Geometry invalidation
+ *     streaming into the UI API direct from `handle.geometry` is a
+ *     follow-up slice (needs a rAF-coalesced fan-out that doesn't
+ *     exist on the geometry facet today).
+ *
+ * Return shape when geometry/handle is unavailable:
+ *   - getAnchor returns null (never throws). Per U4, "if geometry is
+ *     unavailable, return null — do not silently measure DOM."
+ *   - getRects returns [].
+ *   - subscribe throws — subscription is a stateful wiring decision; a
+ *     silent no-op would hide broken event routing.
+ *
+ * Contract U4 — overlays derive anchors from geometry, not DOM. The
+ * shell bridge itself is geometry-backed (the resolver reads
+ * `geometryFacet.getRenderFrame().anchorIndex`); the UI API never
+ * measures DOM.
+ */
+
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type {
+  GeometryRect,
+  OverlayAnchorQuery,
+  OverlayVisibility,
+  UiListener,
+  UiUnsubscribe,
+} from "./_types.ts";
+import type { OverlayKind, SelectionSnapshot } from "../../public-types.ts";
+import type { AnchorQuery } from "../../../runtime/geometry/geometry-types.ts";
+import type { UiApiContext } from "./_context.ts";
+import {
+  composeOverlayVisibility,
+  createOverlaysVisibilityState,
+  notifyVisibilitySubscribers,
+} from "./overlays-visibility.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+
+/**
+ * Translate the UI API's `OverlayAnchorQuery` (public, presentation-shaped) to
+ * the geometry facet's id-keyed `AnchorQuery`. Returns null for
+ * `kind: "selection"` — selection doesn't live in the id-keyed anchor
+ * index; it's resolved through a separate code path via
+ * `handle.geometry.getSelectionRects` (see `resolveSelectionRects` in
+ * this file).
+ */
+function toAnchorQuery(query: OverlayAnchorQuery): AnchorQuery | null {
+  switch (query.kind) {
+    case "block":
+      return { kind: "block-id", value: query.value };
+    case "scope":
+      return { kind: "scope-id", value: query.value };
+    case "comment":
+      return { kind: "comment-id", value: query.value };
+    case "revision":
+      return { kind: "revision-id", value: query.value };
+    case "page":
+      return { kind: "page-index", value: query.value };
+    case "selection":
+      return null;
+  }
+}
+
+/**
+ * Resolve `OverlayAnchorQuery.kind === "selection"` via
+ * `handle.geometry.getSelectionRects({from, to, story})`. The current
+ * selection range is read from `handle.getRenderSnapshot().selection`
+ * (collapsed selections return []; callers that want caret geometry
+ * use `handle.geometry.getCaret(offset)` directly).
+ *
+ * Returns `[]` when geometry / render snapshot are unavailable (pre-paint
+ * / headless handles that don't expose the method). Never reaches DOM
+ * per U4.
+ */
+function resolveSelectionRects(ctx: UiApiContext): readonly GeometryRect[] {
+  const render = ctx.handle.getRenderSnapshot?.() as
+    | { selection?: SelectionSnapshot }
+    | null
+    | undefined;
+  const selection = render?.selection;
+  if (!selection || selection.isCollapsed) return [];
+  const getSelectionRects = ctx.handle.geometry?.getSelectionRects;
+  if (typeof getSelectionRects !== "function") return [];
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  return getSelectionRects({
+    from,
+    to,
+    story: selection.storyTarget,
+  });
+}
+
+export const getAnchorMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.getAnchor",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-anchor.test.ts",
+    commit: "refactor-10-slice-11",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "ui-overlays-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.overlays.getAnchor. For id-keyed kinds (block/scope/comment/revision/page): reads handle.geometry.getAnchor(query) directly; controller hook is the fallback when geometry returns null. For kind:'selection': controller hook (shell bridge — tool-aware) is the primary path; handle.geometry.getSelectionRects is the fallback for headless / pre-mount.",
+};
+
+export const getRectsMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.getRects",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-anchor.test.ts",
+    commit: "refactor-10-slice-11",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "ui-overlays-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.overlays.getRects. For id-keyed kinds: reads handle.geometry.getAnchorRects(query) directly; controller hook is the fallback when geometry returns []. For kind:'selection': controller hook (shell bridge — tool-aware) is the primary path; handle.geometry.getSelectionRects is the fallback.",
+};
+
+export const subscribeMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.subscribe",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-anchor.test.ts",
+    commit: "refactor-07-slice-2",
+  },
+  // Stream-form bidirectional channel (U4 + U7). Subscribe call is
+  // uiVisible — attaching the listener re-parents which overlays are
+  // re-resolved on geometry invalidation. Per-invalidation OverlayAnchorQuery
+  // deliveries travel through the listener.
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "overlay subscriber attached; geometry invalidations that overlap attached queries propagate through the listener",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "ui-overlays-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.overlays.invalidated",
+    payloadType: "OverlayAnchorQuery",
+    coalescing: "raf",
+  },
+  rwdReference: "§UI API § ui.overlays.subscribe. Adapter delegates to UiController.subscribeOverlays; throws when the active binding has no hook. Subscribe call emits one `ux.response.ui.overlays.subscribe` acknowledgement; per-invalidation OverlayAnchorQuery deliveries flow through the listener.",
+};
+
+// ----- U9 overlay-visibility metadata (state-classes X3) -----
+
+export const getVisibilityMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.getVisibility",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-visibility.test.ts",
+    commit: "refactor-10-slice-x3",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-overlays-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.overlays.getVisibility (U9). Single composition site merging class-A policy (handle.getVisibilityPolicy) with class-C local preference. debug-panel is additionally gated on ChromePosture.debugMode per CLAUDE.md Protected Invariant.",
+};
+
+export const setLocalPreferenceMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.setLocalPreference",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-visibility.test.ts",
+    commit: "refactor-10-slice-x3",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "overlay local preference set; subscribers for the kind receive the new composed visibility",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-overlays-set-preference" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.overlays.setLocalPreference (U9). Class-C write; no broadcast, no canonical persistence. Hosts that want cross-reload survival save the preferences on beforeunload and restore on mount.",
+};
+
+export const resetLocalPreferenceMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.resetLocalPreference",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-visibility.test.ts",
+    commit: "refactor-10-slice-x3",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "overlay local preference cleared; subsequent reads fall back to policy default",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-overlays-reset-preference" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.overlays.resetLocalPreference (U9). Class-C write — clears the per-session preference for a specific OverlayKind.",
+};
+
+export const subscribeVisibilityMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.subscribeVisibility",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-visibility.test.ts",
+    commit: "refactor-10-slice-x3",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "visibility subscriber attached; per-kind OverlayVisibility deliveries propagate on local-preference change",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-overlays-subscribe-visibility" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.overlays.visibility_changed",
+    payloadType: "OverlayVisibility",
+    coalescing: "microtask",
+  },
+  rwdReference: "§UI API § ui.overlays.subscribeVisibility (U9). Fires on BOTH local-preference mutation AND class-A policy-change (closed 2026-04-22 — chained to L06's handle.subscribeVisibilityPolicy). debugMode-change fan-out remains a Phase Q follow-up.",
+};
+
+export function createOverlaysFamily(ctx: UiApiContext) {
+  // Closure-local visibility state — per UI API instance. Cross-instance
+  // isolation is structural (two createUiApi(handle) calls hold two
+  // states). Storage is in-memory; hosts persist across reloads via
+  // beforeunload/restore per architecture 10 §U9.
+  const visibilityState = createOverlaysVisibilityState();
+
+  // W10 policy-change fan-out — when L06 mutates the class-A policy
+  // (via runtime.workflow.setVisibilityPolicy / clearVisibilityPolicy),
+  // re-notify every kind that has a live subscriber. This closes the
+  // follow-up flagged in `subscribeVisibilityMetadata.rwdReference`:
+  // previously we only fired on local-preference changes, leaving
+  // authoring-tool policy mutations invisible until a doc reload.
+  //
+  // The subscription is global (not per-kind) because L06's hook fires
+  // for ANY policy change — we iterate our local subscriber map on fire
+  // and compose a fresh OverlayVisibility per kind. Cost: O(subscribed
+  // kinds) × O(composeOverlayVisibility), bounded by 6 kinds.
+  // `subscribeVisibilityPolicy` is on `RuntimeApiHandle` (L06 X1 + L07
+  // roster update). Optional-chain defensively: legacy / test-stub
+  // handles that predate X1 are allowed to omit it — the graceful-
+  // degradation contract is tested at `overlays-visibility.test.ts`
+  // "X1⇄X3 — handles without subscribeVisibilityPolicy degrade
+  // gracefully (no throw)".
+  //
+  // TODO(ui.dispose): we intentionally do not retain the unsubscribe
+  // here — the family instance lives for the lifetime of the host's UI
+  // API, and disposal of that API also collapses the handle. If host
+  // teardown ever gains a ui.dispose() hook, the unsubscribe ref MUST
+  // be retained and invoked there to avoid a leak on the L06 policy-
+  // broadcast channel.
+  ctx.handle.subscribeVisibilityPolicy?.(() => {
+    for (const kind of visibilityState.subscribers.keys()) {
+      notifyVisibilitySubscribers(ctx, visibilityState, kind);
+    }
+  });
+
+  return {
+    getAnchor(query: OverlayAnchorQuery): GeometryRect | null {
+      // `kind: "selection"` — bridge-first, geometry fallback.
+      //
+      // Flicker-remediation 2026-04-22: Slice 11's original geometry-
+      // first order pre-empted the shell-side bridge. The bridge
+      // (populated by `useShellSelectionAnchorBridge` via
+      // `resolveSelectionAnchor`) carries tool-aware semantics —
+      // structural-context tools resolve to the containing block or
+      // table-cell rect, not the raw selection range. Raw
+      // `handle.geometry.getSelectionRects` returns only the range
+      // rects; using them for a tool-active selection placed the
+      // floating surface against the wrong anchor. Order swapped so
+      // the shell's semantically-correct resolver wins when mounted;
+      // geometry remains the fallback for headless / pre-mount cases
+      // where no controller is bound.
+      if (query.kind === "selection") {
+        const hook = ctx.binding?.controller.getOverlayAnchor;
+        if (hook) {
+          const fromBridge = hook(query);
+          if (fromBridge) return fromBridge;
+        }
+        const rects = resolveSelectionRects(ctx);
+        return rects.length > 0 ? (rects[0] ?? null) : null;
+      }
+      const anchorQuery = toAnchorQuery(query);
+      if (anchorQuery) {
+        const fromGeometry = ctx.handle.geometry?.getAnchor?.(anchorQuery) ?? null;
+        if (fromGeometry) return fromGeometry;
+      }
+      const hook = ctx.binding?.controller.getOverlayAnchor;
+      // U4: geometry unavailable AND no controller hook → null.
+      // MUST NOT fall back to DOM measurement.
+      return hook ? hook(query) : null;
+    },
+    getRects(query: OverlayAnchorQuery): readonly GeometryRect[] {
+      // Bridge-first, geometry fallback — same rationale as getAnchor.
+      if (query.kind === "selection") {
+        const hook = ctx.binding?.controller.getOverlayRects;
+        if (hook) {
+          const fromBridge = hook(query);
+          if (fromBridge.length > 0) return fromBridge;
+        }
+        return resolveSelectionRects(ctx);
+      }
+      const anchorQuery = toAnchorQuery(query);
+      if (anchorQuery) {
+        const fromGeometry = ctx.handle.geometry?.getAnchorRects?.(anchorQuery) ?? [];
+        if (fromGeometry.length > 0) return fromGeometry;
+      }
+      const hook = ctx.binding?.controller.getOverlayRects;
+      return hook ? hook(query) : [];
+    },
+    subscribe(listener: UiListener<OverlayAnchorQuery>): UiUnsubscribe {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.overlays.subscribe: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribeOverlays) {
+        throw new Error(
+          `ui.overlays.subscribe: controller of kind "${controller.kind}" did not provide a subscribeOverlays hook`,
+        );
+      }
+      const unsubscribe = controller.subscribeOverlays(listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribeMetadata.name,
+        intent: subscribeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: subscribeMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.overlays" } },
+      });
+      return unsubscribe;
+    },
+
+    // ----- U9 overlay-visibility (state-classes X3) -----
+
+    getVisibility(kind: OverlayKind): OverlayVisibility {
+      return composeOverlayVisibility(ctx, visibilityState, kind);
+    },
+
+    setLocalPreference(kind: OverlayKind, visible: boolean): void {
+      const prev = visibilityState.localPrefs.get(kind);
+      if (prev === visible) return; // idempotent — no spurious wakeups.
+      visibilityState.localPrefs.set(kind, visible);
+      emitUxResponse(ctx.handle, {
+        apiFn: setLocalPreferenceMetadata.name,
+        intent: setLocalPreferenceMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: setLocalPreferenceMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { overlay: kind, visible } },
+      });
+      notifyVisibilitySubscribers(ctx, visibilityState, kind);
+    },
+
+    resetLocalPreference(kind: OverlayKind): void {
+      const had = visibilityState.localPrefs.has(kind);
+      if (!had) return; // idempotent.
+      visibilityState.localPrefs.delete(kind);
+      emitUxResponse(ctx.handle, {
+        apiFn: resetLocalPreferenceMetadata.name,
+        intent: resetLocalPreferenceMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: resetLocalPreferenceMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { overlay: kind, reset: true } },
+      });
+      notifyVisibilitySubscribers(ctx, visibilityState, kind);
+    },
+
+    subscribeVisibility(
+      kind: OverlayKind,
+      listener: UiListener<OverlayVisibility>,
+    ): UiUnsubscribe {
+      let listeners = visibilityState.subscribers.get(kind);
+      if (!listeners) {
+        listeners = new Set();
+        visibilityState.subscribers.set(kind, listeners);
+      }
+      listeners.add(listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribeVisibilityMetadata.name,
+        intent: subscribeVisibilityMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: subscribeVisibilityMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.overlays.visibility", overlay: kind } },
+      });
+      return () => {
+        const current = visibilityState.subscribers.get(kind);
+        if (!current) return;
+        current.delete(listener);
+        if (current.size === 0) visibilityState.subscribers.delete(kind);
+      };
+    },
+  };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @endStateApi v3 — `ui.scope` family (layer 10).
+ *
+ * Opens the mounted-path scope-read seam requested by coord-08 §1 +
+ * coord-11 §5/§50 ("L08 §2 blocked on L10 ui.scope.* seam"). Unblocked
+ * by L07's `compileScopeBundleById` handle primitive (refactor/07
+ * commit `3ffac7fe`, 2026-04-23).
+ *
+ * This slice ships the MVP primitive:
+ *
+ *   ui.scope.getBundle(scopeId: string): ScopeBundle | null
+ *
+ * Thin wrapper over `handle.compileScopeBundleById(scopeId, nowUtc)`.
+ * `nowUtc` is generated internally via `new Date().toISOString()` so UI
+ * consumers don't have to thread a clock through their code. The
+ * underlying AI API (`ai.getScopeBundle`) keeps its explicit-clock
+ * contract for agent-replay determinism; the UI seam trades that for
+ * ergonomic one-call scope reads appropriate for interactive UX.
+ *
+ * Enumeration — `ui.scope.list()` returning `SemanticScope[]` — is a
+ * deferred follow-up. Coord-11 §5 scope-card migration needs
+ * one-at-a-time bundle reads (the card mounts for a selected scope);
+ * broad enumeration stays on L11 using existing `WorkflowScope`-typed
+ * snapshots from the rail until a batch primitive exists.
+ *
+ * Contract compliance:
+ *   - U1: reads through `RuntimeApiHandle` + returned ScopeBundle is
+ *     pure canonical-document projection. No DOM / PM.
+ *   - stateClass: A-canonical (canonical document truth). Unlike other
+ *     L10 families which are C-local, this one surfaces runtime-owned
+ *     canonical state — an intentional exception documented here.
+ *     Persisted to canonical per the underlying scope authoring.
+ */
+
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type { ScopeBundle } from "../../public-types.ts";
+import type { UiApiContext } from "./_context.ts";
+
+export const getBundleMetadata: ApiV3FnMetadata = {
+  name: "ui.scope.getBundle",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scope-get-bundle.test.ts",
+    commit: "refactor-10-slice-ui-scope-mvp",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "ui-scope-read",
+  },
+  // UI-surface convenience wrapper over a canonical read. Classification
+  // mirrors the underlying `ai.getScopeBundle` — reading canonical
+  // scope state, not class-C local UI preference.
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§UI API § ui.scope.getBundle. Wraps handle.compileScopeBundleById(scopeId, nowUtc). nowUtc generated internally from new Date().toISOString() for ergonomic UI use; callers that need determinism (agent replay, tests) use ai.getScopeBundle with an explicit clock.",
+};
+
+export function createScopeFamily(ctx: UiApiContext) {
+  return {
+    getBundle(scopeId: string): ScopeBundle | null {
+      const compile = ctx.handle.compileScopeBundleById;
+      if (typeof compile !== "function") return null;
+      const nowUtc = new Date().toISOString();
+      return compile.call(ctx.handle, scopeId, nowUtc);
+    },
+  };
+}