@beyondwork/docx-react-component 1.0.71 → 1.0.72

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.71",
+  "version": "1.0.72",
   "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

@@ -103,6 +103,27 @@ export type {
 export type { CollabSession } from "../runtime/collab-session.ts";
 export type { MetadataIntegrity } from "../runtime/workflow/tamper-gate.ts";
 export type { ScopeTagRegistry } from "../runtime/workflow/scope-tag-registry.ts";
+/**
+ * Zero-arg factory for the default-seeded `ScopeTagRegistry`. Two
+ * equivalent call sites ship today; pick whichever matches your scope:
+ *
+ *   - `createScopeTagRegistry()` (this re-export) — handle-free path for
+ *     L11 consumers that already import from `public-types`. §4.17
+ *     "simple pass-through of a runtime helper" precedent. Safe when
+ *     there's no `api` in scope (tests, pre-mount, PM-surface
+ *     component-internal memo).
+ *
+ *   - `api.runtime.workflow.createScopeTagRegistry()` — L06 proper API
+ *     home shipped 2026-04-23 per coord-10 §L11-4 (L11 delegation).
+ *     Preferred when a handle is already threaded: the registry is then
+ *     reachable through the same family as `queryScopes`, `getMarkup`,
+ *     etc., and the call appears in agent-audit telemetry.
+ *
+ * Both paths delegate to the same implementation in
+ * `src/runtime/workflow/scope-tag-registry.ts` and return an identical
+ * `ScopeTagRegistry` shape. No behavior difference.
+ */
+export { createScopeTagRegistry } from "../runtime/workflow/scope-tag-registry.ts";
 // Semantic-scope shapes — re-exported so L10 (ui.scope.*) + L09
 // (ai.getScopeBundle) + L11 (scope-card consumers) can import the
 // canonical types from the public-types choke point instead of
@@ -119,6 +140,23 @@ export type {
 } from "../runtime/scopes/semantic-scope-types.ts";
 export type { GeometryFacet } from "../runtime/geometry/index.ts";
 export type { RuntimePageGraph } from "../runtime/layout/page-graph.ts";
+export type { RuntimePageNode } from "../runtime/layout/page-graph.ts";
+
+/**
+ * `resolvePageFieldDisplayText` pure helper — resolves `PAGE` /
+ * `NUMPAGES` field text for a specific page + graph. Used by the PM
+ * page-break decoration renderer to substitute the cached preserve-
+ * only text with a live per-page number. Pure function over the
+ * already-public `RuntimePageGraph` / `RuntimePageNode` +
+ * `SupportedFieldFamily` types; no runtime handle in scope at the
+ * presentation-layer call site. Matches the §4.8 / §4.17 re-export
+ * precedent. Canonical impl lives on
+ * `src/runtime/layout/resolve-page-fields.ts`.
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 L04 layout
+ * long-tail row after `RuntimePageGraph` graduated to public-types.
+ */
+export type { PageFieldContext } from "../runtime/layout/resolve-page-fields.ts";
+export { resolvePageFieldDisplayText } from "../runtime/layout/resolve-page-fields.ts";
 
 export type {
   WordReviewEditorLayoutFacet,
@@ -182,6 +220,63 @@ export type { ScopeRailPosture } from "../runtime/workflow/rail/compose.ts";
 // reaching into `src/runtime/**` directly (P3).
 export type { SessionCapabilities } from "../runtime/session-capabilities.ts";
 
+/**
+ * `deriveCapabilities` value re-export — pure function over the
+ * already-public `RuntimeRenderSnapshot` + `WorkflowScopeSnapshot`
+ * inputs. Matches the `storyTargetsEqual` / unit-constant precedent
+ * for pure-helper re-exports where no runtime handle is in scope at
+ * the consumer. Called by `src/ui-tailwind/index.ts`'s public
+ * facade so hosts can derive capabilities without reaching into
+ * `src/runtime/**` directly. Re-exported 2026-04-24 per refactor/11
+ * handoff §4.17 self-closable row (L01 session-capabilities value).
+ */
+export { deriveCapabilities } from "../runtime/session-capabilities.ts";
+
+/**
+ * Editor capability table — frozen map + accompanying pure types.
+ * Re-exported 2026-04-24 per coord-10 §L11-1 (delegated from
+ * refactor/11 handoff register). Retires the direct reach-through
+ * from `src/ui/runtime-shortcut-dispatch.ts` into
+ * `src/runtime/editor-surface/capabilities.ts`. Matches the §4.8
+ * precedent class: frozen value + pure types, no runtime handle at
+ * the consumer. L07 may later formalize this as
+ * `api.runtime.capabilities.getById(id)` / `.list()`; the re-export
+ * here is the minimum-viable unblock.
+ */
+export type {
+  CapabilityKind,
+  CapabilityCategory,
+  CapabilityShortcut,
+  CapabilityBlockReason,
+  EditorCapability,
+} from "../runtime/editor-surface/capabilities.ts";
+export { CAPABILITY_BY_ID } from "../runtime/editor-surface/capabilities.ts";
+
+/**
+ * Per-page header/footer short-text preview maps — used by the in-flow
+ * page-chrome bands to show live content ("Page 3 of 5") instead of
+ * generic "Header" / "Footer" labels. Re-exported 2026-04-24 per coord-10
+ * §L11-2 (delegated from refactor/11 handoff register). `buildPagePreviewMaps`
+ * reads only `pages[].pageId / stories / isBlankFiller` on its graph input,
+ * and consumers already pass a structural adapter (see
+ * `tw-prosemirror-surface.tsx`); the minimum-viable unblock re-exports the
+ * function + result type without hoisting `RuntimePageGraph` itself. L04
+ * may later formalize as `api.runtime.layout.getPagePreviews(nav, subParts)`.
+ */
+export type { PagePreviewMaps } from "../runtime/layout/resolve-page-previews.ts";
+export { buildPagePreviewMaps } from "../runtime/layout/resolve-page-previews.ts";
+
+/**
+ * Canvas measurement backend factory — browser-only `LayoutMeasurementProvider`
+ * that uses Canvas2D `measureText()` for font-metric-aware width computation.
+ * Re-exported 2026-04-24 per coord-10 §L11-5 (delegated from refactor/11
+ * handoff register). Consumers pass the result to
+ * `WordReviewEditorLayoutFacet.swapMeasurementProvider(...)`; the provider
+ * type is already threaded through the facet's public surface. L04 may
+ * later formalize as `api.runtime.layout.createCanvasBackend()`.
+ */
+export { createCanvasBackend } from "../runtime/layout/measurement-backend-canvas.ts";
+
 export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
 export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
 export type SupportedFieldFamily = import("../model/canonical-document.ts").SupportedFieldFamily;
@@ -260,6 +355,89 @@ export type { EditorStoryTarget } from "../model/layout/page-layout-snapshot.ts"
  */
 export { storyTargetsEqual, MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
 
+/**
+ * `storyTargetKey` pure function — stable string key derivation for
+ * `EditorStoryTarget` (`main` / `header` / `footer` / `footnote` /
+ * `endnote`). Used by presentation-layer caches keyed by story
+ * target (e.g. floating-image overlay model). Matches the
+ * `storyTargetsEqual` precedent — pure function over a public type,
+ * no runtime handle in scope at the consumer. Canonical impl lives
+ * on `src/runtime/story-targeting.ts`.
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 self-closable row.
+ */
+export { storyTargetKey } from "../runtime/story-targeting.ts";
+
+/**
+ * Public-shape anchor constructors — pure helpers producing the
+ * `EditorAnchorProjection` discriminated union used in
+ * `SelectionSnapshot.activeRange`. `createPublicRangeAnchor`
+ * normalizes `from <= to` internally; `createPublicNodeAnchor`
+ * tags a node anchor at `at` with boundary associativity. Canonical
+ * impl lives on `src/core/selection/anchor-conversion.ts` — the
+ * single authority enforced by
+ * `test/api/anchor-boundary-invariants.test.ts`.
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 — the L03/L06
+ * selection-primitives row names `anchor-conversion` as a candidate
+ * for the public-types re-export pattern (chart family precedent)
+ * when the consumer is a leaf helper with no runtime handle in scope,
+ * which `src/ui/headless/selection-helpers.ts` is.
+ */
+export {
+  createPublicRangeAnchor,
+  createPublicNodeAnchor,
+} from "../core/selection/anchor-conversion.ts";
+
+/**
+ * L04 pagination pure helpers — leaf functions over already-public
+ * `DocumentPageSnapshot` / `PageLayoutSnapshot` / `SurfaceBlockSnapshot`
+ * shapes, used by presentation-layer page-chrome surfaces
+ * (`src/ui-tailwind/page-chrome-model.ts`). No runtime handle in scope
+ * at call sites — exactly the §4.8 precedent class.
+ *
+ * - `findPageForOffset(pages, offset)` — index resolver.
+ * - `estimateBlockHeight`, `estimateParagraphLineHeight`,
+ *   `estimateParagraphLineCount`, `getUsableColumnWidth` — pure
+ *   layout estimators used before real layout is available (cold
+ *   open + placeholder chrome).
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 L04 layout
+ * family long-tail. Canonical impls live on
+ * `src/runtime/document-navigation.ts` +
+ * `src/runtime/page-layout-estimation.ts`.
+ */
+export { findPageForOffset } from "../runtime/document-navigation.ts";
+export {
+  estimateBlockHeight,
+  estimateParagraphLineHeight,
+  estimateParagraphLineCount,
+  getUsableColumnWidth,
+} from "../runtime/page-layout-estimation.ts";
+
+/**
+ * L03/L06 search-text pure helpers + type aliases — pure functions
+ * over `SurfaceBlockSnapshot` + `SearchOptions` (public types) used
+ * by the PM search plugin at `src/ui-tailwind/editor-surface/search-plugin.ts`.
+ * No runtime handle in scope. Matches the handoff §4.17 "L03/L06
+ * selection/search primitives — promote to public-types.ts as pure
+ * re-exports (chart family precedent)" alternative.
+ *
+ * Canonical impl lives on `src/core/search/search-text.ts`.
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17. The larger
+ * `runtime.content.search` family seam on L07 is still the preferred
+ * long-term home; until it ships, this pragmatic re-export unblocks
+ * the L11 boundary register.
+ */
+export {
+  buildSearchPattern,
+  createSearchExcerpt,
+  findSearchMatches,
+  searchSecondaryStories,
+  type SecondaryStorySearchResult,
+  type SearchTextOptions,
+} from "../core/search/search-text.ts";
+
 /**
  * OOXML unit-conversion constants shared with presentation-layer
  * renderers. EMU (English Metric Units) is the OOXML measurement
@@ -280,6 +458,39 @@ export {
   SRCRECT_UNITS_PER_PERCENT,
 } from "../runtime/units.ts";
 
+/**
+ * Geometry-kernel + page-estimation unit constants used by presentation-
+ * layer chrome (table grip, page chrome). Both fold into public-types
+ * alongside the OOXML unit constants above so chrome overlays can
+ * convert between twips and CSS px without reaching into
+ * `src/runtime/**`.
+ *
+ * - `DEFAULT_PX_PER_TWIP = 96 / 1440` — kernel render-frame conversion
+ *   used by `tw-table-grip-layer` for grip positioning.
+ * - `DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP = 1 / 15` — page-chrome
+ *   estimation scale used for placeholder chrome before real layout.
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 self-closable
+ * rows. Canonical values live on `src/runtime/render/render-frame-types.ts`
+ * and `src/runtime/page-layout-estimation.ts`.
+ */
+export { DEFAULT_PX_PER_TWIP } from "../runtime/render/render-frame-types.ts";
+export { DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP } from "../runtime/page-layout-estimation.ts";
+
+/**
+ * Markdown sanitizer re-exported at the public-types boundary so the
+ * Layer-11 comment-markdown renderer can consume it without reaching
+ * into `src/runtime/**`. Pure function over a string; no runtime handle
+ * in scope at the leaf renderer. Canonical implementation lives on
+ * `src/runtime/markdown-sanitizer.ts` and is shared with
+ * `runtime/comment-presentation.ts`.
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 self-closable row.
+ */
+export {
+  sanitizeMarkdown,
+  type SanitizeResult,
+} from "../runtime/markdown-sanitizer.ts";
+
 export interface SelectionSnapshot {
   anchor: number;
   head: number;
@@ -904,7 +1115,16 @@ export type SurfaceTextMark =
   | "imprint"
   | "shadow"
   | "smallCaps"
-  | "allCaps";
+  | "allCaps"
+  /**
+   * Present iff the run carried `w:highlight`. The concrete highlight color
+   * is on `markAttrs.backgroundColor`. Consumers that only care about the
+   * presence signal (e.g. "is this run highlighted?") read `marks`; those
+   * that need the color read `markAttrs.backgroundColor`. Note that
+   * `backgroundColor` can also originate from `w:shd` (run shading) — only
+   * the `"highlight"` mark disambiguates the source.
+   */
+  | "highlight";
 
 /**
  * V2c.4 / V2c.5 — DrawingFrame anchor geometry projected onto image + shape
@@ -1657,6 +1877,15 @@ export interface TableStructureContextSnapshot {
   columnCount: number;
   selectedCellCount: number;
   isSimpleTable: boolean;
+  /**
+   * Table-level alignment declared on the canonical `TableNode.alignment`.
+   * `null` when the table has no explicit alignment (renders against the
+   * parent's default — typically left). Mirrors `PublicTableSummary.alignment`
+   * (refactor/11 §4.13) so the active-state of the whole-table alignment
+   * toolbar button can read from the context snapshot directly without
+   * a separate `getTable(tableBlockIndex).alignment` hop.
+   */
+  alignment: "left" | "center" | "right" | null;
   currentCell: {
     rowIndex: number;
     columnIndex: number;
@@ -2205,6 +2434,19 @@ export interface AddScopeParams {
    * held runtime-only, split across doc + workblock, or fully embedded.
    */
   metadata?: Partial<WorkflowMetadataEntry>;
+  /**
+   * Optional fields stamped onto the overlay scope's `metadata` array
+   * at creation time. Distinct from `metadata?: Partial<WorkflowMetadataEntry>`
+   * above (which writes a typed metadata *entry* keyed by `metadataId`);
+   * `scopeMetadataFields` lands as plain `WorkflowScopeMetadataField[]`
+   * on the `WorkflowScope.metadata` slot and survives serialization /
+   * collab replication with the overlay.
+   *
+   * Used by coord-08 §9 — L06's `createScopeFromBlockId({stableRefHint})`
+   * encodes the hint as `{key: "stableRefHint", value: <kind>}` here so
+   * the L08 compiler can read it back during enumeration.
+   */
+  scopeMetadataFields?: readonly WorkflowScopeMetadataField[];
   /** Non-main-body stories (footnote / header / endnote). */
   storyTarget?: EditorStoryTarget;
   /** Optional display label for the scope card / rail. */

package/src/api/v3/_create.ts

@@ -27,6 +27,7 @@ import { createClipboardFamily } from "./runtime/clipboard.ts";
 import { createChartFamily } from "./runtime/chart.ts";
 import { createSearchFamily } from "./runtime/search.ts";
 import { createTableFamily } from "./runtime/table.ts";
+import { createViewportFamily } from "./runtime/viewport.ts";
 
 import { createInspectFamily } from "./ai/inspect.ts";
 import { createResolveFamily } from "./ai/resolve.ts";
@@ -36,6 +37,10 @@ import { createAttachFamily } from "./ai/attach.ts";
 import { createExportFamily } from "./ai/export.ts";
 import { createExplainFamily } from "./ai/explain.ts";
 import { createPolicyFamily } from "./ai/policy.ts";
+import { createReviewFamily as createAiReviewFamily } from "./ai/review.ts";
+import { createEvaluateFamily } from "./ai/evaluate.ts";
+import { createStatsFamily } from "./ai/stats.ts";
+import { createOutlineFamily } from "./ai/outline.ts";
 
 import { createUiApi } from "./ui/_create.ts";
 import type { ApiV3Ui, UiControllerFactory } from "./ui/_types.ts";
@@ -62,6 +67,7 @@ export type ApiV3Runtime = {
   readonly chart: ReturnType<typeof createChartFamily>;
   readonly search: ReturnType<typeof createSearchFamily>;
   readonly table: ReturnType<typeof createTableFamily>;
+  readonly viewport: ReturnType<typeof createViewportFamily>;
 };
 
 export type ApiV3Ai = ReturnType<typeof createInspectFamily>
@@ -71,7 +77,11 @@ export type ApiV3Ai = ReturnType<typeof createInspectFamily>
   & ReturnType<typeof createAttachFamily>
   & ReturnType<typeof createExportFamily>
   & ReturnType<typeof createExplainFamily>
-  & ReturnType<typeof createPolicyFamily>;
+  & ReturnType<typeof createPolicyFamily>
+  & ReturnType<typeof createAiReviewFamily>
+  & ReturnType<typeof createEvaluateFamily>
+  & ReturnType<typeof createStatsFamily>
+  & ReturnType<typeof createOutlineFamily>;
 
 export interface ApiV3 {
   readonly runtime: ApiV3Runtime;
@@ -117,6 +127,10 @@ export function createApiV3(handle: RuntimeApiHandle, opts?: CreateApiV3Opts): A
     ...createExportFamily(handle),
     ...createExplainFamily(handle),
     ...createPolicyFamily(handle),
+    ...createAiReviewFamily(handle),
+    ...createEvaluateFamily(handle),
+    ...createStatsFamily(handle),
+    ...createOutlineFamily(handle),
   };
   const runtime: ApiV3Runtime = {
     document: createDocumentFamily(handle),
@@ -131,6 +145,7 @@ export function createApiV3(handle: RuntimeApiHandle, opts?: CreateApiV3Opts): A
     chart: createChartFamily(handle),
     search: createSearchFamily(handle),
     table: createTableFamily(handle),
+    viewport: createViewportFamily(handle),
   };
   // Construct the UI namespace only when a factory is supplied.
   // `ui` remains `undefined` otherwise — the shape in ApiV3 is optional

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

@@ -55,6 +55,7 @@ export type RuntimeApiHandle = Pick<
   // Review (runtime.review family)
   | "getReviewWorkSnapshot"
   | "acceptChange"
+  | "rejectChange"
   | "resolveComment"
   // Workflow (runtime.workflow + ai.inspect families)
   | "queryScopes"
@@ -131,6 +132,7 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   findAllText: true,
   getReviewWorkSnapshot: true,
   acceptChange: true,
+  rejectChange: true,
   resolveComment: true,
   queryScopes: true,
   getWorkflowMarkupSnapshot: true,

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

@@ -0,0 +1,113 @@
+/**
+ * @endStateApi v3 — `ai.evaluate` family.
+ *
+ * evaluateAction — pre-flight verdict combining /06's static policy
+ * matrix with live runtime state. Returns whether an action can
+ * currently proceed, what blockers (if any) apply, and whether human
+ * approval is required per the policy tier.
+ *
+ * Composition rules:
+ *
+ *   1. If `policy.support` is `'blocked'` or `'unsupported'`, emit a
+ *      `policy-refused:<support>` blocker. `allowed: false` regardless
+ *      of live state — the policy override wins.
+ *
+ *   2. When `input.scopeId` is supplied, resolve it via the scope
+ *      compiler. If it does not resolve, emit
+ *      `scope-not-resolvable:<scopeId>` and flip `allowed: false`. This
+ *      mirrors the refusal taxonomy that `ai.validateReplacementScope`
+ *      surfaces.
+ *
+ *   3. `approvalRequired` is the policy tier's confirmation flag —
+ *      `support === 'confirmation-required' ||
+ *      requirements.userConfirmation`. Agents should surface this to a
+ *      human before calling the mutating path, even when `allowed:
+ *      true`.
+ *
+ * Read-family function — A4 audit emission does not apply.
+ * `validateReplacementScope` remains the authoritative pre-flight for
+ * replacement-class mutations (it runs the full `composeScopeValidation`
+ * pipeline); `evaluateAction` is a lighter, scope-optional probe an
+ * agent can call against any `AIAction`, including non-replacement
+ * operations (resolve_comment_thread, auto_accept_changes, etc.) that
+ * have no scope target.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  getAIActionPolicy,
+  type AIAction,
+  type AIActionPolicy,
+} from "../../../runtime/workflow/ai-action-policy.ts";
+import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
+
+export interface EvaluateActionInput {
+  readonly action: AIAction;
+  readonly scopeId?: string;
+}
+
+export interface EvaluateActionResult {
+  readonly action: AIAction;
+  readonly allowed: boolean;
+  readonly policy: AIActionPolicy;
+  readonly blockers: readonly string[];
+  readonly approvalRequired: boolean;
+}
+
+export const evaluateActionMetadata: ApiV3FnMetadata = {
+  name: "ai.evaluateAction",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-evaluate-action.test.ts",
+    commit: "refactor-09-post-closure-evaluate-action",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "policy-evaluate",
+    contextPromptShape:
+      "Pre-flight verdict: can this action proceed against (optionally) this scope? Returns {allowed, policy, blockers, approvalRequired}. Composes getPolicy() with live scope resolvability.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§AI API § ai.evaluateAction. Composes /06's static policy matrix with live scope resolvability. Returns a single-verdict carrier agents branch on before calling the mutating path. Read-only; no audit emission.",
+};
+
+export function createEvaluateFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
+  return {
+    evaluateAction(input: EvaluateActionInput): EvaluateActionResult {
+      // @endStateApi — live-with-adapter. Composes /06's static policy
+      // matrix with live scope resolvability from the /08 compiler.
+      const policy = getAIActionPolicy(input.action);
+      const blockers: string[] = [];
+
+      if (policy.support === "blocked" || policy.support === "unsupported") {
+        blockers.push(`policy-refused:${policy.support}`);
+      }
+
+      if (input.scopeId !== undefined) {
+        const compiled = compiler.compileScopeById(input.scopeId);
+        if (!compiled) {
+          blockers.push(`scope-not-resolvable:${input.scopeId}`);
+        }
+      }
+
+      const approvalRequired =
+        policy.support === "confirmation-required" ||
+        policy.requirements.userConfirmation === true;
+
+      return {
+        action: input.action,
+        allowed: blockers.length === 0,
+        policy,
+        blockers: Object.freeze([...blockers]),
+        approvalRequired,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,140 @@
+/**
+ * @endStateApi v3 — `ai.getDocumentOutline`.
+ *
+ * Composes the layer-04/07 navigation snapshot with the layer-07 outline
+ * builder to return a heading tree an agent can surface for "jump to
+ * section" / "summarize this section" flows.
+ *
+ * Each entry carries `headingId`, `level`, `text`, `offset`, `pageIndex`,
+ * `sectionIndex`, and `parentHeadingIds` (top-level headings have an
+ * empty array). `activeHeadingId` points at the heading containing the
+ * current selection head, if any.
+ *
+ * Read-family; no audit emission.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type {
+  DocumentOutlineHeadingSnapshot,
+  DocumentOutlineSnapshot,
+} from "../../public-types.ts";
+import { createDocumentNavigationSnapshot } from "../../../runtime/document-navigation.ts";
+import { createDocumentOutlineSnapshot } from "../../../runtime/document-outline.ts";
+import {
+  computeBlockPositions,
+  createScopeCompilerService,
+} from "../../../runtime/scopes/index.ts";
+
+/**
+ * Gap B (coord-08 post-Slice-7 integration) — v3 extension of
+ * `DocumentOutlineHeadingSnapshot` that carries the L08 scope
+ * compiler's `scopeId` for each heading. Agents use it directly with
+ * `ai.applyReplacementScope` / `ai.attachExplanation` / etc. without a
+ * separate `ai.listScopes({kind:"heading"})` lookup + offset match.
+ *
+ * The field is populated when the compiler's heading enumeration has
+ * a matching entry by block-range start; omitted when no match is
+ * found (e.g. a heading outside the `main` story). Empty-docs /
+ * no-heading docs return `headings: []` — the enrichment is a no-op.
+ */
+export type GetDocumentOutlineHeadingEntry = DocumentOutlineHeadingSnapshot & {
+  readonly scopeId?: string;
+};
+
+export type GetDocumentOutlineResult = Omit<
+  DocumentOutlineSnapshot,
+  "headings"
+> & {
+  readonly headings: readonly GetDocumentOutlineHeadingEntry[];
+};
+
+export const getDocumentOutlineMetadata: ApiV3FnMetadata = {
+  name: "ai.getDocumentOutline",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  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-outline-read",
+    contextPromptShape:
+      "Hierarchical heading outline — {headingId, level, text, offset, pageIndex, sectionIndex, parentHeadingIds} per entry, plus activeHeadingId when selection lives under a heading.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§AI API § ai.getDocumentOutline. Composes createDocumentNavigationSnapshot (L04/07) with createDocumentOutlineSnapshot (L07) to surface the heading tree. Read-only; no audit emission.",
+};
+
+export function createOutlineFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
+  return {
+    getDocumentOutline(): GetDocumentOutlineResult {
+      // @endStateApi — live-with-adapter. Composes L04/07 navigation
+      // snapshot with L07 outline builder to surface heading tree;
+      // enriches each heading entry with the L08 compiler's `scopeId`
+      // (Gap B, coord-08 post-Slice-7 integration).
+      const snapshot = runtime.getRenderSnapshot();
+      const document = runtime.getCanonicalDocument();
+      const selectionHead = snapshot.selection.head;
+      const navigation = createDocumentNavigationSnapshot(
+        document,
+        selectionHead,
+        snapshot.activeStory,
+      );
+      const outline = createDocumentOutlineSnapshot({
+        navigation,
+        activeStory: snapshot.activeStory,
+        selectionHead,
+      });
+
+      // Gap B enrichment — build an offset → scopeId map over the
+      // heading enumeration and join onto each outline entry. The
+      // offset-based join uses `computeBlockPositions` to translate
+      // the compiler's `blockIndex` (on the enumerated scope's
+      // `semanticPath`) back into a character offset equal to the
+      // outline's `offset` field.
+      const headingScopes = compiler
+        .compileAllScopes()
+        .filter((s) => s.kind === "heading");
+      const blockPositions = computeBlockPositions(document);
+      const blockOffsetByIndex = new Map<number, number>();
+      for (const entry of blockPositions) {
+        blockOffsetByIndex.set(entry.blockIndex, entry.from);
+      }
+      const scopeIdByOffset = new Map<number, string>();
+      for (const scope of headingScopes) {
+        // `semanticPath` is ["body", "heading", <level>, <blockIndex>]
+        // — the blockIndex is the last segment. Numeric parse + offset
+        // lookup gives us the heading paragraph's character offset.
+        const path = scope.handle.semanticPath;
+        const lastSegment = path[path.length - 1];
+        if (typeof lastSegment !== "string") continue;
+        const blockIndex = Number.parseInt(lastSegment, 10);
+        if (!Number.isFinite(blockIndex)) continue;
+        const offset = blockOffsetByIndex.get(blockIndex);
+        if (typeof offset === "number") {
+          scopeIdByOffset.set(offset, scope.handle.scopeId);
+        }
+      }
+
+      const enrichedHeadings: GetDocumentOutlineHeadingEntry[] =
+        outline.headings.map((heading) => {
+          const scopeId = scopeIdByOffset.get(heading.offset);
+          return scopeId ? { ...heading, scopeId } : heading;
+        });
+
+      return {
+        ...(outline.activeHeadingId
+          ? { activeHeadingId: outline.activeHeadingId }
+          : {}),
+        headings: enrichedHeadings,
+      };
+    },
+  };
+}

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

@@ -121,6 +121,13 @@ export interface ApplyResult {
   readonly reason?: string;
   readonly blockers?: readonly string[];
   readonly auditHint?: string;
+  /**
+   * Gap A (post-Slice-7 integration) — revision IDs authored during
+   * the apply. Populated for suggest-mode (tracked insert + delete);
+   * empty for direct-edit. Agents chain into `ai.acceptRevision` /
+   * `ai.rejectRevision` with each id to land or discard the proposal.
+   */
+  readonly authoredRevisionIds: readonly string[];
 }
 
 export interface ApplyReplacementScopeInput {
@@ -331,6 +338,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
+        authoredRevisionIds: result.authoredRevisionIds,
       };
     },
   };