@beyondwork/docx-react-component 1.0.67 → 1.0.70

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

@@ -0,0 +1,476 @@
+/**
+ * @endStateApi v3 — `ui.chrome` family (layer 10).
+ *
+ * Slice 4 wiring:
+ *   - getPosture         — live-with-adapter. Single composition site for
+ *                          ChromePosture. Reads the guard verdict from
+ *                          `handle.getInteractionGuardSnapshot()` and the
+ *                          mode/readOnly from `handle.getRenderSnapshot()`;
+ *                          overlays the host-provided slice (reviewMode,
+ *                          markupDisplay, debugMode, chromePreset) via
+ *                          `controller.getHostPosture()`. Host defaults
+ *                          applied at this layer — debugMode defaults to
+ *                          "off" per U6 + CLAUDE.md Protected Invariants.
+ *   - getPinnedSurfaces  — live-with-adapter. Delegates to
+ *                          `controller.getPinnedSurfaces()`; returns [] when
+ *                          unbound or the hook is absent. The existing
+ *                          `chrome-preset-model` lives in the presentation
+ *                          layer; the controller adapts it.
+ *   - subscribe          — live-with-adapter. Delegates to
+ *                          `controller.subscribeChrome`.
+ *
+ * Contract U5 — chrome posture is composed once per read at this single
+ * site. Components that call getPosture() do not re-derive from individual
+ * inputs. `refactor/10 Slice 6` migrates chrome components off their
+ * direct `getInteractionGuardSnapshot()` reads.
+ *
+ * Contract U6 — debug mode defaults "off". The default MUST survive every
+ * code path in this file. CLAUDE.md flags this has regressed multiple
+ * times; `test/api/v3/ui/chrome-posture-shape.test.ts` asserts it.
+ */
+
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type {
+  ChromePosture,
+  ChromeSurface,
+  ChromeDocumentMode,
+  UiListener,
+  UiUnsubscribe,
+} from "./_types.ts";
+import type {
+  ChromeComposition,
+  ChromeCompositionInput,
+  EditorRailTab,
+} from "./chrome-composition.ts";
+import { resolveChromeComposition } from "./chrome-composition.ts";
+import type { UiApiContext } from "./_context.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+
+export const getPostureMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.getPosture",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-posture-shape.test.ts",
+    commit: "refactor-10-slice-4",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-chrome-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § ui.chrome.getPosture. Composes handle.getInteractionGuardSnapshot() + handle.getRenderSnapshot() with controller.getHostPosture() at a single site. debugMode defaults 'off' per U6.",
+};
+
+export const getCompositionMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.getComposition",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-composition-shape.test.ts",
+    commit: "refactor-10-slice-9",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-chrome-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § ui.chrome.getComposition (U5.b). Pure function — wraps resolveChromeComposition from src/api/v3/ui/chrome-composition.ts. Input is host-supplied; output is the single ChromeComposition record every chrome surface reads. Caller memoizes.",
+};
+
+export const getPinnedSurfacesMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.getPinnedSurfaces",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-pinned-surfaces.test.ts",
+    commit: "refactor-10-slice-4",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-chrome-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § ui.chrome.getPinnedSurfaces. Adapter delegates to controller.getPinnedSurfaces which wraps chrome-preset-model on the bind-side.",
+};
+
+export const subscribeMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.subscribe",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-posture-coherence.test.ts",
+    commit: "refactor-07-slice-2",
+  },
+  // Stream-form bidirectional channel (U5 + U7). Posture changes
+  // (guard-snapshot updates, host posture flips like debugMode toggle)
+  // fan out through this listener. Coalescing is microtask — posture
+  // composes at most once per render tick, no rAF batching needed.
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "chrome subscriber attached; posture changes propagate through the listener",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-chrome-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.chrome.posture-changed",
+    payloadType: "ChromePosture",
+    coalescing: "microtask",
+  },
+  rwdReference: "§UI API § ui.chrome.subscribe. Adapter delegates to controller.subscribeChrome. Subscribe call emits one `ux.response.ui.chrome.subscribe` acknowledgement; per-change ChromePosture deliveries flow through the listener (microtask-coalesced).",
+};
+
+/**
+ * Normalize a `DocumentMode` (long form — "editing" / "suggesting" /
+ * "viewing" / "commenting") OR a `WorkflowScopeMode` (short form —
+ * "edit" / "suggest" / "view" / "comment") to the ChromePosture short
+ * form. Unknown values fall back to "edit" — the most permissive posture
+ * is the safest default.
+ */
+function normalizeDocumentMode(raw: string | undefined | null): ChromeDocumentMode {
+  switch (raw) {
+    case "editing":
+    case "edit":
+      return "edit";
+    case "suggesting":
+    case "suggest":
+      return "suggest";
+    case "commenting":
+    case "comment":
+      return "comment";
+    case "viewing":
+    case "view":
+      return "view";
+    default:
+      return "edit";
+  }
+}
+
+function normalizeEffectiveMode(
+  mode: string | undefined | null,
+): ChromePosture["effectiveMode"] {
+  if (mode === "blocked") return "blocked";
+  return normalizeDocumentMode(mode);
+}
+
+// Rail-state metadata — class-C per-session local state, owned by L10
+// per the three-way state model (§9.1).
+
+export const getActiveRailTabMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.getActiveRailTab",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-rail-state.test.ts",
+    commit: "refactor-10-task-2-rail-state",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-chrome-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.chrome.getActiveRailTab. Class-C rail state read — null when no tab is active. UI API owns the state; hosts persist across reloads via beforeunload save/restore if needed (no localStorage inside L10).",
+};
+
+export const setActiveRailTabMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.setActiveRailTab",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-rail-state.test.ts",
+    commit: "refactor-10-task-2-rail-state",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "rail active tab updated; subscribers receive the new value; next getComposition reflects the change",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-chrome-set-rail-state" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.chrome.setActiveRailTab (null closes the rail).",
+};
+
+export const getPinnedRailTabsMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.getPinnedRailTabs",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-rail-state.test.ts",
+    commit: "refactor-10-task-2-rail-state",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-chrome-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.chrome.getPinnedRailTabs.",
+};
+
+export const pinRailTabMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.pinRailTab",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-rail-state.test.ts",
+    commit: "refactor-10-task-2-rail-state",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "rail tab pinned; next getComposition reflects the pinned set",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-chrome-set-rail-state" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.chrome.pinRailTab. Idempotent.",
+};
+
+export const unpinRailTabMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.unpinRailTab",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-rail-state.test.ts",
+    commit: "refactor-10-task-2-rail-state",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "rail tab unpinned; next getComposition reflects the pinned set",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-chrome-set-rail-state" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.chrome.unpinRailTab. Idempotent.",
+};
+
+export const subscribeRailStateMetadata: ApiV3FnMetadata = {
+  name: "ui.chrome.subscribeRailState",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/chrome-rail-state.test.ts",
+    commit: "refactor-10-task-2-rail-state",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "rail-state subscriber attached; receives the new active tab on every set/pin/unpin that mutated state",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-chrome-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.chrome.rail_state_changed",
+    payloadType: "EditorRailTab | null",
+    coalescing: "microtask",
+  },
+  rwdReference: "§UI API § ui.chrome.subscribeRailState. Fires on any mutation to active-tab or pinned-set. Payload is the new active tab; consumers read the pinned set via getPinnedRailTabs.",
+};
+
+export function createChromeFamily(ctx: UiApiContext) {
+  // Closure-local class-C rail state. Per-createUiApi-instance — two
+  // instances over the same handle hold independent rail state (same
+  // isolation pattern as U9 overlay-visibility).
+  //
+  // `activeRailTabSet` distinguishes "user explicitly set activeRailTab"
+  // (including to `null`, meaning "close the rail") from "user hasn't
+  // expressed an opinion" (composer picks a mode-default). Without this
+  // flag, getComposition would force `null` for every caller that
+  // previously relied on the composer's mode-appropriate default.
+  let activeRailTab: EditorRailTab | null = null;
+  let activeRailTabSet = false;
+  const pinnedRailTabs = new Set<EditorRailTab>();
+  const railStateSubscribers = new Set<UiListener<EditorRailTab | null>>();
+
+  function notifyRailStateSubscribers(): void {
+    for (const listener of railStateSubscribers) {
+      try {
+        listener(activeRailTab);
+      } catch {
+        // Isolate listener errors.
+      }
+    }
+  }
+
+  return {
+    getPosture(): ChromePosture {
+      // Runtime-sourced slice — the guard + mode + readOnly. Per DS §8.3
+      // (runtime owns truth) we trust the RuntimeApiHandle contract —
+      // `getInteractionGuardSnapshot` and `getRenderSnapshot` are
+      // unconditional on the handle interface. A throw here is a runtime
+      // regression, not a "pre-mount" state, and masking it with a
+      // silent fallback would let the UI declare `effectiveMode: "edit"`
+      // while the substrate is broken. Pre-mount handles use the
+      // inert-facet pattern from `loading-runtime-bridge.ts`.
+      const guard = ctx.handle.getInteractionGuardSnapshot() as
+        | { effectiveMode?: string; blockedReasons?: ReadonlyArray<{ code?: string; reason?: string } | string> }
+        | undefined
+        | null;
+      const effectiveMode: ChromePosture["effectiveMode"] = guard
+        ? normalizeEffectiveMode(guard.effectiveMode)
+        : "edit";
+      const blockedReasons: readonly string[] =
+        guard && Array.isArray(guard.blockedReasons)
+          ? guard.blockedReasons.map((r) =>
+              typeof r === "string" ? r : (r?.code ?? r?.reason ?? "blocked"),
+            )
+          : [];
+
+      const render = ctx.handle.getRenderSnapshot() as
+        | { documentMode?: string; readOnly?: boolean }
+        | undefined
+        | null;
+      const documentMode: ChromeDocumentMode = render
+        ? normalizeDocumentMode(render.documentMode)
+        : "edit";
+      const readOnly = render?.readOnly === true;
+
+      // Host-provided slice — reviewMode / markupDisplay / debugMode /
+      // chromePreset. Defaults applied here; U6 — debugMode MUST default
+      // to "off" (CLAUDE.md Protected Invariants).
+      const host = ctx.binding?.controller.getHostPosture?.() ?? undefined;
+      const reviewMode = host?.reviewMode ?? "observer";
+      const markupDisplay = host?.markupDisplay ?? "final";
+      const debugMode = host?.debugMode ?? "off";
+      const chromePreset = host?.chromePreset;
+
+      return {
+        effectiveMode,
+        documentMode,
+        readOnly,
+        reviewMode,
+        markupDisplay,
+        debugMode,
+        chromePreset,
+        blockedReasons,
+      };
+    },
+    getComposition(input: ChromeCompositionInput): ChromeComposition {
+      // U5.b — compose with class-C rail state the UI API owns. The
+      // caller can override `activeRailTab` / `pinnedRailTabs` via input;
+      // when omitted AND the UI API's internal state has been set,
+      // internal state fills in. When the caller omits AND internal state
+      // is untouched (the initial-mount path), the composer's mode-default
+      // kicks in (e.g. rail open on "advanced" preset picks a default
+      // active tab per mode). This preserves back-compat for callers that
+      // never interacted with rail-state methods.
+      const merged: ChromeCompositionInput = {
+        ...input,
+        ...(input.activeRailTab !== undefined
+          ? {}
+          : activeRailTabSet
+            ? { activeRailTab }
+            : {}),
+        ...(input.pinnedRailTabs !== undefined
+          ? {}
+          : pinnedRailTabs.size > 0
+            ? { pinnedRailTabs }
+            : {}),
+      };
+      return resolveChromeComposition(merged);
+    },
+    getPinnedSurfaces(): readonly ChromeSurface[] {
+      const hook = ctx.binding?.controller.getPinnedSurfaces;
+      return hook ? hook() : [];
+    },
+    subscribe(listener: UiListener<ChromePosture>): UiUnsubscribe {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.chrome.subscribe: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribeChrome) {
+        throw new Error(
+          `ui.chrome.subscribe: controller of kind "${controller.kind}" did not provide a subscribeChrome hook`,
+        );
+      }
+      const unsubscribe = controller.subscribeChrome(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.chrome" } },
+      });
+      return unsubscribe;
+    },
+
+    // ----- Class-C rail state (Task 2) -----
+
+    getActiveRailTab(): EditorRailTab | null {
+      return activeRailTab;
+    },
+
+    setActiveRailTab(tab: EditorRailTab | null): void {
+      if (activeRailTabSet && activeRailTab === tab) return; // idempotent.
+      activeRailTab = tab;
+      activeRailTabSet = true;
+      emitUxResponse(ctx.handle, {
+        apiFn: setActiveRailTabMetadata.name,
+        intent: setActiveRailTabMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: setActiveRailTabMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { activeRailTab: tab } },
+      });
+      notifyRailStateSubscribers();
+    },
+
+    getPinnedRailTabs(): ReadonlySet<EditorRailTab> {
+      // Return a defensive snapshot — mutation on the caller side must
+      // not leak into UI API state.
+      return new Set(pinnedRailTabs);
+    },
+
+    pinRailTab(tab: EditorRailTab): void {
+      if (pinnedRailTabs.has(tab)) return;
+      pinnedRailTabs.add(tab);
+      emitUxResponse(ctx.handle, {
+        apiFn: pinRailTabMetadata.name,
+        intent: pinRailTabMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: pinRailTabMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { pinned: tab } },
+      });
+      notifyRailStateSubscribers();
+    },
+
+    unpinRailTab(tab: EditorRailTab): void {
+      if (!pinnedRailTabs.has(tab)) return;
+      pinnedRailTabs.delete(tab);
+      emitUxResponse(ctx.handle, {
+        apiFn: unpinRailTabMetadata.name,
+        intent: unpinRailTabMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: unpinRailTabMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { unpinned: tab } },
+      });
+      notifyRailStateSubscribers();
+    },
+
+    subscribeRailState(
+      listener: UiListener<EditorRailTab | null>,
+    ): UiUnsubscribe {
+      railStateSubscribers.add(listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribeRailStateMetadata.name,
+        intent: subscribeRailStateMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: subscribeRailStateMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.chrome.railState" } },
+      });
+      return () => {
+        railStateSubscribers.delete(listener);
+      };
+    },
+  };
+}

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

@@ -0,0 +1,124 @@
+/**
+ * @endStateApi v3 — `ui.debug` family (layer 10).
+ *
+ * Slice 5 wiring:
+ *   - attach  — live-with-adapter. Delegates to the bound controller's
+ *               `attachDebug` hook, which on the bind-side wires
+ *               `runtime.debug.bus` + `runtime.debug.getSnapshot` to the
+ *               mounted debug surface. Returns a DebugAttachment whose
+ *               `detach` invokes the controller-provided cleanup and
+ *               clears the UI API's attachment record.
+ *   - detach  — live-with-adapter. Ends the current attachment (if any)
+ *               by invoking its controller-provided cleanup. Idempotent
+ *               — calling detach without an attachment is a no-op.
+ *
+ * Phase Q (runtime-embedded debug UX at `src/ui-tailwind/debug/**`) is the
+ * presentation consumer of this surface. Per refactor plan 10 risk register
+ * #3 and §9 finishing-development-branch discipline, Slice 5 ships the
+ * substrate; the Phase Q React components + `debugMode` public prop +
+ * `test/ui/debug-mode-visibility-invariant.test.ts` land in a follow-up.
+ * `src/ui-tailwind/debug/README.md` documents the reserved scope.
+ *
+ * Contract U6 — debug attachment is opt-in and scoped. Default state:
+ * no debug UX. The `debugMode` prop gate (to-be-added) defaults to
+ * `"off"`. CLAUDE.md Protected Invariants flag this has regressed
+ * multiple times.
+ */
+
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type { DebugSession, DebugAttachment } from "./_types.ts";
+import type { UiApiContext } from "./_context.ts";
+
+export const attachMetadata: ApiV3FnMetadata = {
+  name: "ui.debug.attach",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/debug-attach.test.ts",
+    commit: "refactor-10-slice-5",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "compound", boundedScope: "session", auditCategory: "ui-debug-attach" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § ui.debug.attach. Adapter delegates to UiController.attachDebug which on the bind-side wires runtime.debug.bus + getSnapshot to the mounted debug surface. Throws when no controller is bound or the hook is absent.",
+};
+
+export const detachMetadata: ApiV3FnMetadata = {
+  name: "ui.debug.detach",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/debug-attach.test.ts",
+    commit: "refactor-10-slice-5",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "compound", boundedScope: "session", auditCategory: "ui-debug-detach" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § ui.debug.detach. Idempotent — invokes the controller-provided cleanup from the active attachment (if any) and clears the record.",
+};
+
+interface DebugAttachmentState {
+  session: DebugSession;
+  cleanup: () => void;
+}
+
+export function createDebugFamily(ctx: UiApiContext) {
+  // Per-instance attachment state. One UI API holds at most one active
+  // debug attachment; re-attaching tears down the prior attachment first.
+  let current: DebugAttachmentState | null = null;
+
+  function detachInternal(): void {
+    if (current) {
+      try {
+        current.cleanup();
+      } finally {
+        current = null;
+      }
+    }
+  }
+
+  return {
+    attach(session: DebugSession): DebugAttachment {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.debug.attach: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.attachDebug) {
+        throw new Error(
+          `ui.debug.attach: controller of kind "${controller.kind}" did not provide an attachDebug hook`,
+        );
+      }
+      // Tear down any prior attachment so re-attaching does not leak
+      // subscriptions or telemetry-bus listeners.
+      detachInternal();
+      const cleanup = controller.attachDebug(session);
+      current = { session, cleanup };
+      // NOTE: `DebugAttachment.detach` is aliased to `detachInternal`,
+      // which detaches **whatever is currently attached** — not
+      // specifically the session this attachment was created with. At
+      // most one attachment is live per UI API instance, so this is
+      // semantically correct under the "single attachment at a time"
+      // model. Callers that hold onto an older `attachment` ref and
+      // call its `.detach()` after a re-attach will tear down the
+      // NEWER attachment. Typical hosts create + detach in lockstep
+      // (attach on mount, detach on unmount), so this is fine; the
+      // debug service's RPC driver re-attaches on every session, which
+      // matches this model.
+      return {
+        session,
+        detach: detachInternal,
+      };
+    },
+    detach(): void {
+      // Idempotent — no-op when nothing is attached. See U6; the default
+      // state is "no debug UX", so repeated detach calls must stay safe.
+      detachInternal();
+    },
+  };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * @endStateApi v3 — UI API barrel (layer 10).
+ *
+ * Public exports for `src/api/v3/ui/**`. Consumers import from this barrel
+ * rather than individual family files.
+ */
+
+export { createUiApi } from "./_create.ts";
+export type {
+  ApiV3Ui,
+  ApiV3UiSession,
+  ApiV3UiSurface,
+  ApiV3UiViewport,
+  ApiV3UiOverlays,
+  ApiV3UiChrome,
+  ApiV3UiDebug,
+  ApiV3UiScope,
+  UiController,
+  UiControllerKind,
+  UiControllerFactory,
+  UiBinding,
+  UiListener,
+  UiUnsubscribe,
+  ViewportState,
+  ScrollTarget,
+  ScrollTargetBehavior,
+  SelectionRangeInput,
+  OverlayAnchorQuery,
+  OverlayKind,
+  OverlayVisibility,
+  WorkflowMarkupMode,
+  ChromePosture,
+  ChromeHostPosture,
+  ChromeSurface,
+  ChromeSurfaceKind,
+  ChromeDocumentMode,
+  ChromeMarkupDisplay,
+  ChromeReviewMode,
+  ChromeDebugMode,
+  DebugSession,
+  DebugAttachment,
+  GeometryRect,
+} from "./_types.ts";
+
+// Chrome composition types (U5.b) — relocated to layer 10 in Slice 8.
+export { CHROME_RESPONSIVE_THRESHOLDS, resolveChromeComposition } from "./chrome-composition.ts";
+export type {
+  ChromeComposition,
+  ChromeCompositionInput,
+  ChromeDensity,
+  ChromeResponsiveTier,
+  DiagnosticsSeverity,
+  DiagnosticsSignal,
+  EditorChromeMode,
+  EditorRailTab,
+  LocalSurfaceKind,
+  RailComposition,
+  WorkspaceRowComposition,
+} from "./chrome-composition.ts";
+export {
+  resolveChromePreset,
+  resolveChromePresetOptions,
+  resolveChromeVisibilityForPreset,
+} from "./chrome-preset-model.ts";