@beyondwork/docx-react-component 1.0.104 → 1.0.105

package/package.json

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

package/src/api/public-types.ts

@@ -177,9 +177,11 @@ export type {
   PublicBlockMeasurement,
   PublicFieldDirtinessReport,
   PublicLineBox,
+  PublicLayoutDivergence,
   PublicMeasurementFidelity,
   PublicNoteAllocation,
   PublicPageAnchor,
+  PublicPageFrame,
   PublicPageNode,
   PublicPageRegion,
   PublicPageRegions,
@@ -190,6 +192,7 @@ export type {
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
   PublicSectionNode,
+  PublicTwipsRect,
   // R0.5: named page-format + margin-preset catalogs
   PageFormatDefinition,
   ActivePageFormat,

package/src/api/v3/ai/_pe2-evidence.ts

@@ -0,0 +1,153 @@
+/**
+ * Layer 09 PE2 evidence projection.
+ *
+ * The AI API should not leak the full runtime geometry index. Agents need a
+ * small, JSON-stable read model that says whether PE2 geometry evidence is
+ * available and, for scope reads, whether a replacement envelope exists for
+ * the requested scope.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type {
+  GeometryIndexCoverage,
+  GeometryPrecision,
+  GeometryRehydrationStatus,
+  GeometryReplacementEnvelopeEntry,
+  GeometrySourceIdentity,
+} from "../../../runtime/geometry/index.ts";
+
+export interface AiPe2GeometryCoverageEvidence {
+  readonly status: GeometryRehydrationStatus;
+  readonly pageCount: number;
+  readonly regionCount: number;
+  readonly sliceCount: number;
+  readonly lineCount: number;
+  readonly anchorCount: number;
+  readonly hitTargetCount: number;
+  readonly semanticEntryCount: number;
+  readonly replacementEnvelopeCount: number;
+  readonly objectHandleCount: number;
+  readonly precision: {
+    readonly exact: number;
+    readonly "within-tolerance": number;
+    readonly heuristic: number;
+  };
+}
+
+export interface AiPe2DocumentEvidence {
+  readonly geometry: AiPe2GeometryCoverageEvidence;
+}
+
+export interface AiPe2ScopeReplacementEnvelopeEvidence {
+  readonly status: GeometryRehydrationStatus;
+  readonly precision: GeometryPrecision;
+  readonly rectCount: number;
+  readonly pageIds?: readonly string[];
+  readonly sourceIdentity?: GeometrySourceIdentity;
+}
+
+export interface AiPe2ScopeEvidence {
+  readonly geometry: {
+    readonly coverage: AiPe2GeometryCoverageEvidence;
+    readonly replacementEnvelope?: AiPe2ScopeReplacementEnvelopeEvidence;
+    readonly reason?: "geometry-index-unavailable" | "scope-envelope-not-found";
+  };
+}
+
+function copyCoverage(coverage: GeometryIndexCoverage): AiPe2GeometryCoverageEvidence {
+  return {
+    status: coverage.status,
+    pageCount: coverage.pageCount,
+    regionCount: coverage.regionCount,
+    sliceCount: coverage.sliceCount,
+    lineCount: coverage.lineCount,
+    anchorCount: coverage.anchorCount,
+    hitTargetCount: coverage.hitTargetCount,
+    semanticEntryCount: coverage.semanticEntryCount,
+    replacementEnvelopeCount: coverage.replacementEnvelopeCount,
+    objectHandleCount: coverage.objectHandleCount,
+    precision: {
+      exact: coverage.precision.exact,
+      "within-tolerance": coverage.precision["within-tolerance"],
+      heuristic: coverage.precision.heuristic,
+    },
+  };
+}
+
+function copyEnvelope(
+  envelope: GeometryReplacementEnvelopeEntry,
+): AiPe2ScopeReplacementEnvelopeEvidence {
+  return {
+    status: envelope.status,
+    precision: envelope.precision,
+    rectCount: envelope.rects.length,
+    ...(envelope.pageIds ? { pageIds: [...envelope.pageIds] } : {}),
+    ...(envelope.sourceIdentity ? { sourceIdentity: { ...envelope.sourceIdentity } } : {}),
+  };
+}
+
+const UNAVAILABLE_COVERAGE: AiPe2GeometryCoverageEvidence = {
+  status: "unavailable",
+  pageCount: 0,
+  regionCount: 0,
+  sliceCount: 0,
+  lineCount: 0,
+  anchorCount: 0,
+  hitTargetCount: 0,
+  semanticEntryCount: 0,
+  replacementEnvelopeCount: 0,
+  objectHandleCount: 0,
+  precision: { exact: 0, "within-tolerance": 0, heuristic: 0 },
+};
+
+export function projectDocumentPe2Evidence(
+  runtime: RuntimeApiHandle,
+): AiPe2DocumentEvidence {
+  if (!runtime.geometry) {
+    return { geometry: UNAVAILABLE_COVERAGE };
+  }
+  return {
+    geometry: copyCoverage(runtime.geometry.getGeometryCoverage()),
+  };
+}
+
+export function projectScopePe2Evidence(
+  runtime: RuntimeApiHandle,
+  scopeId: string,
+): AiPe2ScopeEvidence {
+  if (!runtime.geometry) {
+    return {
+      geometry: {
+        coverage: UNAVAILABLE_COVERAGE,
+        reason: "geometry-index-unavailable",
+      },
+    };
+  }
+  const coverage = copyCoverage(runtime.geometry.getGeometryCoverage());
+  const index = runtime.geometry.getGeometryIndex();
+  if (!index) {
+    return {
+      geometry: {
+        coverage,
+        reason: "geometry-index-unavailable",
+      },
+    };
+  }
+
+  const envelope = index.replacementEnvelopes.find((entry) => entry.scopeId === scopeId);
+  if (!envelope) {
+    return {
+      geometry: {
+        coverage,
+        reason: "scope-envelope-not-found",
+      },
+    };
+  }
+
+  return {
+    geometry: {
+      coverage,
+      replacementEnvelope: copyEnvelope(envelope),
+    },
+  };
+}

package/src/api/v3/ai/bundle.ts

@@ -24,6 +24,10 @@ import {
   type SemanticScope,
 } from "../../../runtime/scopes/index.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  projectScopePe2Evidence,
+  type AiPe2ScopeEvidence,
+} from "./_pe2-evidence.ts";
 
 /**
  * Handle-shaped input (architecture A3 — scope-handle-first targeting).
@@ -42,8 +46,9 @@ export interface GetScopeBundleInput {
   readonly nowUtc: string;
 }
 
-/** Re-export the runtime-side `ScopeBundle` so v3 consumers get the rich shape. */
-export type { RuntimeScopeBundle as ScopeBundle };
+export type ScopeBundle = RuntimeScopeBundle & {
+  readonly pe2Evidence: AiPe2ScopeEvidence;
+};
 
 export interface ScopeBundleNotFound {
   readonly notFound: true;
@@ -91,7 +96,7 @@ export const getScopeBundleMetadata: ApiV3FnMetadata = {
     boundedScope: "scope",
     auditCategory: "scope-bundle",
     contextPromptShape:
-      "Bundle content + formatting + layout + geometry + workflow + replaceability for prompt context.",
+      "Bundle content + formatting + layout + geometry + workflow + replaceability + PE2 geometry coverage/envelope evidence for prompt context.",
   },
   stateClass: "A-canonical",
   persistsTo: "canonical",
@@ -110,7 +115,7 @@ export function createBundleFamily(runtime: RuntimeApiHandle) {
       return compiled?.scope ?? null;
     },
 
-    getScopeBundle(input: GetScopeBundleInput): RuntimeScopeBundle | ScopeBundleNotFound {
+    getScopeBundle(input: GetScopeBundleInput): ScopeBundle | ScopeBundleNotFound {
       // @endStateApi — live-with-adapter. Routes through the compiler-
       // service facade.
       //
@@ -126,7 +131,10 @@ export function createBundleFamily(runtime: RuntimeApiHandle) {
           reason: "no scope with this id in canonical document or review store",
         };
       }
-      return bundle;
+      return {
+        ...bundle,
+        pe2Evidence: projectScopePe2Evidence(runtime, scopeId),
+      };
     },
   };
 }

package/src/api/v3/ai/inspect.ts

@@ -16,6 +16,10 @@ import {
   type SemanticScopeKind,
 } from "../../../runtime/scopes/index.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  projectDocumentPe2Evidence,
+  type AiPe2DocumentEvidence,
+} from "./_pe2-evidence.ts";
 
 export interface InspectDocumentResult {
   readonly documentId: string;
@@ -23,6 +27,7 @@ export interface InspectDocumentResult {
   readonly pageCount?: number;
   readonly semanticSummary: string;
   readonly kindDistribution: Readonly<Partial<Record<SemanticScopeKind, number>>>;
+  readonly pe2Evidence: AiPe2DocumentEvidence;
 }
 
 export const inspectDocumentMetadata: ApiV3FnMetadata = {
@@ -40,7 +45,7 @@ export const inspectDocumentMetadata: ApiV3FnMetadata = {
     boundedScope: "document",
     auditCategory: "document-inspect",
     contextPromptShape:
-      "Summarize document by scope count + page count + semantic kind distribution.",
+      "Summarize document by scope count + page count + semantic kind distribution + PE2 geometry coverage evidence.",
   },
   stateClass: "A-canonical",
   persistsTo: "canonical",
@@ -97,6 +102,7 @@ export function createInspectFamily(runtime: RuntimeApiHandle) {
         scopeCount: scopes.length,
         semanticSummary: summary,
         kindDistribution,
+        pe2Evidence: projectDocumentPe2Evidence(runtime),
       };
     },
 

package/src/api/v3/ai/replacement.ts

@@ -123,6 +123,7 @@ export interface ApplyResult {
   readonly applied: boolean;
   readonly reason?: string;
   readonly blockers?: readonly string[];
+  readonly blockerDetails?: readonly ActionBlockerDetail[];
   readonly auditHint?: string;
   /**
    * Gap A (post-Slice-7 integration) — revision IDs authored during
@@ -133,6 +134,19 @@ export interface ApplyResult {
   readonly authoredRevisionIds: readonly string[];
 }
 
+export interface ActionBlockerDetail {
+  readonly code: string;
+  readonly category:
+    | "unsupported-scope-kind"
+    | "unsupported-operation"
+    | "unresolved-scope"
+    | "policy-or-guard";
+  readonly message: string;
+  readonly nextStep: string;
+  readonly scopeKind?: string;
+  readonly operation?: string;
+}
+
 export interface ApplyReplacementScopeInput {
   readonly targetScopeId: string;
   readonly operation?: ReplacementOperationKind;
@@ -263,6 +277,97 @@ function projectValidationResult(
   };
 }
 
+function blockerDetailFor(code: string): ActionBlockerDetail | null {
+  if (code.startsWith("scope-not-resolvable:")) {
+    return {
+      code,
+      category: "unresolved-scope",
+      message: "The target scope no longer resolves in the current document.",
+      nextStep:
+        "Call ai.resolveReference or ai.queryScopeAtPosition again, then retry with the returned handle's scopeId.",
+    };
+  }
+
+  if (!code.startsWith("compile-refused:")) return null;
+
+  const [, scopeKind = "unknown", ...rest] = code.split(":");
+  const suffix = rest.join(":");
+  if (suffix.startsWith("operation-not-implemented:")) {
+    const operation = suffix.slice("operation-not-implemented:".length);
+    return {
+      code,
+      category: "unsupported-operation",
+      scopeKind,
+      operation,
+      message: `The ${operation} operation is not implemented for ${scopeKind} scopes.`,
+      nextStep:
+        "Retry with operation:\"replace\" when that is acceptable, or attach an explanation/issue instead of mutating.",
+    };
+  }
+
+  if (scopeKind === "scope" && suffix === "multi-paragraph-replace-not-implemented") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: "Multi-paragraph scope replacement is not implemented.",
+      nextStep:
+        "Split the request into paragraph-scoped replacements, or attach an explanation/issue until the multi-paragraph planner ships.",
+    };
+  }
+
+  if (scopeKind === "table" || scopeKind === "table-row" || scopeKind === "table-cell") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: `Flat text replacement is not implemented for ${scopeKind} scopes because it can break table structure.`,
+      nextStep:
+        "Use ai.attachExplanation or ai.createIssue for now, or wait for the Layer 08 table-family replacement planner.",
+    };
+  }
+
+  if (scopeKind === "field") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: "Field result replacement is preserve-only because field text is computed from instructions.",
+      nextStep:
+        "Attach an explanation/issue, or use a future field-aware edit path that updates field instructions safely.",
+    };
+  }
+
+  if (scopeKind === "image" || scopeKind === "note") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: `Replacement is not implemented for ${scopeKind} scopes.`,
+      nextStep:
+        "Attach an explanation/issue rather than mutating until a scope-specific planner exists.",
+    };
+  }
+
+  return {
+    code,
+    category: "unsupported-scope-kind",
+    scopeKind,
+    message: `Replacement is not implemented for ${scopeKind} scopes.`,
+    nextStep:
+      "Use a supported paragraph-like scope, or attach an explanation/issue and route the unsupported planner to the owning layer.",
+  };
+}
+
+function projectBlockerDetails(
+  blockers: readonly string[],
+): readonly ActionBlockerDetail[] | undefined {
+  const details = blockers
+    .map((code) => blockerDetailFor(code))
+    .filter((detail): detail is ActionBlockerDetail => detail !== null);
+  return details.length > 0 ? Object.freeze(details) : undefined;
+}
+
 export function createReplacementFamily(runtime: RuntimeApiHandle) {
   const compiler = createScopeCompilerService(runtime);
   return {
@@ -371,6 +476,9 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         expectedDelta: applyReplacementScopeMetadata.uxIntent.expectedDelta,
       });
 
+      const blockerDetails = projectBlockerDetails(
+        result.validation.blockedReasons,
+      );
       return {
         proposalId,
         applied: result.applied,
@@ -378,6 +486,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
+        ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };
@@ -412,6 +521,9 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         expectedDelta: applyScopeActionMetadata.uxIntent.expectedDelta,
       });
 
+      const blockerDetails = projectBlockerDetails(
+        result.validation.blockedReasons,
+      );
       return {
         proposalId,
         applied: result.applied,
@@ -419,6 +531,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
+        ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };

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

@@ -127,6 +127,21 @@ export interface UiController {
   readonly subscribeOverlays?: (
     listener: UiListener<OverlayAnchorQuery>,
   ) => UiUnsubscribe;
+  /**
+   * PE2 overlay-lane snapshot resolver. This is the mounted-surface lane
+   * contract for selection/caret/redline/scope/comment/table/object/search
+   * and presence overlays. The bind-side supplies already-projected lane
+   * entries; L10 owns the observable shape, not layout or geometry caches.
+   */
+  readonly getOverlayLane?: (kind: UiOverlayLaneKind) => UiOverlayLaneSnapshot;
+  /**
+   * PE2 overlay-lane subscription. Must fan out lane changes without
+   * dispatching PM document transactions or invalidating L04 layout.
+   */
+  readonly subscribeOverlayLane?: (
+    kind: UiOverlayLaneKind,
+    listener: UiListener<UiOverlayLaneSnapshot>,
+  ) => UiUnsubscribe;
   /**
    * Overlay anchor resolver. Expected to be a direct projection of the
    * geometry facet (U4 — overlays derive from geometry, not DOM). Returns
@@ -267,6 +282,60 @@ export type OverlayAnchorQuery =
   | { kind: "page"; value: number }
   | { kind: "selection" };
 
+/* ================================================================== */
+/*  PE2 overlay lanes                                                  */
+/* ================================================================== */
+
+export type UiOverlayLaneKind =
+  | "selection"
+  | "caret"
+  | "redlines"
+  | "field-scopes"
+  | "broad-scopes"
+  | "comments"
+  | "issues"
+  | "tables"
+  | "objects"
+  | "search"
+  | "presence";
+
+export type UiOverlayLaneStatus =
+  | "resolved"
+  | "requires-rehydration"
+  | "unavailable";
+
+export type UiOverlayLaneSource =
+  | "geometry"
+  | "workflow"
+  | "search"
+  | "awareness"
+  | "controller"
+  | "unavailable";
+
+export interface UiOverlayLaneEntry {
+  readonly id: string;
+  readonly status: UiOverlayLaneStatus;
+  readonly anchor?: OverlayAnchorQuery;
+  readonly rects?: readonly GeometryRect[];
+  readonly reason?: string;
+  /**
+   * Lane-specific plain payload. Examples: peer identity for presence,
+   * issue severity, search rank, table/object classification. Kept plain
+   * so non-React consumers and debug runners can serialize snapshots.
+   */
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+export interface UiOverlayLaneSnapshot {
+  readonly __mock?: true;
+  readonly kind: UiOverlayLaneKind;
+  readonly status: UiOverlayLaneStatus;
+  readonly entries: readonly UiOverlayLaneEntry[];
+  readonly revision: number;
+  readonly source: UiOverlayLaneSource;
+  readonly reason?: string;
+}
+
 /* ================================================================== */
 /*  Overlay visibility — U9 (state-classes X3)                        */
 /* ================================================================== */
@@ -453,6 +522,23 @@ export interface ApiV3UiOverlays {
     query: OverlayAnchorQuery,
     listener: UiListener<GeometryRect | null>,
   ): UiUnsubscribe;
+  /**
+   * PE2 overlay-lane read. Returns a plain snapshot for a mounted lane
+   * such as selection, caret, redlines, comments, tables, objects,
+   * search, or presence. When the host has not wired a lane yet, returns
+   * an explicit `unavailable` snapshot instead of measuring DOM or
+   * forcing geometry rehydration.
+   */
+  getLane(kind: UiOverlayLaneKind): UiOverlayLaneSnapshot;
+  /**
+   * PE2 overlay-lane subscription. The listener receives lane snapshots,
+   * never PM transactions. Presence/awareness updates must travel through
+   * this channel without invalidating L04 layout.
+   */
+  subscribeLane(
+    kind: UiOverlayLaneKind,
+    listener: UiListener<UiOverlayLaneSnapshot>,
+  ): UiUnsubscribe;
 
   /**
    * U9 · Composed overlay visibility. Merges the class-A policy from

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

@@ -43,6 +43,11 @@ export type {
   DebugSession,
   DebugAttachment,
   GeometryRect,
+  UiOverlayLaneEntry,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
+  UiOverlayLaneSource,
+  UiOverlayLaneStatus,
 } from "./_types.ts";
 
 // Chrome composition types (U5.b) — relocated to layer 10 in Slice 8.

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

@@ -42,6 +42,8 @@ import type {
   GeometryRect,
   OverlayAnchorQuery,
   OverlayVisibility,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
   UiListener,
   UiUnsubscribe,
 } from "./_types.ts";
@@ -195,6 +197,57 @@ export const subscribeQueryMetadata: ApiV3FnMetadata = {
   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)`.",
 };
 
+// ----- PE2 overlay-lane contract -------------------------------------------
+
+export const getLaneMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.getLane",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-lanes.test.ts",
+    commit: "refactor-10-pe2-overlay-lanes",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Unavailable UiOverlayLaneSnapshot with entries:[] and revision:0 when the mounted controller has not wired the requested PE2 overlay lane yet.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-overlays-lane-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § PE2 overlay lanes. Reads the mounted controller's lane snapshot for selection/caret/redlines/field-scopes/broad-scopes/comments/issues/tables/objects/search/presence. Returns explicit status:'unavailable' when the lane is not wired; never measures DOM or wakes layout.",
+};
+
+export const subscribeLaneMetadata: ApiV3FnMetadata = {
+  name: "ui.overlays.subscribeLane",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/overlays-lanes.test.ts",
+    commit: "refactor-10-pe2-overlay-lanes",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "overlay-lane subscriber attached; future lane snapshots propagate through the listener without PM document transactions",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-overlays-lane-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.overlays.lane_changed",
+    payloadType: "UiOverlayLaneSnapshot",
+    coalescing: "raf",
+  },
+  rwdReference:
+    "§UI API § PE2 overlay lanes. Adapter delegates to UiController.subscribeOverlayLane(kind, listener). Presence/awareness, selection, search, and review lane updates are observable UI state only; this method does not dispatch PM document transactions or invalidate L04 layout.",
+};
+
 // ----- U9 overlay-visibility metadata (state-classes X3) -----
 
 export const getVisibilityMetadata: ApiV3FnMetadata = {
@@ -354,6 +407,21 @@ export function createOverlaysFamily(ctx: UiApiContext) {
   const queryChannels = new Map<string, QueryChannel>();
   let queryCoarseUnsubscribe: (() => void) | null = null;
 
+  function unavailableLane(
+    kind: UiOverlayLaneKind,
+    reason = "overlay lane is not wired on the active controller",
+  ): UiOverlayLaneSnapshot {
+    return {
+      __mock: true,
+      kind,
+      status: "unavailable",
+      entries: Object.freeze([]),
+      revision: 0,
+      source: "unavailable",
+      reason,
+    };
+  }
+
   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}`;
@@ -560,6 +628,42 @@ export function createOverlaysFamily(ctx: UiApiContext) {
       };
     },
 
+    // ----- PE2 overlay lanes -----
+
+    getLane(kind: UiOverlayLaneKind): UiOverlayLaneSnapshot {
+      const hook = ctx.binding?.controller.getOverlayLane;
+      return hook
+        ? hook(kind)
+        : unavailableLane(kind);
+    },
+
+    subscribeLane(
+      kind: UiOverlayLaneKind,
+      listener: UiListener<UiOverlayLaneSnapshot>,
+    ): UiUnsubscribe {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.overlays.subscribeLane: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribeOverlayLane) {
+        throw new Error(
+          `ui.overlays.subscribeLane: controller of kind "${controller.kind}" did not provide a subscribeOverlayLane hook`,
+        );
+      }
+      const unsubscribe = controller.subscribeOverlayLane(kind, listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribeLaneMetadata.name,
+        intent: subscribeLaneMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: subscribeLaneMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.overlays.lane", lane: kind } },
+      });
+      return unsubscribe;
+    },
+
     // ----- U9 overlay-visibility (state-classes X3) -----
 
     getVisibility(kind: OverlayKind): OverlayVisibility {

package/src/model/layout/index.ts

@@ -65,6 +65,9 @@ export type {
   RuntimeLayoutDivergenceKind,
   RuntimeLayoutDivergence,
   RuntimePageFrame,
+  RuntimePageLocalStoryInstance,
+  RuntimeResolvedStoryField,
+  RuntimeStoryAnchoredObject,
   RuntimeBlockFragment,
   RuntimeLineBox,
   RuntimeNoteAllocation,