@beyondwork/docx-react-component 1.0.73 → 1.0.75

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.73",
+  "version": "1.0.75",
   "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"
@@ -5598,6 +5625,13 @@ export interface ShortcutDelegationContext {
   selectionRange: SelectionSnapshot;
 }
 
+/**
+ * Resolver contract (`resolveChromeVisibilityForPreset`): every field on
+ * this interface is REQUIRED — no `| undefined`, no optional sugar. Each
+ * preset's default-visibility block (`src/api/v3/ui/chrome-preset-model.ts`)
+ * MUST set every field. If you add a new surface visibility flag, add it
+ * here AND to all preset default blocks in the same commit.
+ */
 export interface WordReviewEditorChromeVisibility {
   toolbar: boolean;
   alerts: boolean;

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/runtime/workflow.ts

@@ -11,12 +11,16 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
+  EditorStoryTarget,
   OverlayKind,
   OverlayVisibilityPolicy,
   WorkflowMarkupModePolicy,
 } from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
-import { createScopeFromBlockId } from "../../../runtime/workflow/scope-writer.ts";
+import {
+  createScopeFromAnchor,
+  createScopeFromBlockId,
+} from "../../../runtime/workflow/scope-writer.ts";
 import { attachScopeMetadata } from "../../../runtime/workflow/metadata-writer.ts";
 import {
   DEFAULT_REGISTRY_ENTRIES,
@@ -113,6 +117,59 @@ export interface CreateScopeResult {
   readonly status: "created" | "block-not-found";
 }
 
+/**
+ * Input for `createScopeFromAnchor` — sub-block marker-backed scope.
+ *
+ * Use this variant when the scope must bracket a range *within* a block
+ * (a phrase inside a paragraph) or across blocks (a selection that
+ * spans paragraph boundaries). For whole-block scopes, prefer
+ * `createScope({blockId})` — it stays block-aligned after edits at the
+ * block boundary.
+ *
+ * The `from`/`to` positions are consumed **once** at creation. After
+ * this call returns, use the returned `scopeId` as the reference. Do
+ * not cache, store, or reuse the positions — they are positional
+ * queries (KI-P9), valid only in the document state they were captured
+ * in. The scope itself is marker-backed and travels with its bracketed
+ * content through any number of subsequent edits.
+ */
+export interface CreateScopeFromAnchorInput {
+  readonly anchor: {
+    /** Zero-based surface offset, inclusive. Must be `>= 0`. */
+    readonly from: number;
+    /** Zero-based surface offset, exclusive of the marker slot. Must be `>= from` and `<= storyLength`. */
+    readonly to: number;
+    /** Non-main-body story (footnote / header / endnote). Defaults to `{kind:"main"}`. */
+    readonly storyTarget?: EditorStoryTarget;
+  };
+  readonly mode?: "edit" | "suggest" | "comment" | "view";
+  readonly label?: string;
+  readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+  readonly stableRefHint?:
+    | "scope-id"
+    | "bookmark"
+    | "semantic-path"
+    | "runtime-handle";
+}
+
+export type CreateScopeFromAnchorResult =
+  | { readonly scopeId: string; readonly status: "created" }
+  | {
+      readonly scopeId: "";
+      readonly status: "range-invalid";
+      readonly reason:
+        | "from-negative"
+        | "to-less-than-from"
+        | "range-exceeds-story-length";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      /** Agent-actionable single-sentence explanation. Safe to surface to LLM tool replies as-is. */
+      readonly message: string;
+      /** Machine-routable next-step hint (`"clamp-from-to-zero"` / `"swap-from-and-to"` / `"clamp-to-to-storyLength-or-pick-a-different-range"`). */
+      readonly nextStep: string;
+    };
+
 export const createScopeMetadata: ApiV3FnMetadata = {
   name: "runtime.workflow.createScope",
   status: "live-with-adapter",
@@ -129,6 +186,32 @@ export const createScopeMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.workflow.createScope",
 };
 
+export const createScopeFromAnchorMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.createScopeFromAnchor",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-from-anchor-live.test.ts",
+    commit: "pending",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "scope-created",
+    expectedDelta:
+      "rail shows new scope chip for the sub-block range; editor surface refreshes with inline markers planted at from/to",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "scope-creation",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.workflow.createScopeFromAnchor. Companion to createScope({blockId}) for sub-block ranges. Consumes from/to once to plant inline scope_marker_start/end; the returned scopeId is the durable reference (KI-P9).",
+};
+
 export interface AttachMetadataInput {
   readonly scopeId: string;
   readonly metadataId: string;
@@ -411,6 +494,52 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
       return { scopeId: adapterResult.scopeId, status: "created" };
     },
 
+    createScopeFromAnchor(
+      input: CreateScopeFromAnchorInput,
+    ): CreateScopeFromAnchorResult {
+      // @endStateApi — live-with-adapter. Delegates to the layer-06
+      // scope-writer with the anchor range passed through directly.
+      // Bounds are validated against the story length; out-of-bounds
+      // ranges return a typed `range-invalid` discriminator rather than
+      // inventing a scopeId.
+      const adapterResult = createScopeFromAnchor(runtime, {
+        anchor: input.anchor,
+        mode: input.mode,
+        label: input.label,
+        ...(input.assoc ? { assoc: input.assoc } : {}),
+        ...(input.stableRefHint
+          ? { stableRefHint: input.stableRefHint }
+          : {}),
+      });
+      emitUxResponse(runtime, {
+        apiFn: createScopeFromAnchorMetadata.name,
+        intent: createScopeFromAnchorMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: createScopeFromAnchorMetadata.uxIntent.expectedDelta,
+        actualDelta:
+          adapterResult.status === "created"
+            ? {
+                kind: "inline-change",
+                payload: { scopeId: adapterResult.scopeId },
+              }
+            : undefined,
+      });
+      if (adapterResult.status !== "created") {
+        return {
+          scopeId: "",
+          status: "range-invalid",
+          reason: adapterResult.reason,
+          from: adapterResult.from,
+          to: adapterResult.to,
+          storyLength: adapterResult.storyLength,
+          message: adapterResult.message,
+          nextStep: adapterResult.nextStep,
+        };
+      }
+      return { scopeId: adapterResult.scopeId, status: "created" };
+    },
+
     getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null {
       // @endStateApi — live. Class-A policy read; composition with
       // class-C local preference lives in L10 (`ui.overlays.getVisibility`).

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" };
+}