@beyondwork/docx-react-component 1.0.73 → 1.0.74

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.73",
+  "version": "1.0.74",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/anchor-conversion.ts

@@ -23,8 +23,8 @@ export function toPublicAnchorProjection(
     case "range":
       return {
         kind: "range",
-        from: anchor.range.from,
-        to: anchor.range.to,
+        from: anchor.from,
+        to: anchor.to,
         assoc: anchor.assoc,
       };
     case "node":

package/src/api/public-types.ts

@@ -92,6 +92,8 @@ export type {
   ScopeRailSegment,
 } from "../runtime/workflow/rail/types.ts";
 
+import type { ScopeRailSegment as _ScopeRailSegment } from "../runtime/workflow/rail/types.ts";
+
 /**
  * Substrate-type re-exports consumed by Layer-11 overlay + chrome
  * surfaces (refactor/11 type-only retirement sweep). Every entry below
@@ -1581,14 +1583,17 @@ export interface EditorSurfaceSnapshot {
   lockedFragmentIds: string[];
   secondaryStories: SecondaryStorySurface[];
   /**
-   * Block index range rendered as real (non-placeholder) in this snapshot.
-   * Blocks outside this range are placeholder opaque_blocks carrying the
-   * original position range but no content. `null` (default) = all blocks
-   * are real (legacy behavior).
+   * Block-index intervals rendered as real (non-placeholder) in this snapshot.
+   * Blocks whose index falls in ANY interval are real; all others are
+   * placeholder opaque_blocks that preserve the original position range but
+   * carry no content. `null` (default) = all blocks are real (legacy).
    *
-   * See CLAUDE.md (lane status table)
+   * Typically one interval (the current viewport + overscan), but when the
+   * caret is scrolled off-screen a second interval covering the caret's page
+   * keeps the selection block real without realizing the full gap between
+   * viewport and caret. See `docs/wiki/performance.md` §"Viewport realization".
    */
-  viewportBlockRange: { start: number; end: number } | null;
+  viewportBlockRanges: readonly { start: number; end: number }[] | null;
 }
 
 export type EditorWarningCode =
@@ -2959,6 +2964,28 @@ export interface ScopeCardModel {
   agentPending: boolean;
 }
 
+/**
+ * UI-API scope rail snapshot — KI-008 presentation projection (2026-04-24).
+ *
+ * Plain-value envelope wrapping `ScopeRailSegment[]` so L10
+ * `ui.scope.rail(options?)` returns a stable shape regardless of
+ * page filtering. Chrome consumers reading the rail get the segments
+ * + a stamp of what narrowing the snapshot represents (no page =
+ * "all pages" on the active story; `pageIndex` set = only segments
+ * on that page).
+ *
+ * No React handlers, no DOM refs — agents + non-React hosts consume
+ * this safely. Host chrome wires event handlers in its own tree.
+ */
+export interface ScopeRailSnapshot {
+  readonly segments: readonly _ScopeRailSegment[];
+  /**
+   * Present only when the caller narrowed to a single page. Absent =
+   * the snapshot spans every page the runtime's page graph knows about.
+   */
+  readonly pageIndex?: number;
+}
+
 export interface WorkflowBlockedCommandReason {
   code:
     | "outside_workflow_scope"

package/src/api/v3/_runtime-handle.ts

@@ -91,6 +91,18 @@ export type RuntimeApiHandle = Pick<
   // Exposing this scopeId-keyed compile primitive on the handle lets
   // `ui/scope.ts` deliver `SemanticScope` / `ScopeBundle` reads directly.
   | "compileScopeBundleById"
+  // KI-008 (2026-04-24): batch enumeration primitive — L10 `ui.scope.list`
+  // reaches `SemanticScope[]` through the handle without importing
+  // src/runtime/scopes/** (blocked by ci-check-ui-api-layer-purity).
+  // Mirror / delegate of `ai.listScopes({kind?, limit?})`.
+  | "compileScopeList"
+  // KI-008 close (2026-04-24): presentation-shaped projections —
+  // `ui.scope.card(scopeId)` + `ui.scope.rail(options?)`. Both
+  // delegate through the same WorkflowFacet rail/card projectors
+  // L11 chrome already consumes; the handle primitives are the
+  // L10-seam equivalents.
+  | "compileScopeCardById"
+  | "compileScopeRailSnapshot"
   // Layer-08 Slice-5 — scope-scoped replacement dispatch. `ai.apply
   // ReplacementScope` + `runtime.content.replaceText(scopeId, …)`
   // route compiled plans through this seam.
@@ -152,6 +164,9 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   getScope: true,
   getLocationForAnchor: true,
   compileScopeBundleById: true,
+  compileScopeList: true,
+  compileScopeCardById: true,
+  compileScopeRailSnapshot: true,
   applyScopeReplacement: true,
   debug: true,
   layout: true,

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

@@ -436,7 +436,28 @@ export interface ApiV3UiOverlays {
   getAnchor(query: OverlayAnchorQuery): GeometryRect | null;
   /** Multi-rect coverage for scope envelopes. Empty array when unavailable. */
   getRects(query: OverlayAnchorQuery): readonly GeometryRect[];
+  /**
+   * Coarse overlay-invalidation subscription. Listener wakes on every
+   * render-frame revision. Callers interested in a specific anchor
+   * should prefer `subscribeQuery(query, listener)` (KI-006 close) —
+   * rect-diffed per-query delivery over a shared coarse tick.
+   */
   subscribe(listener: UiListener<OverlayAnchorQuery>): UiUnsubscribe;
+  /**
+   * Per-query coalesced subscription. Registers on the shared coarse
+   * `subscribeOverlays` tick lazily; re-resolves the query on every
+   * tick via `getAnchor`; fires only when the query's rect actually
+   * changes (null → rect, rect → null, or structural delta). Listener
+   * receives the new `GeometryRect | null` value.
+   *
+   * N subscribers on the same query share one memoized rect channel
+   * and all fire once per real change. Torn down automatically when
+   * the last subscriber for the last query unsubscribes.
+   */
+  subscribeQuery(
+    query: OverlayAnchorQuery,
+    listener: UiListener<GeometryRect | null>,
+  ): UiUnsubscribe;
 
   /**
    * U9 · Composed overlay visibility. Merges the class-A policy from

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

@@ -39,6 +39,7 @@
 
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
+  ChromePosture,
   GeometryRect,
   OverlayAnchorQuery,
   OverlayVisibility,
@@ -165,7 +166,34 @@ export const subscribeMetadata: ApiV3FnMetadata = {
     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.",
+  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. Coarse channel — listener wakes on every overlay invalidation; callers interested in a specific anchor should use `subscribeQuery(query, listener)` (KI-006 close) for rect-diffed per-query delivery.",
+};
+
+// ----- KI-006 close — per-query coalesced subscription ---------------------
+
+export const subscribeQueryMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.subscribeQuery",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-subscribe-query.test.ts",
+    commit: "refactor-10-slice-ki-006",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "per-query overlay subscriber attached; listener fires only when the query's rect actually changes (rect-diffed coalescer on top of the coarse subscribe channel)",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "ui-overlays-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.overlays.query_changed",
+    payloadType: "GeometryRect",
+    coalescing: "raf",
+  },
+  rwdReference: "§UI API § ui.overlays.subscribeQuery (KI-006 close). Per-query coalesced variant of `subscribe`. Registers a shared coarse `controller.subscribeOverlays` tick on the first query subscription; re-resolves each attached query on every tick via `getAnchor(query)` (memoized); fires per-query listeners only when the rect actually changes. Torn down on last unsubscribe. Listener receives the new `GeometryRect | null` value. Callers that need the full invalidation stream keep using `subscribe(listener)`.",
 };
 
 // ----- U9 overlay-visibility metadata (state-classes X3) -----
@@ -245,7 +273,7 @@ export const subscribeVisibilityMetadata: ApiV3FnMetadata = {
     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.",
+  rwdReference: "§UI API § ui.overlays.subscribeVisibility (U9). Fires on THREE channels: (a) local-preference mutation, (b) class-A policy-change (chained to L06's `handle.subscribeVisibilityPolicy`, shipped 2026-04-22), (c) `ChromePosture.debugMode` transitions on the `debug-panel` kind (chained to the bound controller's `subscribeChrome`, shipped 2026-04-24 closing KI-007). Chrome fan-out is lazy — registered on the first `debug-panel` subscriber, torn down on the last. debugMode-comparison-based firing avoids false fan-out on unrelated chrome ticks (reviewMode, markupDisplay).",
 };
 
 export function createOverlaysFamily(ctx: UiApiContext) {
@@ -285,6 +313,170 @@ export function createOverlaysFamily(ctx: UiApiContext) {
     }
   });
 
+  // KI-007 close — chrome-change fan-out for `debug-panel` visibility.
+  //
+  // The composed `debug-panel` visibility depends on three inputs:
+  // (a) class-A policy, (b) class-C local preference, and (c)
+  // ChromePosture.debugMode. Fan-out for (a) + (b) was already wired;
+  // (c) was the missing channel. Now registered lazily on the first
+  // `subscribeVisibility("debug-panel", …)` call and torn down when the
+  // last such subscriber unsubscribes, so the chrome-listener cost only
+  // applies when someone is actually listening.
+  //
+  // Comparison-based firing: we compare `ChromePosture.debugMode` to
+  // the previous value on each chrome tick and only re-notify when it
+  // changes. This avoids firing debug-panel visibility subscribers on
+  // unrelated chrome changes (reviewMode flip, markup-display change,
+  // etc.) — cost-efficient + semantically correct.
+  //
+  // Note on re-bind: if the host calls `ui.session.release()` then
+  // `bind(newController)`, the chrome-listener's underlying hook is
+  // torn down with the old controller. Consumers already subscribed to
+  // debug-panel visibility continue holding their listeners but stop
+  // receiving chrome-tick fan-out until they unsubscribe and re-
+  // subscribe. Release+rebind is a lifecycle event hosts handle
+  // explicitly; documented here rather than auto-re-registering
+  // because a full bind-cycle integration would also require reading
+  // the initial posture to seed `lastKnownDebugMode`, which is out of
+  // scope for this targeted fix.
+  let chromeUnsubscribe: (() => void) | null = null;
+  let lastKnownDebugMode: ChromePosture["debugMode"] | undefined;
+
+  function ensureChromeFanout(): void {
+    if (chromeUnsubscribe) return;
+    const controller = ctx.binding?.controller;
+    if (!controller?.subscribeChrome) return;
+    // Seed last-known from the current posture so the first real change
+    // doesn't false-fire against undefined.
+    const posture = readPostureForDebugModeSeed(ctx);
+    lastKnownDebugMode = posture?.debugMode;
+    chromeUnsubscribe = controller.subscribeChrome((next) => {
+      const nextMode = next?.debugMode;
+      if (nextMode === lastKnownDebugMode) return;
+      lastKnownDebugMode = nextMode;
+      notifyVisibilitySubscribers(ctx, visibilityState, "debug-panel");
+    });
+  }
+
+  function releaseChromeFanoutIfEmpty(): void {
+    const debugPanelSubs = visibilityState.subscribers.get("debug-panel");
+    if (debugPanelSubs && debugPanelSubs.size > 0) return;
+    if (chromeUnsubscribe) {
+      chromeUnsubscribe();
+      chromeUnsubscribe = null;
+      lastKnownDebugMode = undefined;
+    }
+  }
+
+  // KI-006 close — per-query coalesced subscribe channel.
+  //
+  // The coarse `subscribe(listener)` delegates to `controller.
+  // subscribeOverlays` and fires on every render-frame revision. That's
+  // correct but ergonomically coarse: consumers that care about a
+  // specific anchor wake on every frame and must re-query + compare
+  // manually. `subscribeQuery(query, listener)` is the per-query
+  // variant: it shares a single coarse tick across all query
+  // subscribers, re-resolves each attached query on every tick via
+  // `getAnchor(query)`, compares the new rect to the memoized previous
+  // rect, and only fires listeners whose query's rect actually changed.
+  //
+  // - Lazy registration: coarse subscriber registered on first
+  //   `subscribeQuery` call; torn down on last unsubscribe.
+  // - Shared tick: N query subscribers share 1 coarse subscription.
+  // - Rect-diff firing: null → rect, rect → null, and non-zero rect
+  //   delta all count as changes; structural equality (same topPx /
+  //   leftPx / widthPx / heightPx) suppresses fire.
+  // - Keyed by serialized query (`${kind}:${value}`): two subscribers
+  //   on the same query share the memoized rect and both fire once
+  //   per real change.
+  //
+  // Cost: O(attached queries) per frame. For typical overlay loads
+  // (scope-card, comment-bubble, revision-bar) this is O(10) per
+  // frame — bounded and cheap.
+  interface QueryChannel {
+    query: OverlayAnchorQuery;
+    lastRect: GeometryRect | null;
+    listeners: Set<UiListener<GeometryRect | null>>;
+  }
+  const queryChannels = new Map<string, QueryChannel>();
+  let queryCoarseUnsubscribe: (() => void) | null = null;
+
+  function queryKey(q: OverlayAnchorQuery): string {
+    // `selection` is a singleton kind with no `value` — key by kind alone.
+    return q.kind === "selection" ? "selection" : `${q.kind}:${q.value}`;
+  }
+
+  function rectsEqual(a: GeometryRect | null, b: GeometryRect | null): boolean {
+    if (a === null || b === null) return a === b;
+    return (
+      a.topPx === b.topPx &&
+      a.leftPx === b.leftPx &&
+      a.widthPx === b.widthPx &&
+      a.heightPx === b.heightPx
+    );
+  }
+
+  function resolveQueryRect(query: OverlayAnchorQuery): GeometryRect | null {
+    // Reuse the id-keyed geometry path from getAnchor; skip the
+    // selection bridge fallback because subscribeQuery is anchor-
+    // oriented and selection would be a caller-owned subscription
+    // off `ui.surface` when that ships. For selection queries today,
+    // we fall back to the getSelectionRects read and take the first
+    // rect (consistent with getAnchor's selection handling).
+    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;
+    return hook ? hook(query) : null;
+  }
+
+  function diffAndFireAllQueries(): void {
+    for (const channel of queryChannels.values()) {
+      if (channel.listeners.size === 0) continue;
+      const next = resolveQueryRect(channel.query);
+      if (rectsEqual(channel.lastRect, next)) continue;
+      channel.lastRect = next;
+      for (const listener of channel.listeners) {
+        try {
+          listener(next);
+        } catch {
+          // Isolate per-listener errors.
+        }
+      }
+    }
+  }
+
+  function ensureQueryCoarseTick(): void {
+    if (queryCoarseUnsubscribe) return;
+    const controller = ctx.binding?.controller;
+    if (!controller?.subscribeOverlays) return;
+    queryCoarseUnsubscribe = controller.subscribeOverlays(() => {
+      diffAndFireAllQueries();
+    });
+  }
+
+  function releaseQueryCoarseTickIfEmpty(): void {
+    // If any channel still has listeners, keep the coarse tick alive.
+    for (const channel of queryChannels.values()) {
+      if (channel.listeners.size > 0) return;
+    }
+    if (queryCoarseUnsubscribe) {
+      queryCoarseUnsubscribe();
+      queryCoarseUnsubscribe = null;
+    }
+  }
+
   return {
     getAnchor(query: OverlayAnchorQuery): GeometryRect | null {
       // `kind: "selection"` — bridge-first, geometry fallback.
@@ -362,6 +554,59 @@ export function createOverlaysFamily(ctx: UiApiContext) {
       return unsubscribe;
     },
 
+    subscribeQuery(
+      query: OverlayAnchorQuery,
+      listener: UiListener<GeometryRect | null>,
+    ): UiUnsubscribe {
+      // KI-006 close — per-query coalesced variant of `subscribe`.
+      // Shares one coarse `controller.subscribeOverlays` tick across
+      // all query subscribers, rect-diffs per query on each tick, and
+      // only fires listeners whose query rect actually changed.
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.overlays.subscribeQuery: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribeOverlays) {
+        throw new Error(
+          `ui.overlays.subscribeQuery: controller of kind "${controller.kind}" did not provide a subscribeOverlays hook`,
+        );
+      }
+
+      const key = queryKey(query);
+      let channel = queryChannels.get(key);
+      if (!channel) {
+        channel = {
+          query,
+          lastRect: resolveQueryRect(query),
+          listeners: new Set(),
+        };
+        queryChannels.set(key, channel);
+      }
+      channel.listeners.add(listener);
+      ensureQueryCoarseTick();
+
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribeQueryMetadata.name,
+        intent: subscribeQueryMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: subscribeQueryMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.overlays.query", query: key } },
+      });
+
+      return () => {
+        const current = queryChannels.get(key);
+        if (!current) return;
+        current.listeners.delete(listener);
+        if (current.listeners.size === 0) {
+          queryChannels.delete(key);
+        }
+        releaseQueryCoarseTickIfEmpty();
+      };
+    },
+
     // ----- U9 overlay-visibility (state-classes X3) -----
 
     getVisibility(kind: OverlayKind): OverlayVisibility {
@@ -408,6 +653,12 @@ export function createOverlaysFamily(ctx: UiApiContext) {
         visibilityState.subscribers.set(kind, listeners);
       }
       listeners.add(listener);
+      // KI-007 — lazy-register the chrome-change fan-out when the first
+      // debug-panel subscriber lands. No-op for other kinds + idempotent
+      // when a chrome listener is already active.
+      if (kind === "debug-panel") {
+        ensureChromeFanout();
+      }
       emitUxResponse(ctx.handle, {
         apiFn: subscribeVisibilityMetadata.name,
         intent: subscribeVisibilityMetadata.uxIntent.expectedDelta ?? "",
@@ -421,7 +672,30 @@ export function createOverlaysFamily(ctx: UiApiContext) {
         if (!current) return;
         current.delete(listener);
         if (current.size === 0) visibilityState.subscribers.delete(kind);
+        // KI-007 — tear down the chrome-change fan-out when the last
+        // debug-panel subscriber unsubscribes.
+        if (kind === "debug-panel") {
+          releaseChromeFanoutIfEmpty();
+        }
       };
     },
   };
 }
+
+/**
+ * KI-007 helper — read the current `ChromePosture.debugMode` value so
+ * the chrome-change fan-out can seed its `lastKnownDebugMode` tracker
+ * without false-firing on the first tick. Mirrors the logic in
+ * `chrome.ts::getPosture` but only extracts `debugMode` + returns
+ * `undefined` on any missing piece (rather than composing a full
+ * posture). Keeps the debug-panel fan-out path cheap.
+ */
+function readPostureForDebugModeSeed(
+  ctx: UiApiContext,
+): { debugMode: ChromePosture["debugMode"] } | null {
+  const hook = ctx.binding?.controller.getHostPosture;
+  if (!hook) return null;
+  const host = hook();
+  if (!host) return null;
+  return { debugMode: host.debugMode ?? "off" };
+}

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

@@ -33,9 +33,92 @@
  */
 
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
-import type { ScopeBundle } from "../../public-types.ts";
+import type {
+  ScopeBundle,
+  ScopeCardModel,
+  ScopeRailSnapshot,
+  SemanticScope,
+  SemanticScopeKind,
+} from "../../public-types.ts";
 import type { UiApiContext } from "./_context.ts";
 
+export interface UiScopeListFilter {
+  readonly kind?: SemanticScopeKind;
+  readonly limit?: number;
+}
+
+export interface UiScopeRailOptions {
+  /**
+   * Narrow the snapshot to a single page index. Omit (default) to
+   * span every page the runtime's page graph knows about.
+   */
+  readonly pageIndex?: number;
+}
+
+export const cardMetadata: ApiV3FnMetadata = {
+  name: "ui.scope.card",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scope-card-rail.test.ts",
+    commit: "refactor-10-ki-008-ui-scope-card-rail",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "ui-scope-card-read",
+  },
+  // Same classification as other `ui.scope.*` reads — canonical scope
+  // projection (not class-C local preference). KI-008 close.
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§UI API § ui.scope.card. Wraps handle.compileScopeCardById(scopeId) which projects runtime.workflow.getAllScopeCardModels() filtered to the matching scope. Returns plain-value ScopeCardModel — no React handlers, no DOM refs. Hosts wire event handlers in their own chrome tree.",
+};
+
+export const railMetadata: ApiV3FnMetadata = {
+  name: "ui.scope.rail",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scope-card-rail.test.ts",
+    commit: "refactor-10-ki-008-ui-scope-card-rail",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "ui-scope-rail-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§UI API § ui.scope.rail. Wraps handle.compileScopeRailSnapshot({pageIndex?}) which projects runtime.workflow.getRailSegments(pageIndex) / getAllRailSegments() into a ScopeRailSnapshot envelope. Plain-value data; no React handlers.",
+};
+
+export const listMetadata: ApiV3FnMetadata = {
+  name: "ui.scope.list",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scope-list.test.ts",
+    commit: "refactor-10-ki-008-ui-scope-list",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "ui-scope-list",
+  },
+  // Same classification as `ui.scope.getBundle` — reads canonical
+  // scope state (not class-C local preference). KI-008 closure.
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§UI API § ui.scope.list. Wraps handle.compileScopeList(filter?) to enumerate compiled SemanticScope records through the L10 seam without importing src/runtime/scopes/**. Filter matches ai.listScopes({kind?, limit?}) for identity-set symmetry.",
+};
+
 export const getBundleMetadata: ApiV3FnMetadata = {
   name: "ui.scope.getBundle",
   status: "live-with-adapter",
@@ -67,5 +150,34 @@ export function createScopeFamily(ctx: UiApiContext) {
       const nowUtc = new Date().toISOString();
       return compile.call(ctx.handle, scopeId, nowUtc);
     },
+    list(filter?: UiScopeListFilter): readonly SemanticScope[] {
+      // KI-008 — enumeration through the handle's batch primitive
+      // (L10 purity blocks importing src/runtime/scopes/**). Returns
+      // a fresh array so callers that sort / splice don't leak into
+      // internal compiler state.
+      const enumerate = ctx.handle.compileScopeList;
+      if (typeof enumerate !== "function") return Object.freeze([]);
+      return enumerate.call(ctx.handle, filter);
+    },
+    card(scopeId: string): ScopeCardModel | null {
+      // KI-008 close — single-scope presentation projection. Returns
+      // a plain-value ScopeCardModel (posture, label, issue, suggestion
+      // groups, review actions, agent-pending flag). Host chrome wires
+      // event handlers around it.
+      const compile = ctx.handle.compileScopeCardById;
+      if (typeof compile !== "function") return null;
+      return compile.call(ctx.handle, scopeId);
+    },
+    rail(options?: UiScopeRailOptions): ScopeRailSnapshot {
+      // KI-008 close — rail snapshot. When `options.pageIndex` is
+      // supplied, narrows to that page; otherwise spans every page
+      // in the runtime's page graph. Envelope shape is stable either
+      // way; callers check `snapshot.pageIndex` to detect narrowing.
+      const compile = ctx.handle.compileScopeRailSnapshot;
+      if (typeof compile !== "function") {
+        return { segments: Object.freeze([]) };
+      }
+      return compile.call(ctx.handle, options);
+    },
   };
 }

package/src/compare/diff-engine.ts

@@ -410,8 +410,7 @@ function createParagraphRevisionRecords(
       changeId: revision.changeId,
       kind: revision.kind,
       anchor: {
-        kind: "range",
-        range: { from: position, to: position },
+        kind: "range", from: position, to: position,
         assoc: { start: -1, end: 1 },
       },
       authorId,