@beyondwork/docx-react-component 1.0.104 → 1.0.106

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

@@ -16,6 +16,11 @@ import {
   type SemanticScopeKind,
 } from "../../../runtime/scopes/index.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  projectDocumentPe2Evidence,
+  type AiPe2EvidenceOptions,
+  type AiPe2DocumentEvidence,
+} from "./_pe2-evidence.ts";
 
 export interface InspectDocumentResult {
   readonly documentId: string;
@@ -23,6 +28,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 +46,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",
@@ -79,7 +85,10 @@ function buildKindDistribution(
   return out;
 }
 
-export function createInspectFamily(runtime: RuntimeApiHandle) {
+export function createInspectFamily(
+  runtime: RuntimeApiHandle,
+  pe2Evidence?: AiPe2EvidenceOptions,
+) {
   const compiler = createScopeCompilerService(runtime);
   return {
     inspectDocument(): InspectDocumentResult {
@@ -97,6 +106,7 @@ export function createInspectFamily(runtime: RuntimeApiHandle) {
         scopeCount: scopes.length,
         semanticSummary: summary,
         kindDistribution,
+        pe2Evidence: projectDocumentPe2Evidence(runtime, pe2Evidence),
       };
     },
 

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

@@ -33,6 +33,10 @@ import type {
 } from "../../../runtime/scopes/index.ts";
 import type { AIAction } from "../../../runtime/workflow/ai-action-policy.ts";
 import type { TextFormattingDirective } from "../../public-types.ts";
+import {
+  projectAuditReference,
+  type AiActionAuditReference,
+} from "./_audit-reference.ts";
 
 export interface ReplacementProposalInput {
   readonly targetScopeId: string;
@@ -123,7 +127,9 @@ export interface ApplyResult {
   readonly applied: boolean;
   readonly reason?: string;
   readonly blockers?: readonly string[];
+  readonly blockerDetails?: readonly ActionBlockerDetail[];
   readonly auditHint?: string;
+  readonly auditReference?: AiActionAuditReference;
   /**
    * Gap A (post-Slice-7 integration) — revision IDs authored during
    * the apply. Populated for suggest-mode (tracked insert + delete);
@@ -133,6 +139,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 +282,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 +481,9 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         expectedDelta: applyReplacementScopeMetadata.uxIntent.expectedDelta,
       });
 
+      const blockerDetails = projectBlockerDetails(
+        result.validation.blockedReasons,
+      );
       return {
         proposalId,
         applied: result.applied,
@@ -378,7 +491,11 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
+        ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
+        ...(result.audit
+          ? { auditReference: projectAuditReference(result.audit) }
+          : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };
     },
@@ -412,6 +529,9 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         expectedDelta: applyScopeActionMetadata.uxIntent.expectedDelta,
       });
 
+      const blockerDetails = projectBlockerDetails(
+        result.validation.blockedReasons,
+      );
       return {
         proposalId,
         applied: result.applied,
@@ -419,7 +539,11 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
+        ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
+        ...(result.audit
+          ? { auditReference: projectAuditReference(result.audit) }
+          : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };
     },

package/src/api/v3/index.ts

@@ -14,6 +14,13 @@
 
 export { createApiV3 } from "./_create.ts";
 export type { ApiV3, CreateApiV3Opts } from "./_create.ts";
+export type {
+  AiPe2EvidenceOptions,
+  AiPe2OracleEvidence,
+  AiPe2OracleEvidenceProvider,
+  AiPe2OracleEvidenceProviderInput,
+  AiPe2OracleVerdict,
+} from "./ai/_pe2-evidence.ts";
 
 export type {
   ApiStatus,

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

@@ -118,6 +118,21 @@ export interface UiController {
    * error rather than silently no-op.
    */
   readonly subscribeViewport?: (listener: UiListener<ViewportState>) => UiUnsubscribe;
+  /**
+   * PE2 page-residency policy read. L10 owns the observable residency
+   * shape; L11 owns realized DOM/PM attachment and L05 owns geometry
+   * caches. Omitting the hook makes `ui.viewport.getPageResidency`
+   * return an explicit unavailable snapshot.
+   */
+  readonly getPageResidency?: (pageIndex: number) => PageResidencySnapshot;
+  /**
+   * Page-residency subscription. Fires when the mounted surface changes
+   * whether a page is realized, cold, or evicted.
+   */
+  readonly subscribePageResidency?: (
+    pageIndex: number,
+    listener: UiListener<PageResidencySnapshot>,
+  ) => UiUnsubscribe;
   /**
    * Overlay invalidation subscription. Fires when geometry invalidation
    * ranges overlap attached overlay queries (U7). `ui.overlays.subscribe`
@@ -127,6 +142,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
@@ -219,6 +249,29 @@ export interface ViewportState {
   readonly devicePixelRatio: number;
 }
 
+export type PageResidency = "realized" | "cold" | "evicted";
+
+export type RehydrationStatus =
+  | "available"
+  | "requires-rehydration"
+  | "unavailable";
+
+export type PageResidencySource =
+  | "controller"
+  | "unavailable";
+
+export interface PageResidencySnapshot {
+  readonly __mock?: true;
+  /** 0-based page index, matching GeometryFacet.getPage(index). */
+  readonly pageIndex: number;
+  readonly pageId?: string;
+  readonly residency: PageResidency;
+  readonly status: RehydrationStatus;
+  readonly revision: number;
+  readonly source: PageResidencySource;
+  readonly reason?: string;
+}
+
 export type ScrollTargetBehavior = "auto" | "smooth" | "instant";
 
 export type ScrollTarget =
@@ -267,6 +320,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)                        */
 /* ================================================================== */
@@ -383,6 +490,21 @@ export interface ApiV3UiSurface {
 export interface ApiV3UiViewport {
   get(): ViewportState;
   subscribe(listener: UiListener<ViewportState>): UiUnsubscribe;
+  /**
+   * Read L10's page-residency policy for a 0-based page index. When no
+   * mounted controller has supplied a residency policy yet, returns an
+   * explicit `unavailable` mock snapshot instead of probing geometry or
+   * realizing DOM.
+   */
+  getPageResidency(pageIndex: number): PageResidencySnapshot;
+  /**
+   * Subscribe to residency changes for a 0-based page index. The listener
+   * receives plain snapshots; realization/teardown stays owned by L11.
+   */
+  subscribePageResidency(
+    pageIndex: number,
+    listener: UiListener<PageResidencySnapshot>,
+  ): UiUnsubscribe;
 
   /**
    * Scroll the mounted surface to a specific 1-based page number.
@@ -453,6 +575,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

@@ -24,6 +24,10 @@ export type {
   UiScopeListFilter,
   UiScopeRailOptions,
   ViewportState,
+  PageResidency,
+  PageResidencySnapshot,
+  PageResidencySource,
+  RehydrationStatus,
   ScrollTarget,
   ScrollTargetBehavior,
   ScrollToPageResult,
@@ -43,6 +47,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 {