@beyondwork/docx-react-component 1.0.67 → 1.0.70

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

@@ -0,0 +1,100 @@
+/**
+ * @endStateApi v3 — `ui.session` family (layer 10).
+ *
+ * Slice 2 — live. Pure state management inside the UI API instance: bind
+ * stores the controller on the shared context, getController reads it,
+ * release clears it. No runtime coupling at this layer; the controller is
+ * the seam.
+ *
+ * Contract U2 — UI API is bound to an opaque controller, not React
+ * internals. The same shape works for the React editor, a Playwright test,
+ * and a headless debug session.
+ */
+
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type { UiController, UiBinding } from "./_types.ts";
+import type { UiApiContext, BindingState } from "./_context.ts";
+
+export const bindMetadata: ApiV3FnMetadata = {
+  name: "ui.session.bind",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/session-bind.test.ts",
+    commit: "refactor-10-slice-2",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "compound", boundedScope: "session", auditCategory: "ui-session-bind" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.session.bind",
+};
+
+export const getControllerMetadata: ApiV3FnMetadata = {
+  name: "ui.session.getController",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/session-bind.test.ts",
+    commit: "refactor-10-slice-2",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-session-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.session.getController",
+};
+
+export const releaseMetadata: ApiV3FnMetadata = {
+  name: "ui.session.release",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/session-bind.test.ts",
+    commit: "refactor-10-slice-2",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "compound", boundedScope: "session", auditCategory: "ui-session-release" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.session.release",
+};
+
+export function createSessionFamily(ctx: UiApiContext) {
+  function makeBinding(state: BindingState): UiBinding {
+    return {
+      controller: state.controller,
+      release(): void {
+        if (state.released) return;
+        state.released = true;
+        // Only clear the root binding if it still points to this state —
+        // calling release() on a stale binding must NOT unbind a newer one.
+        if (ctx.binding === state) {
+          ctx.binding = null;
+        }
+      },
+    };
+  }
+  return {
+    bind(controller: UiController): UiBinding {
+      // Replace any prior binding. The prior binding's own release() is a
+      // no-op after this (its released flag will be set the next time it
+      // is invoked — and it can no longer affect ctx.binding).
+      if (ctx.binding) {
+        ctx.binding.released = true;
+      }
+      const state: BindingState = { controller, released: false };
+      ctx.binding = state;
+      return makeBinding(state);
+    },
+    getController(): UiController | null {
+      return ctx.binding?.controller ?? null;
+    },
+    release(): void {
+      if (ctx.binding) {
+        ctx.binding.released = true;
+        ctx.binding = null;
+      }
+    },
+  };
+}

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

@@ -0,0 +1,170 @@
+/**
+ * @endStateApi v3 — `ui.surface` family (layer 10).
+ *
+ * Slice 2 wiring:
+ *   - getSelection  — live. Reads `handle.getRenderSnapshot().selection`;
+ *                     returns null when the runtime has no snapshot.
+ *   - setSelection  — live-with-adapter. Delegates to the bound
+ *                     controller's `dispatchSelection` hook. Bidirectional
+ *                     channel U3.
+ *   - getViewport   — partial. Delegates to the controller's
+ *                     `getViewport` hook if provided; otherwise returns a
+ *                     mock default. Slice 3 replaces with a
+ *                     `GeometryFacet.getViewport()` read.
+ *   - scrollTo      — live-with-adapter. Delegates to the bound
+ *                     controller's `dispatchScroll`. Slice 3 adds
+ *                     geometry-backed resolution for block/scope/comment/
+ *                     revision targets before dispatch.
+ *
+ * Contract U3 — selection + viewport are the only bidirectional channels.
+ */
+
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type { SelectionSnapshot } from "../../public-types.ts";
+import type {
+  SelectionRangeInput,
+  ScrollTarget,
+  ViewportState,
+} from "./_types.ts";
+import type { UiApiContext } from "./_context.ts";
+import { readComposedViewport } from "./_context.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+
+export const getSelectionMetadata: ApiV3FnMetadata = {
+  name: "ui.surface.getSelection",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/selection-bidirectional.test.ts",
+    commit: "refactor-10-slice-2",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "selection", auditCategory: "ui-surface-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.surface.getSelection",
+};
+
+export const setSelectionMetadata: ApiV3FnMetadata = {
+  name: "ui.surface.setSelection",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/selection-bidirectional.test.ts",
+    commit: "refactor-10-slice-2",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "selection-change", expectedDelta: "selection moves to requested range" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "selection", auditCategory: "ui-surface-set-selection" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  // Dispatch-form bidirectional channel (U3): request flows UI → runtime
+  // via controller.dispatchSelection; the runtime's follow-up
+  // `selection.changed` emission is observed by the viewport / surface
+  // event stream, not by this call. No subscriptionShape — single-shot.
+  bidirectional: true,
+  rwdReference: "§UI API § ui.surface.setSelection. Adapter delegates to UiController.dispatchSelection; throws when the active binding has no dispatch hook.",
+};
+
+export const getViewportMetadata: ApiV3FnMetadata = {
+  name: "ui.surface.getViewport",
+  status: "partial",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/selection-bidirectional.test.ts",
+    commit: "refactor-10-slice-2",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription: "Default zeroed ViewportState (width/height/scroll=0, zoom/dpr=1) when no controller.getViewport hook is provided. Slice 3 promotes to live via GeometryFacet.getViewport().",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-surface-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.surface.getViewport",
+};
+
+export const scrollToMetadata: ApiV3FnMetadata = {
+  name: "ui.surface.scrollTo",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scroll-to.test.ts",
+    commit: "refactor-10-slice-2",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "surface-refresh", expectedDelta: "viewport scrolls to target" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-surface-scroll" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  // Dispatch-form bidirectional channel (U3): request flows UI → runtime
+  // via controller.dispatchScroll; viewport settles via rAF + the
+  // `ux.response.ui.surface.scrollTo` event announces the request.
+  bidirectional: true,
+  rwdReference: "§UI API § ui.surface.scrollTo. Adapter delegates to UiController.dispatchScroll. Slice 3 adds geometry-backed target resolution for block/scope/comment/revision kinds prior to dispatch.",
+};
+
+export function createSurfaceFamily(ctx: UiApiContext) {
+  return {
+    getSelection(): SelectionSnapshot | null {
+      // Per DS §8.3 (runtime owns truth), trust the handle contract.
+      // A thrown `getRenderSnapshot` is a runtime regression, not a
+      // pre-mount state — silent null would let the UI claim "no
+      // selection" while substrate is broken. Pre-mount handles use
+      // the inert-facet pattern (`loading-runtime-bridge.ts`).
+      const snapshot = ctx.handle.getRenderSnapshot();
+      return snapshot?.selection ?? null;
+    },
+    setSelection(range: SelectionRangeInput): void {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.surface.setSelection: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.dispatchSelection) {
+        throw new Error(
+          `ui.surface.setSelection: controller of kind "${controller.kind}" did not provide a dispatchSelection hook`,
+        );
+      }
+      controller.dispatchSelection(range);
+      emitUxResponse(ctx.handle, {
+        apiFn: setSelectionMetadata.name,
+        intent: setSelectionMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: setSelectionMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "selection-change", payload: { anchor: range.anchor, head: range.head } },
+      });
+    },
+    getViewport(): ViewportState {
+      // Shared composition with `ui.viewport.get` (Slice 11) — reads
+      // scroll/dpr/zoom from handle.geometry, width/height from the
+      // bound controller.
+      return readComposedViewport(ctx);
+    },
+    async scrollTo(target: ScrollTarget): Promise<void> {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.surface.scrollTo: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.dispatchScroll) {
+        throw new Error(
+          `ui.surface.scrollTo: controller of kind "${controller.kind}" did not provide a dispatchScroll hook`,
+        );
+      }
+      await controller.dispatchScroll(target);
+      emitUxResponse(ctx.handle, {
+        apiFn: scrollToMetadata.name,
+        intent: scrollToMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: scrollToMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { kind: target.kind, value: target.kind === "scope" || target.kind === "comment" || target.kind === "revision" || target.kind === "block" ? target.value : undefined } },
+      });
+    },
+  };
+}

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

@@ -0,0 +1,303 @@
+/**
+ * @endStateApi v3 — `ui.viewport` family (layer 10).
+ *
+ * Slice 11 wiring (2026-04-22 — refactor/10 adversarial closure):
+ *   - get        — live. Reads scroll / dpr / zoom directly from
+ *                  `handle.geometry.getViewport()` (available since
+ *                  refactor/05 adversarial closure). Width + height
+ *                  still come from the controller hook when present,
+ *                  because those are DOM-measured container dims and
+ *                  not in the geometry primitive. When neither geometry
+ *                  nor controller is available, returns a mock-flagged
+ *                  zeroed default.
+ *   - subscribe  — live-with-adapter. Delegates to the bound controller's
+ *                  `subscribeViewport` hook. Bind-side is responsible for
+ *                  rAF coalescing (U7). Throws when no controller is
+ *                  bound or the controller lacks the hook — consumers
+ *                  learn about misconfiguration rather than silently
+ *                  missing events.
+ *
+ * Contract U7 — subscribers receive runtime-time events plus coalesced
+ * rAF ticks for viewport. Never on raw PM transaction emission.
+ */
+
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type {
+  ViewportState,
+  UiListener,
+  UiUnsubscribe,
+  WorkflowMarkupMode,
+} from "./_types.ts";
+import type { UiApiContext } from "./_context.ts";
+import { readComposedViewport } from "./_context.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+
+export const getMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.get",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/viewport-subscribe.test.ts",
+    commit: "refactor-10-slice-11",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription: "Default zeroed ViewportState (width/height=0, scroll=0, zoom/dpr=1) when neither handle.geometry nor a controller.getViewport hook is available (headless pre-paint). Slice 11 sources scroll/dpr/zoom from handle.geometry.getViewport() and width/height from the controller hook when present.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.viewport.get. Reads scroll/dpr/zoom through handle.geometry.getViewport() directly (refactor/05 geometry facet). width/height come from controller.getViewport() when bound, since container-dim measurement is DOM-local and not in the geometry primitive.",
+};
+
+export const subscribeMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.subscribe",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/viewport-subscribe.test.ts",
+    commit: "refactor-07-slice-2",
+  },
+  // Stream-form bidirectional channel (U3 + U7). `uiVisible: true`
+  // because the subscribe call IS observable UX — registering a
+  // listener affects what the mounted surface paints on the next
+  // viewport change. The single `surface-refresh` ack fires on the
+  // establishing call; the rAF-coalesced stream is announced via
+  // `subscriptionShape`.
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "viewport subscriber attached; future scroll/zoom/dpr changes propagate through the listener",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.viewport.changed",
+    payloadType: "ViewportState",
+    coalescing: "raf",
+  },
+  rwdReference: "§UI API § ui.viewport.subscribe. Adapter delegates to UiController.subscribeViewport; throws when the active binding has no hook. Subscribe call emits one `ux.response.ui.viewport.subscribe` acknowledgement; per-tick ViewportState deliveries flow through the listener (rAF-coalesced, U7).",
+};
+
+// ----- X5 markup-mode metadata (state-classes cross-cutting Slice X5) -----
+
+/**
+ * Intrinsic default when no policy has been authored AND no local
+ * preference is set. "all" mirrors the shipped shell default: show
+ * insertions + deletions + suggestions so a user who hasn't touched
+ * the control sees changes.
+ */
+const INTRINSIC_DEFAULT_MARKUP_MODE: WorkflowMarkupMode = "all";
+
+export const getEffectiveMarkupModeMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.getEffectiveMarkupMode",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/markup-mode-composition.test.ts",
+    commit: "refactor-10-slice-x5",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.viewport.getEffectiveMarkupMode (X5). Composes class-A policy (handle.getMarkupModePolicy) with class-C local preference. enforcement 'always' hard-overrides the preference; 'authored-default' cedes to local preference.",
+};
+
+export const setLocalMarkupModeMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.setLocalMarkupMode",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/markup-mode-composition.test.ts",
+    commit: "refactor-10-slice-x5",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "markup-mode local preference set; subscribers receive the new composed mode",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-viewport-set-markup-mode" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.viewport.setLocalMarkupMode (X5). Class-C write.",
+};
+
+export const resetLocalMarkupModeMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.resetLocalMarkupMode",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/markup-mode-composition.test.ts",
+    commit: "refactor-10-slice-x5",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "markup-mode local preference cleared; subsequent reads fall back to policy",
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "session", auditCategory: "ui-viewport-reset-markup-mode" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§UI API § ui.viewport.resetLocalMarkupMode (X5).",
+};
+
+export const subscribeEffectiveMarkupModeMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.subscribeEffectiveMarkupMode",
+  status: "live",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/markup-mode-composition.test.ts",
+    commit: "refactor-10-slice-x5",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "markup-mode subscriber attached; future local-pref changes + L06 policy changes propagate through the listener",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.viewport.markup_mode_changed",
+    payloadType: "WorkflowMarkupMode",
+    coalescing: "microtask",
+  },
+  rwdReference: "§UI API § ui.viewport.subscribeEffectiveMarkupMode (X5). Fires on local-pref mutations AND on L06 class-A policy changes (chained through handle.subscribeMarkupModePolicy).",
+};
+
+export function createViewportFamily(ctx: UiApiContext) {
+  // Closure-local class-C markup-mode state (X5). Per-createUiApi-
+  // instance — two instances over the same handle hold independent
+  // preferences (same isolation pattern as U9 + rail-state).
+  let localMarkupMode: WorkflowMarkupMode | null = null;
+  const markupModeSubscribers = new Set<UiListener<WorkflowMarkupMode>>();
+
+  function readEffectiveMarkupMode(): WorkflowMarkupMode {
+    const policy = ctx.handle.getMarkupModePolicy?.() ?? null;
+    // enforcement "always" hard-overrides local preference.
+    if (policy?.enforcement === "always") {
+      return policy.mode;
+    }
+    // authored-default / no policy: local preference wins if expressed.
+    if (localMarkupMode !== null) {
+      return localMarkupMode;
+    }
+    // No preference → policy.mode (authored default) or intrinsic "all".
+    return policy?.mode ?? INTRINSIC_DEFAULT_MARKUP_MODE;
+  }
+
+  function notifyMarkupModeSubscribers(): void {
+    if (markupModeSubscribers.size === 0) return;
+    const mode = readEffectiveMarkupMode();
+    for (const listener of markupModeSubscribers) {
+      try {
+        listener(mode);
+      } catch {
+        // Isolate listener errors.
+      }
+    }
+  }
+
+  // Chain L06 policy changes into our subscribers so consumers get
+  // notified on class-A authoring (same pattern as U9 X1⇄X3).
+  // TODO(ui.dispose): retain the unsubscribe if a family-level dispose
+  // hook lands. The family instance lives for the lifetime of the
+  // handle today.
+  ctx.handle.subscribeMarkupModePolicy?.(() => {
+    notifyMarkupModeSubscribers();
+  });
+
+  return {
+    // Slice 11 — composes scroll/dpr/zoom from `handle.geometry` with
+    // width/height from the bound controller (see
+    // `readComposedViewport` in `_context.ts` for the shared
+    // implementation).
+    get(): ViewportState {
+      return readComposedViewport(ctx);
+    },
+    subscribe(listener: UiListener<ViewportState>): UiUnsubscribe {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.viewport.subscribe: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribeViewport) {
+        throw new Error(
+          `ui.viewport.subscribe: controller of kind "${controller.kind}" did not provide a subscribeViewport hook`,
+        );
+      }
+      const unsubscribe = controller.subscribeViewport(listener);
+      // Stream-form bidirectional ack: one UxResponse per subscribe call
+      // announcing "channel established". Per-tick ViewportState updates
+      // flow through the listener, not this event stream.
+      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.viewport" } },
+      });
+      return unsubscribe;
+    },
+
+    // ----- X5 markup-mode (state-classes cross-cutting Slice X5) -----
+
+    getEffectiveMarkupMode(): WorkflowMarkupMode {
+      return readEffectiveMarkupMode();
+    },
+
+    setLocalMarkupMode(mode: WorkflowMarkupMode): void {
+      if (localMarkupMode === mode) return; // idempotent.
+      localMarkupMode = mode;
+      emitUxResponse(ctx.handle, {
+        apiFn: setLocalMarkupModeMetadata.name,
+        intent: setLocalMarkupModeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: setLocalMarkupModeMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { markupMode: mode } },
+      });
+      notifyMarkupModeSubscribers();
+    },
+
+    resetLocalMarkupMode(): void {
+      if (localMarkupMode === null) return; // idempotent.
+      localMarkupMode = null;
+      emitUxResponse(ctx.handle, {
+        apiFn: resetLocalMarkupModeMetadata.name,
+        intent: resetLocalMarkupModeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: resetLocalMarkupModeMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { markupMode: "reset" } },
+      });
+      notifyMarkupModeSubscribers();
+    },
+
+    subscribeEffectiveMarkupMode(
+      listener: UiListener<WorkflowMarkupMode>,
+    ): UiUnsubscribe {
+      markupModeSubscribers.add(listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribeEffectiveMarkupModeMetadata.name,
+        intent: subscribeEffectiveMarkupModeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: subscribeEffectiveMarkupModeMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.viewport.markupMode" } },
+      });
+      return () => {
+        markupModeSubscribers.delete(listener);
+      };
+    },
+  };
+}

package/src/core/commands/index.ts

@@ -21,6 +21,27 @@ import {
   type MappingStep,
   type TransactionMapping,
 } from "../selection/mapping.ts";
+import {
+  toInternalAnchorProjection,
+  toPublicAnchorProjection,
+} from "../selection/anchor-conversion.ts";
+import type { EditorAnchorProjection as PublicEditorAnchorProjection } from "../../api/public-types.ts";
+
+/**
+ * Apply a transaction mapping to a record-attached (public flat) anchor.
+ * Record-attached anchors (on `EditorWarning` / `CompatibilityFeatureEntry`)
+ * carry the flat public shape; `mapAnchor` operates on the internal nested
+ * shape. Convert flat → nested → map → flat so the mapping composition
+ * logic stays in `mapping.ts` while records stay flat.
+ *
+ * See `docs/plans/cross-layer-coord-02.md §8`.
+ */
+function mapRecordAnchor(
+  anchor: PublicEditorAnchorProjection,
+  mapping: TransactionMapping,
+): PublicEditorAnchorProjection {
+  return toPublicAnchorProjection(mapAnchor(toInternalAnchorProjection(anchor), mapping));
+}
 import {
   createAcceptRevisionCommand,
   createRejectRevisionCommand,
@@ -37,6 +58,7 @@ import {
 } from "./text-commands.ts";
 import type {
   BlockNode,
+  MutableCanonicalDocument,
   RevisionRecord as CanonicalRevisionRecord,
 } from "../../model/canonical-document.ts";
 import { remapCommentThreads } from "../../review/store/comment-remapping.ts";
@@ -95,7 +117,7 @@ import { insertPageBreak, insertTable } from "./text-commands.ts";
 // is a **diamond** dependency (A → B, A → C, B → C), NOT a module-level
 // cycle — `text-commands.ts` does not re-enter `core/commands/index.ts`
 // or `runtime/edit-ops/`. Verified 2026-04-20 by static DFS; see
-// docs/plans/architecture-lane.md §F3. Keep it this way — don't add
+// CLAUDE.md (lane status table) §F3. Keep it this way — don't add
 // imports from `runtime/` that route through this file, as that could
 // introduce a real cycle.
 import { editLayer } from "../../runtime/edit-ops/index.ts";
@@ -527,7 +549,7 @@ export function executeEditorCommand(
               entry.affectedAnchor
                 ? {
                     ...entry,
-                    affectedAnchor: mapAnchor(entry.affectedAnchor, mapping),
+                    affectedAnchor: mapRecordAnchor(entry.affectedAnchor, mapping),
                   }
                 : entry,
             ),
@@ -574,7 +596,7 @@ export function executeEditorCommand(
               entry.affectedAnchor
                 ? {
                     ...entry,
-                    affectedAnchor: mapAnchor(entry.affectedAnchor, mapping),
+                    affectedAnchor: mapRecordAnchor(entry.affectedAnchor, mapping),
                   }
                 : entry,
             ),
@@ -1363,7 +1385,7 @@ export function applyDocumentPatch(
   contentChildren?: ContentChildrenPatch,
 ): CanonicalDocumentEnvelope {
   const nextContent = resolvePatchedContent(base, patch, contentChildren);
-  const merged: CanonicalDocumentEnvelope = { ...base, ...patch };
+  const merged: MutableCanonicalDocument = { ...base, ...patch };
   if (nextContent) {
     merged.content = nextContent;
   }
@@ -1445,7 +1467,7 @@ function buildDocumentReplaceTransaction(
           entry.affectedAnchor
             ? {
                 ...entry,
-                affectedAnchor: mapAnchor(entry.affectedAnchor, mapping),
+                affectedAnchor: mapRecordAnchor(entry.affectedAnchor, mapping),
               }
             : entry,
         ),
@@ -2094,7 +2116,7 @@ function mapWarningsThroughMapping(
     warning.affectedAnchor
       ? {
           ...warning,
-          affectedAnchor: mapAnchor(warning.affectedAnchor, mapping),
+          affectedAnchor: mapRecordAnchor(warning.affectedAnchor, mapping),
         }
       : warning,
   );

package/src/core/commands/list-commands.ts

@@ -2,6 +2,7 @@ import type {
   AbstractNumberingDefinition,
   BlockNode,
   CanonicalDocument as CanonicalDocumentEnvelope,
+  MutableCanonicalDocument,
   NumberingCatalog,
   NumberingInstance,
   ParagraphNode,
@@ -498,14 +499,14 @@ function ensureNumberingCatalog(value: NumberingCatalog): NumberingCatalog {
 function cloneEnvelope(
   document: CanonicalDocumentEnvelope,
   timestamp: string,
-): CanonicalDocumentEnvelope {
+): MutableCanonicalDocument {
   return {
     ...structuredClone(document),
     updatedAt: timestamp,
   };
 }
 
-function captureEditableParagraphs(document: CanonicalDocumentEnvelope): ParagraphNode[] {
+function captureEditableParagraphs(document: MutableCanonicalDocument): ParagraphNode[] {
   if (isDocumentRoot(document.content)) {
     const paragraphs: ParagraphNode[] = [];
     collectEditableParagraphs(document.content.children as BlockNode[], paragraphs);