@beyondwork/docx-react-component 1.0.71 → 1.0.72

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

@@ -0,0 +1,342 @@
+/**
+ * @endStateApi v3 — `ai` review-workflow family.
+ *
+ * acceptRevision / rejectRevision / resolveCommentThread.
+ *
+ * Thin adapters over Layer-06 review-workflow primitives exposed on
+ * `RuntimeApiHandle`:
+ *
+ *   - `runtime.acceptChange(revisionId)` — dispatches `change.accept`
+ *     through the /06 coordinator.
+ *   - `runtime.rejectChange(revisionId)` — dispatches `change.reject`.
+ *   - `runtime.resolveComment(commentId)` — dispatches `comment.resolve`.
+ *
+ * Refusal contract: when the id doesn't resolve (revision already
+ * accepted/rejected/detached, or unknown), the adapter returns
+ * `{accepted|rejected|resolved: false, reason: "<kind>-not-found:<id>" |
+ * "<kind>-not-actionable:<id>"}`. Success path is verified post-dispatch
+ * by re-reading `runtime.getRenderSnapshot().trackedChanges` /
+ * `.comments` and confirming the target entry transitioned.
+ *
+ * Architecture A4: these mutations emit exactly one `ScopeActionAudit`
+ * on the `scope` telemetry channel when the target carries a resolvable
+ * scope anchor. When no scope is resolvable (e.g. the revision anchors
+ * to a region that isn't an enumerable scope), the audit is skipped
+ * silently — mirrors `attach.ts`'s pre-scope-null arm. The mutation
+ * still commits; the contract is "at most one audit per mutation", and
+ * review-workflow mutations on non-scoped regions remain traceable via
+ * the primitive's own `change.*` dispatch records on the `command`
+ * telemetry channel.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+import {
+  captureScopeSnapshot,
+  emitScopeMetadataAudit,
+  snapshotDocumentHash,
+} from "./_metadata-audit.ts";
+
+export interface AcceptRevisionInput {
+  readonly revisionId: string;
+  /**
+   * Optional audit-target hint. When provided and resolvable, the A4
+   * `ScopeActionAudit` is emitted against this scope. Omitting it still
+   * accepts the revision; the audit is skipped silently.
+   */
+  readonly scopeId?: string;
+}
+
+export interface AcceptRevisionResult {
+  readonly revisionId: string;
+  readonly accepted: boolean;
+  readonly reason?: string;
+}
+
+export interface RejectRevisionInput {
+  readonly revisionId: string;
+  readonly scopeId?: string;
+}
+
+export interface RejectRevisionResult {
+  readonly revisionId: string;
+  readonly rejected: boolean;
+  readonly reason?: string;
+}
+
+export interface ResolveCommentThreadInput {
+  readonly threadId: string;
+  readonly scopeId?: string;
+}
+
+export interface ResolveCommentThreadResult {
+  readonly threadId: string;
+  readonly resolved: boolean;
+  readonly reason?: string;
+}
+
+export const acceptRevisionMetadata: ApiV3FnMetadata = {
+  name: "ai.acceptRevision",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-review-workflow.test.ts",
+    commit: "refactor-09-post-closure-review-workflow",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "tracked-change accepted; revision removed from pending list",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "document",
+    auditCategory: "revision-accept",
+    contextPromptShape:
+      "Accept a single tracked-change revision by revisionId. Optional scopeId hint binds the audit to a scope target.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.acceptRevision. Adapter over runtime.acceptChange (Layer-06 review-workflow). A4 audit emitted when scopeId hint resolves; otherwise the primitive's /06 dispatch record on the command channel carries the trace.",
+};
+
+export const rejectRevisionMetadata: ApiV3FnMetadata = {
+  name: "ai.rejectRevision",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-review-workflow.test.ts",
+    commit: "refactor-09-post-closure-review-workflow",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "tracked-change rejected; revision removed from pending list",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "document",
+    auditCategory: "revision-reject",
+    contextPromptShape:
+      "Reject a single tracked-change revision by revisionId. Optional scopeId hint binds the audit to a scope target.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.rejectRevision. Adapter over runtime.rejectChange (Layer-06 review-workflow). A4 audit emitted when scopeId hint resolves.",
+};
+
+export const resolveCommentThreadMetadata: ApiV3FnMetadata = {
+  name: "ai.resolveCommentThread",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-review-workflow.test.ts",
+    commit: "refactor-09-post-closure-review-workflow",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "comment thread marked resolved; thread moves out of open list",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "document",
+    auditCategory: "comment-resolve",
+    contextPromptShape:
+      "Resolve an open comment thread by threadId. Optional scopeId hint binds the audit to the anchored scope.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.resolveCommentThread. Adapter over runtime.resolveComment (Layer-06 review-workflow). A4 audit emitted when scopeId hint resolves.",
+};
+
+export function createReviewFamily(runtime: RuntimeApiHandle) {
+  return {
+    acceptRevision(input: AcceptRevisionInput): AcceptRevisionResult {
+      // @endStateApi — live-with-adapter. Routes through Layer-06's
+      // runtime.acceptChange() dispatch; A4 audit emitted on success when
+      // caller supplied a resolvable scopeId hint.
+      const { revisionId } = input;
+      const before = runtime.getRenderSnapshot().trackedChanges;
+      const target = before.revisions.find((r) => r.revisionId === revisionId);
+      if (!target) {
+        return {
+          revisionId,
+          accepted: false,
+          reason: `revision-not-found:${revisionId}`,
+        };
+      }
+      if (!target.canAccept || target.status !== "active") {
+        return {
+          revisionId,
+          accepted: false,
+          reason: `revision-not-actionable:${revisionId}`,
+        };
+      }
+      const preScope = input.scopeId
+        ? captureScopeSnapshot(runtime, input.scopeId)
+        : null;
+      const documentHashBefore = snapshotDocumentHash(runtime);
+      runtime.acceptChange(revisionId);
+      const after = runtime.getRenderSnapshot().trackedChanges;
+      const accepted = !after.pendingChangeIds.includes(revisionId);
+      if (accepted && preScope && input.scopeId) {
+        emitScopeMetadataAudit({
+          runtime,
+          actionId: acceptRevisionMetadata.name,
+          scopeId: input.scopeId,
+          targetScopeSnapshot: preScope,
+          proposedContent: {
+            kind: "explanation",
+            payload: { revisionId, intent: "accept" },
+          },
+          compiledOperationKind: "metadata-attach-explanation",
+          compiledOperationSummary: `accept revision ${revisionId}`,
+          emittedAtUtc: new Date(0).toISOString(),
+          documentHashBefore,
+        });
+      }
+      emitUxResponse(runtime, {
+        apiFn: acceptRevisionMetadata.name,
+        intent: acceptRevisionMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: acceptRevisionMetadata.uxIntent.expectedDelta,
+      });
+      return accepted
+        ? { revisionId, accepted: true }
+        : {
+            revisionId,
+            accepted: false,
+            reason: `revision-not-actionable:${revisionId}`,
+          };
+    },
+
+    rejectRevision(input: RejectRevisionInput): RejectRevisionResult {
+      // @endStateApi — live-with-adapter. Routes through Layer-06's
+      // runtime.rejectChange() dispatch.
+      const { revisionId } = input;
+      const before = runtime.getRenderSnapshot().trackedChanges;
+      const target = before.revisions.find((r) => r.revisionId === revisionId);
+      if (!target) {
+        return {
+          revisionId,
+          rejected: false,
+          reason: `revision-not-found:${revisionId}`,
+        };
+      }
+      if (!target.canReject || target.status !== "active") {
+        return {
+          revisionId,
+          rejected: false,
+          reason: `revision-not-actionable:${revisionId}`,
+        };
+      }
+      const preScope = input.scopeId
+        ? captureScopeSnapshot(runtime, input.scopeId)
+        : null;
+      const documentHashBefore = snapshotDocumentHash(runtime);
+      runtime.rejectChange(revisionId);
+      const after = runtime.getRenderSnapshot().trackedChanges;
+      const rejected = !after.pendingChangeIds.includes(revisionId);
+      if (rejected && preScope && input.scopeId) {
+        emitScopeMetadataAudit({
+          runtime,
+          actionId: rejectRevisionMetadata.name,
+          scopeId: input.scopeId,
+          targetScopeSnapshot: preScope,
+          proposedContent: {
+            kind: "explanation",
+            payload: { revisionId, intent: "reject" },
+          },
+          compiledOperationKind: "metadata-attach-explanation",
+          compiledOperationSummary: `reject revision ${revisionId}`,
+          emittedAtUtc: new Date(0).toISOString(),
+          documentHashBefore,
+        });
+      }
+      emitUxResponse(runtime, {
+        apiFn: rejectRevisionMetadata.name,
+        intent: rejectRevisionMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: rejectRevisionMetadata.uxIntent.expectedDelta,
+      });
+      return rejected
+        ? { revisionId, rejected: true }
+        : {
+            revisionId,
+            rejected: false,
+            reason: `revision-not-actionable:${revisionId}`,
+          };
+    },
+
+    resolveCommentThread(
+      input: ResolveCommentThreadInput,
+    ): ResolveCommentThreadResult {
+      // @endStateApi — live-with-adapter. Routes through Layer-06's
+      // runtime.resolveComment() dispatch.
+      const { threadId } = input;
+      const before = runtime.getRenderSnapshot().comments;
+      const target = before.threads.find((t) => t.commentId === threadId);
+      if (!target) {
+        return {
+          threadId,
+          resolved: false,
+          reason: `thread-not-found:${threadId}`,
+        };
+      }
+      if (target.status !== "open") {
+        return {
+          threadId,
+          resolved: false,
+          reason: `thread-not-open:${threadId}`,
+        };
+      }
+      const preScope = input.scopeId
+        ? captureScopeSnapshot(runtime, input.scopeId)
+        : null;
+      const documentHashBefore = snapshotDocumentHash(runtime);
+      runtime.resolveComment(threadId);
+      const after = runtime.getRenderSnapshot().comments;
+      const resolved = after.resolvedCommentIds.includes(threadId);
+      if (resolved && preScope && input.scopeId) {
+        emitScopeMetadataAudit({
+          runtime,
+          actionId: resolveCommentThreadMetadata.name,
+          scopeId: input.scopeId,
+          targetScopeSnapshot: preScope,
+          proposedContent: {
+            kind: "explanation",
+            payload: { threadId, intent: "resolve-comment" },
+          },
+          compiledOperationKind: "metadata-attach-explanation",
+          compiledOperationSummary: `resolve comment thread ${threadId}`,
+          emittedAtUtc: new Date(0).toISOString(),
+          documentHashBefore,
+        });
+      }
+      emitUxResponse(runtime, {
+        apiFn: resolveCommentThreadMetadata.name,
+        intent: resolveCommentThreadMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: resolveCommentThreadMetadata.uxIntent.expectedDelta,
+      });
+      return resolved
+        ? { threadId, resolved: true }
+        : {
+            threadId,
+            resolved: false,
+            reason: `thread-not-resolvable:${threadId}`,
+          };
+    },
+  };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @endStateApi v3 — `ai.getDocumentStatistics`.
+ *
+ * Passes `DocumentStats` derived inside the runtime through to agents.
+ * Counts: paragraphs, words, characters, comments, revisions.
+ *
+ * Read-family; no audit emission. Complements `ai.inspectDocument`
+ * (which reports scope-level counts) with flat document-level counts
+ * an agent can surface directly.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { deriveDocumentStats } from "../../../core/state/editor-state.ts";
+
+export interface DocumentStatisticsResult {
+  readonly paragraphCount: number;
+  readonly wordCount: number;
+  readonly characterCount: number;
+  readonly commentCount: number;
+  readonly revisionCount: number;
+}
+
+export const getDocumentStatisticsMetadata: ApiV3FnMetadata = {
+  name: "ai.getDocumentStatistics",
+  status: "live-with-adapter",
+  sourceLayer: "canonical",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-document-read.test.ts",
+    commit: "refactor-09-post-closure-document-read",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "document-stats-read",
+    contextPromptShape:
+      "Flat document counts: paragraphs, words, characters, comments, revisions.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§AI API § ai.getDocumentStatistics. Read-through of the DocumentStats record derived from the canonical document. Complements ai.inspectDocument's scope-level counts.",
+};
+
+export function createStatsFamily(runtime: RuntimeApiHandle) {
+  return {
+    getDocumentStatistics(): DocumentStatisticsResult {
+      // @endStateApi — live-with-adapter. Passes deriveDocumentStats
+      // through the canonical document for agent-facing counts.
+      const document = runtime.getCanonicalDocument();
+      const stats = deriveDocumentStats({ document });
+      return {
+        paragraphCount: stats.paragraphCount,
+        wordCount: stats.wordCount,
+        characterCount: stats.characterCount,
+        commentCount: stats.commentCount,
+        revisionCount: stats.revisionCount,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,181 @@
+/**
+ * @endStateApi v3 — `runtime.viewport` family.
+ *
+ * Closes coord-07 §2.9 / coord-10 §γ — page-anchor + page-geometry
+ * primitives the visual-fidelity harness (and any future "go to page N"
+ * host) consumes through `ui.viewport.scrollToPage(n)`.
+ *
+ * Background (coord-07 §2.9 / coord-10 §γ filed 2026-04-23). The
+ * visual-fidelity harness approximated page navigation via PM
+ * `[data-page-frame='N']` boundary widgets + `scrollIntoView`. Three
+ * problems surfaced:
+ *   1. Widget naming drifted once already (`data-page-index` → `data-page-frame`).
+ *   2. Boundary widgets are zero-height strips between pages, not on
+ *      page content — scrolling one to viewport-top parks the camera
+ *      between pages.
+ *   3. Page 1 + final page have no boundary widget (only N-1 widgets for
+ *      N pages).
+ *
+ * A runtime-owned primitive backed by the layout page graph eliminates
+ * both the chrome-drift risk and the gap-vs-content problem. Pure
+ * reads; `stateClass: "A-canonical"` + `persistsTo: "canonical"` — the
+ * layout facet is derived canonical state.
+ *
+ * `elementId` stays `null` until L11's per-page content wrapper (coord-11
+ * §19 / §P) lands with a stable `data-page-frame-start="page-<section>-<page>"`
+ * id. Until then callers rely on `scrollY` / `pageRect` for positioning.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { DEFAULT_PX_PER_TWIP } from "../../public-types.ts";
+
+/**
+ * Resolves a 1-based page number to a stable scroll target.
+ *
+ * - `elementId`: DOM id L11 populates on the per-page content wrapper.
+ *   Returns `null` while the L11 wrapper contract (coord-11 §19 / §P)
+ *   is still in flight — callers fall back to `scrollY`.
+ * - `scrollY`: scroll-container-relative Y offset of the page's top
+ *   edge in CSS px. Computed as the sum of prior pages' heights via
+ *   the layout facet's page graph.
+ * - `pageRect`: the page's content rectangle in the scroll container's
+ *   coordinate space. `top === scrollY`; `left === 0`; `width/height`
+ *   projected from the page's canonical `pageWidth` / `pageHeight`
+ *   twips via `DEFAULT_PX_PER_TWIP`.
+ */
+export interface PageAnchor {
+  readonly elementId: string | null;
+  readonly scrollY: number;
+  readonly pageRect: {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  } | null;
+}
+
+/**
+ * Per-page geometry for deterministic capture + truth-comparison.
+ * Stable across layout-recompute re-runs within the same
+ * `LAYOUT_ENGINE_VERSION`.
+ */
+export interface PageGeometry {
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly marginsPx: {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+  };
+  /** CSS px-per-inch honoring the default kernel conversion (96 / 1440 × 1440 = 96). */
+  readonly dpi: number;
+}
+
+/* ================================================================== */
+/*  getPageAnchor                                                     */
+/* ================================================================== */
+
+export const getPageAnchorMetadata: ApiV3FnMetadata = {
+  name: "runtime.viewport.getPageAnchor",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/viewport-page-anchor.test.ts",
+    commit: "refactor-07-viewport-family-2026-04-24",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "viewport-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.viewport.getPageAnchor. Reads the kernel-authoritative page frame from `handle.geometry.getPage(index).frame` — same source `ui.viewport.scrollToPage(n)` consumes (coord-10 §γ shipment `b8116b97`), so values stay consistent across the two surfaces. `elementId` stays null until L11's per-page content wrapper (coord-11 §19 / §P) lands; until then callers position off `scrollY` / `pageRect`. Promotes to `live` when the geometry facet surfaces a direct `getPageAnchor(pageNumber)` reader or when elementId is populated.",
+};
+
+/* ================================================================== */
+/*  getPageGeometry                                                   */
+/* ================================================================== */
+
+export const getPageGeometryMetadata: ApiV3FnMetadata = {
+  name: "runtime.viewport.getPageGeometry",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/viewport-page-anchor.test.ts",
+    commit: "refactor-07-viewport-family-2026-04-24",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "viewport-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.viewport.getPageGeometry. Projects the selected page's `PageLayoutSnapshot` (pageWidth/Height + margins, all in twips) into CSS px via `DEFAULT_PX_PER_TWIP`. `dpi: 96` matches the kernel's default. Promotes to `live` when the layout facet projects PageLayoutSnapshot in px directly.",
+};
+
+/* ================================================================== */
+/*  family factory                                                    */
+/* ================================================================== */
+
+export function createViewportFamily(runtime: RuntimeApiHandle) {
+  const layout = runtime.layout;
+
+  return {
+    getPageAnchor(pageNumber: number): PageAnchor | null {
+      // @endStateApi — live-with-adapter. Reads the kernel-authoritative
+      // page frame from `handle.geometry.getPage(index)` — same source
+      // `ui.viewport.scrollToPage(n)` (coord-10 §γ shipment `b8116b97`)
+      // consumes. Geometry's `frame.topPx` includes page gaps + rounding
+      // the kernel applies, matching the DOM scroll-container's actual
+      // Y. Layout-only pageHeight summation would omit page gaps and
+      // diverge from both the DOM and the ui.viewport.scrollToPage return.
+      if (!layout) return null;
+      if (!Number.isInteger(pageNumber) || pageNumber < 1) return null;
+      if (pageNumber > layout.getPageCount()) return null;
+      const pageIndex = pageNumber - 1;
+      const geometry = runtime.geometry;
+      const page = geometry?.getPage(pageIndex);
+      if (!page) return null;
+      return {
+        elementId: null,
+        scrollY: page.frame.topPx,
+        pageRect: {
+          left: page.frame.leftPx,
+          top: page.frame.topPx,
+          width: page.frame.widthPx,
+          height: page.frame.heightPx,
+        },
+      };
+    },
+
+    getPageGeometry(pageNumber: number): PageGeometry | null {
+      // @endStateApi — live-with-adapter.
+      if (!layout) return null;
+      if (!Number.isInteger(pageNumber) || pageNumber < 1) return null;
+      const pageCount = layout.getPageCount();
+      if (pageNumber > pageCount) return null;
+      const page = layout.getPage(pageNumber - 1);
+      if (!page) return null;
+      const lay = page.layout;
+      return {
+        widthPx: lay.pageWidth * DEFAULT_PX_PER_TWIP,
+        heightPx: lay.pageHeight * DEFAULT_PX_PER_TWIP,
+        marginsPx: {
+          top: lay.marginTop * DEFAULT_PX_PER_TWIP,
+          right: lay.marginRight * DEFAULT_PX_PER_TWIP,
+          bottom: lay.marginBottom * DEFAULT_PX_PER_TWIP,
+          left: lay.marginLeft * DEFAULT_PX_PER_TWIP,
+        },
+        dpi: 96,
+      };
+    },
+  };
+}