@beyondwork/docx-react-component 1.0.83 → 1.0.85

package/package.json

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

package/src/api/internal/build-ref-projections.ts

@@ -52,6 +52,9 @@ export function buildRefProjections(
     rejectAll: () => getRef().rejectAllChanges(),
     acceptGroup: (groupId) => getRef().acceptSuggestionGroup(groupId),
     rejectGroup: (groupId) => getRef().rejectSuggestionGroup(groupId),
+    getCommentThread: (changeId) => getRef().getCommentThreadForChange(changeId),
+    ensureCommentThread: (changeId) => getRef().ensureCommentThreadForChange(changeId),
+    addReply: (changeId, body) => getRef().addReplyToChange(changeId, body),
     scrollTo: (revisionId) => getRef().scrollToRevision(revisionId),
     get: () => getRef().getTrackedChanges(),
     getSuggestions: () => getRef().getSuggestionsSnapshot(),

package/src/api/public-types.ts

@@ -592,6 +592,8 @@ export interface CommentSidebarThreadSnapshot {
   createdBy: string;
   warningCount: number;
   anchorLabel: string;
+  /** Present when this thread is the discussion attached to a tracked change. */
+  linkedRevisionId?: string;
   detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
   actionabilityNote?: string;
   isActive: boolean;
@@ -630,6 +632,10 @@ export interface TrackedChangeEntrySnapshot {
   warningCount: number;
   canAccept: boolean;
   canReject: boolean;
+  /** Comment threads whose metadata links them to this revision. */
+  commentThreadIds?: string[];
+  /** Number of reply entries across linked comment threads. */
+  replyCount?: number;
   preserveOnlyReason?: string;
   excerpt?: string;
   detail?: string;
@@ -672,6 +678,10 @@ export interface SuggestionEntrySnapshot {
   preserveOnlyReason?: string;
   excerpt?: string;
   detail?: string;
+  /** Comment threads linked to any revision in this suggestion unit. */
+  commentThreadIds?: string[];
+  /** Number of reply entries across linked comment threads. */
+  replyCount?: number;
   /**
    * R3 — scope-card-overlay P2. When present, links this entry to a
    * `SuggestionGroup` via `SuggestionsSnapshot.groups[].groupId`.
@@ -1311,6 +1321,12 @@ export type SurfaceInlineSegment =
       instruction: string;
       refreshStatus: FieldRefreshStatus;
       label: string;
+      /**
+       * Current display text for fields whose visible value is computed by
+       * layout context (PAGE / NUMPAGES / SECTIONPAGES). Consumers fall back
+       * to `label` when absent.
+       */
+      displayText?: string;
     }
   | {
       /**
@@ -2512,6 +2528,16 @@ export interface AddScopeParams {
   storyTarget?: EditorStoryTarget;
   /** Optional display label for the scope card / rail. */
   label?: string;
+  /**
+   * Optional per-scope visibility. Controls chrome/query presentation only;
+   * edit enforcement is controlled by `guardPolicy`.
+   */
+  visibility?: ScopeVisibility;
+  /**
+   * Optional edit-enforcement posture. Absent means advisory for
+   * edit/suggest/comment scopes and read-only for `mode: "view"`.
+   */
+  guardPolicy?: WorkflowScopeGuardPolicy;
 }
 
 export interface AddScopeResult {
@@ -2591,6 +2617,19 @@ export interface ExportResult {
 
 export type WorkflowScopeMode = "edit" | "suggest" | "comment" | "view";
 
+/**
+ * Explicit scope enforcement axis. Visibility is presentation-only.
+ *
+ * - `"none"`: advisory/metadata/chrome scope; direct editing is unaffected.
+ * - `"insert-only"`: allowlist scope; when any active insert-only scope
+ *   exists, selection-driven edits outside insert-only scopes are blocked.
+ * - `"read-only"`: deny edits inside this scope; outside content is unaffected.
+ *
+ * When absent, `mode: "view"` scopes default to `"read-only"` for
+ * compatibility; all other modes default to `"none"`.
+ */
+export type WorkflowScopeGuardPolicy = "none" | "insert-only" | "read-only";
+
 /**
  * §C7 — Local chrome visibility mode. Never collab-replicated.
  * - `"all"`:      show all scope rail entries + decorations (default).
@@ -2615,8 +2654,8 @@ export interface ScopeChromeVisibilityState {
  *
  * - `"visible"`:   rail entry + card + inline decoration (current behavior).
  * - `"hidden"`:    in the rail but muted; card opens on explicit click; no decoration.
- * - `"invisible"`: never rendered; only queryable via API. Does NOT contribute
- *   to InteractionGuard unless `mode === "view"` (explicit host opt-in).
+ * - `"invisible"`: never rendered; only queryable via API. Visibility never
+ *   contributes to InteractionGuard.
  */
 export type ScopeVisibility = "visible" | "hidden" | "invisible";
 
@@ -2639,6 +2678,12 @@ export interface WorkflowScope {
   domain?: "legal" | "commercial" | "finance" | "other";
   metadataRefs?: string[];
   metadata?: WorkflowScopeMetadataField[];
+  /**
+   * Explicit edit-enforcement posture. Absent means:
+   * - `mode: "view"` -> `"read-only"` (legacy read-only behavior).
+   * - all other modes -> `"none"` (advisory/chrome/metadata only).
+   */
+  guardPolicy?: WorkflowScopeGuardPolicy;
   /**
    * Schema 1.1 — override the overlay default for this scope.
    * `"inherit"` defers to the overlay; absent is equivalent to
@@ -4402,6 +4447,9 @@ export interface WordReviewEditorChangesFacet {
   rejectAll(): void;
   acceptGroup(groupId: string): void;
   rejectGroup(groupId: string): void;
+  getCommentThread(changeId: string): CommentSidebarThreadSnapshot | null;
+  ensureCommentThread(changeId: string): AddCommentResult | null;
+  addReply(changeId: string, body: string): AddCommentReplyResult | null;
   scrollTo(revisionId: string): void;
   get(): TrackedChangesSnapshot;
   getSuggestions(): SuggestionsSnapshot;
@@ -4549,6 +4597,25 @@ export interface WordReviewEditorRef {
     commentId: string,
     body: string,
   ): AddCommentReplyResult | null;
+  /**
+   * Return the open/resolved comment thread linked to a tracked change, if
+   * one exists. This is the read side for "reply to tracked change" UX.
+   */
+  getCommentThreadForChange(changeId: string): CommentSidebarThreadSnapshot | null;
+  /**
+   * Create or return the discussion thread attached to a tracked change.
+   * Newly-created threads are anchored to the revision range and opened in
+   * the comments rail by mounted UI callers.
+   */
+  ensureCommentThreadForChange(changeId: string): AddCommentResult | null;
+  /**
+   * Append a reply to a tracked change's linked discussion thread, creating
+   * that thread first when needed.
+   */
+  addReplyToChange(
+    changeId: string,
+    body: string,
+  ): AddCommentReplyResult | null;
   editCommentBody(commentId: string, body: string): void;
   deleteComment(commentId: string): void;
   /**
@@ -4571,8 +4638,9 @@ export interface WordReviewEditorRef {
   removeScope(scopeId: string): void;
   /**
    * §C8 — Convenience: adds a scope with `visibility: "invisible"` atomically.
-   * Mode defaults to `"comment"` — invisible scopes carry no InteractionGuard
-   * constraint unless `mode: "view"` is passed explicitly.
+   * Mode defaults to `"comment"`. Visibility is presentation-only; edit
+   * gating is controlled by `guardPolicy` (`mode: "view"` still defaults to
+   * read-only for compatibility unless `guardPolicy: "none"` is set).
    */
   addInvisibleScope(
     params: Omit<AddScopeParams, "mode"> & { mode?: WorkflowScopeMode },
@@ -4587,6 +4655,20 @@ export interface WordReviewEditorRef {
    * scopes or when the `visibility` field has never been set.
    */
   getScopeVisibility(scopeId: string): ScopeVisibility;
+  /**
+   * Set a scope's edit-enforcement posture. Collab-replicated through the
+   * workflow overlay; visibility remains purely presentational.
+   */
+  setScopeGuardPolicy(
+    scopeId: string,
+    guardPolicy: WorkflowScopeGuardPolicy,
+  ): void;
+  /**
+   * Get a scope's effective guard policy. Returns `"read-only"` for legacy
+   * `mode: "view"` scopes with no explicit policy and `"none"` for unknown
+   * scopes.
+   */
+  getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy;
   /**
    * §C7 — Set the local chrome-visibility state. Local view-state only —
    * never collab-replicated. Controls whether the scope rail / decorations

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

@@ -53,12 +53,18 @@ export type RuntimeApiHandle = Pick<
   | "getCanonicalDocument"
   // Content search + selection (runtime.content + ai.bundle families)
   | "findAllText"
+  | "replaceText"
+  // Formatting mutations (runtime.formatting.apply)
+  | "applyFormattingOperation"
   // Review (runtime.review family)
   | "getReviewWorkSnapshot"
   | "getSuggestionsSnapshot"
   | "acceptChange"
   | "rejectChange"
   | "resolveComment"
+  | "getCommentThreadForChange"
+  | "ensureCommentThreadForChange"
+  | "addReplyToChange"
   // Workflow (runtime.workflow + ai.inspect families)
   | "queryScopes"
   | "getWorkflowMarkupSnapshot"
@@ -70,6 +76,8 @@ export type RuntimeApiHandle = Pick<
   // live seam. `getWorkflowMetadataSnapshot` is the read side the
   // metadata writer inspects before merging its entry.
   | "addScope"
+  | "setScopeGuardPolicy"
+  | "getScopeGuardPolicy"
   | "setWorkflowMetadataEntries"
   | "getWorkflowMetadataSnapshot"
   // W10 overlay-visibility policy (state-classes X1). Class-A canonical
@@ -145,16 +153,23 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   getRenderSnapshot: true,
   getCanonicalDocument: true,
   findAllText: true,
+  replaceText: true,
+  applyFormattingOperation: true,
   getReviewWorkSnapshot: true,
   getSuggestionsSnapshot: true,
   acceptChange: true,
   rejectChange: true,
   resolveComment: true,
+  getCommentThreadForChange: true,
+  ensureCommentThreadForChange: true,
+  addReplyToChange: true,
   queryScopes: true,
   getWorkflowMarkupSnapshot: true,
   getInteractionGuardSnapshot: true,
   getWorkflowOverlay: true,
   addScope: true,
+  setScopeGuardPolicy: true,
+  getScopeGuardPolicy: true,
   setWorkflowMetadataEntries: true,
   getWorkflowMetadataSnapshot: true,
   getVisibilityPolicy: true,

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

@@ -12,7 +12,12 @@
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
-import type { CanonicalDocumentFragment } from "../../public-types.ts";
+import type {
+  CanonicalDocumentFragment,
+  EditorAnchorProjection,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+} from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
 import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
 
@@ -179,6 +184,18 @@ export function createContentFamily(runtime: RuntimeApiHandle) {
       // Layer-08 compiler-service facade. Same pipeline as
       // ai.applyReplacementScope; the host/UI path omits actionId (not
       // an agent action) and tags origin:"ui" + actorId:"user".
+      const tableCellResult = replaceTableCellText(runtime, input);
+      if (tableCellResult) {
+        emitUxResponse(runtime, {
+          apiFn: replaceTextMetadata.name,
+          intent: replaceTextMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: replaceTextMetadata.uxIntent.expectedDelta,
+        });
+        return tableCellResult;
+      }
+
       const result = compiler.applyReplacement({
         targetScopeId: input.scopeId,
         operation: "replace",
@@ -234,3 +251,133 @@ export function createContentFamily(runtime: RuntimeApiHandle) {
     },
   };
 }
+
+function replaceTableCellText(
+  runtime: RuntimeApiHandle,
+  input: ReplaceTextInput,
+): ReplaceTextResult | null {
+  const parsed = parseTableCellScopeId(input.scopeId);
+  if (!parsed) {
+    return null;
+  }
+
+  const snapshot = runtime.getRenderSnapshot();
+  if (!snapshot.isReady || snapshot.readOnly || snapshot.fatalError) {
+    return { applied: false, reason: "document-not-editable" };
+  }
+
+  const document = runtime.getCanonicalDocument();
+  const rootChild = document.content.children[parsed.blockIndex];
+  if (!rootChild || rootChild.type !== "table") {
+    return { applied: false, reason: "table-cell-scope-not-resolvable" };
+  }
+
+  const tableOrdinal = document.content.children
+    .slice(0, parsed.blockIndex)
+    .filter((block) => block.type === "table").length;
+  const tableBlock =
+    snapshot.surface?.blocks.find(
+      (block): block is Extract<SurfaceBlockSnapshot, { kind: "table" }> =>
+        block.kind === "table" && block.blockId === `table-${tableOrdinal}`,
+    ) ??
+    (snapshot.surface?.blocks[parsed.blockIndex]?.kind === "table"
+      ? snapshot.surface.blocks[parsed.blockIndex]
+      : null);
+  if (!tableBlock || tableBlock.kind !== "table") {
+    return { applied: false, reason: "table-cell-surface-not-realized" };
+  }
+
+  const cell = tableBlock.rows[parsed.rowIndex]?.cells[parsed.cellIndex];
+  if (!cell) {
+    return { applied: false, reason: "table-cell-scope-not-resolvable" };
+  }
+
+  const range = resolveTableCellTextRange(cell.content);
+  if (range.status === "empty") {
+    return { applied: false, reason: "table-cell-empty-text" };
+  }
+  if (range.status === "ambiguous") {
+    return { applied: false, reason: "table-cell-text-scope-ambiguous" };
+  }
+  const { from, to } = range;
+
+  const anchor: EditorAnchorProjection = {
+    kind: "range",
+    from,
+    to,
+    assoc: { start: -1, end: 1 },
+  };
+  const beforeRevisionToken = snapshot.revisionToken;
+  runtime.replaceText(input.replacement, anchor);
+  const afterRevisionToken = runtime.getRenderSnapshot().revisionToken;
+  if (afterRevisionToken === beforeRevisionToken) {
+    return { applied: false, reason: "replace-text-not-applied" };
+  }
+  return { applied: true };
+}
+
+function parseTableCellScopeId(
+  scopeId: string,
+): { blockIndex: number; rowIndex: number; cellIndex: number } | null {
+  const match = /^cell:(\d+):(\d+):(\d+)$/u.exec(scopeId);
+  if (!match) return null;
+  return {
+    blockIndex: Number(match[1]),
+    rowIndex: Number(match[2]),
+    cellIndex: Number(match[3]),
+  };
+}
+
+type TableCellTextRangeResult =
+  | { status: "ok"; from: number; to: number }
+  | { status: "empty" }
+  | { status: "ambiguous" };
+
+function resolveTableCellTextRange(
+  blocks: readonly SurfaceBlockSnapshot[],
+): TableCellTextRangeResult {
+  const paragraphRanges = collectTableCellParagraphTextRanges(blocks);
+  if (paragraphRanges.length === 0) {
+    return { status: "empty" };
+  }
+  if (paragraphRanges.length > 1) {
+    return { status: "ambiguous" };
+  }
+  const [range] = paragraphRanges;
+  return range && range.from < range.to
+    ? { status: "ok", from: range.from, to: range.to }
+    : { status: "empty" };
+}
+
+function collectTableCellParagraphTextRanges(
+  blocks: readonly SurfaceBlockSnapshot[],
+  output: Array<{ from: number; to: number }> = [],
+): Array<{ from: number; to: number }> {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      const textSegments = block.segments.filter(
+        (segment): segment is Extract<SurfaceInlineSegment, { kind: "text" }> =>
+          segment.kind === "text" && segment.from < segment.to,
+      );
+      if (textSegments.length > 0) {
+        output.push({
+          from: Math.min(...textSegments.map((segment) => segment.from)),
+          to: Math.max(...textSegments.map((segment) => segment.to)),
+        });
+      }
+      continue;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectTableCellParagraphTextRanges(cell.content, output);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      collectTableCellParagraphTextRanges(block.children, output);
+    }
+  }
+  return output;
+}

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

@@ -13,12 +13,14 @@
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { emitUxResponse } from "../_ux-response.ts";
 import {
   resolveEffectiveFormatting,
   createFormattingContext,
   type EffectiveFormatting,
   type RunProvenance,
 } from "../../../runtime/formatting/index.ts";
+import type { FormattingOperation } from "../../../core/commands/formatting-commands.ts";
 import {
   findParagraphByBlockId,
   resolveDirectRunFormattingAtSegment,
@@ -132,8 +134,47 @@ export const resolveRunWithProvenanceMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.formatting.resolveRunWithProvenance. Agent-facing provenance view — `source ∈ {direct, characterStyle, style, docDefaults}` plus `sourceId` for style tiers. Substrate for ai.explainFormatting (L09).",
 };
 
+export const applyMetadata: ApiV3FnMetadata = {
+  name: "runtime.formatting.apply",
+  status: "live",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/formatting-adapter.test.ts",
+    commit: "refactor-03-tracked-changes-v1-formatting-apply-2026-04-23",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "formatting changes in the active selection",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "formatting-write",
+  },
+  rwdReference:
+    "§Runtime API § runtime.formatting.apply. Live adapter over DocumentRuntime.applyFormattingOperation(); supports direct formatting/paragraph alignment/indentation and authors bounded property-change suggestions when the effective mode is suggesting. Style suggestions are intentionally not accepted by this operation shape.",
+};
+
 export function createFormattingFamily(runtime: RuntimeApiHandle) {
   return {
+    apply(operation: FormattingOperation): void {
+      // @endStateApi — live. Delegates to the runtime-owned mutation seam
+      // so direct edits, workflow blocking, and suggesting-mode property-
+      // change authorship all share one implementation.
+      runtime.applyFormattingOperation(operation);
+      emitUxResponse(runtime, {
+        apiFn: applyMetadata.name,
+        intent: applyMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: applyMetadata.uxIntent.expectedDelta,
+      });
+    },
+
     getEffective(
       nodeRef: FormattingNodeRef,
       opts?: FormattingGetEffectiveOpts,

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

@@ -8,6 +8,8 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
+  AddCommentReplyResult,
+  AddCommentResult,
   CommentSidebarThreadSnapshot,
   SuggestionsSnapshot,
   TrackedChangeEntrySnapshot,
@@ -120,6 +122,56 @@ export const resolveCommentMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.review.resolveComment",
 };
 
+export const getCommentThreadForChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.getCommentThreadForChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-redline-revision-thread-link",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "review-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.review.getCommentThreadForChange. Live adapter over runtime linked revision comment threads.",
+};
+
+export const ensureCommentThreadForChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.ensureCommentThreadForChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-redline-revision-thread-link",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "comment thread opens for tracked change" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "comment-add" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.review.ensureCommentThreadForChange. Creates or returns the comment thread attached to a tracked change.",
+};
+
+export const addReplyToChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.addReplyToChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-redline-revision-thread-link",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "reply appears on tracked-change thread" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "comment-reply" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.review.addReplyToChange. Appends a reply to the comment thread linked to a tracked change.",
+};
+
 export function createReviewFamily(runtime: RuntimeApiHandle) {
   return {
     getComments(): readonly CommentSidebarThreadSnapshot[] {
@@ -140,6 +192,52 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
       return runtime.getSuggestionsSnapshot();
     },
 
+    getCommentThreadForChange(changeId: string): CommentSidebarThreadSnapshot | null {
+      // @endStateApi — live. Reads the comment thread linked to a tracked
+      // change from the canonical comment projection.
+      return runtime.getCommentThreadForChange(changeId);
+    },
+
+    ensureCommentThreadForChange(changeId: string): AddCommentResult | null {
+      // @endStateApi — live. Ensures a canonical comment thread exists for
+      // a tracked change and emits an inline UX response when created/found.
+      const result = runtime.ensureCommentThreadForChange(changeId);
+      if (result) {
+        emitUxResponse(runtime, {
+          apiFn: ensureCommentThreadForChangeMetadata.name,
+          intent: ensureCommentThreadForChangeMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: ensureCommentThreadForChangeMetadata.uxIntent.expectedDelta,
+          actualDelta: {
+            kind: "inline-change",
+            payload: { changeId, commentId: result.commentId },
+          },
+        });
+      }
+      return result;
+    },
+
+    addReplyToChange(changeId: string, body: string): AddCommentReplyResult | null {
+      // @endStateApi — live. Appends a canonical comment reply to the
+      // thread linked to a tracked change.
+      const result = runtime.addReplyToChange(changeId, body);
+      if (result) {
+        emitUxResponse(runtime, {
+          apiFn: addReplyToChangeMetadata.name,
+          intent: addReplyToChangeMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: addReplyToChangeMetadata.uxIntent.expectedDelta,
+          actualDelta: {
+            kind: "inline-change",
+            payload: { changeId, commentId: result.commentId, entryId: result.entryId },
+          },
+        });
+      }
+      return result;
+    },
+
     acceptChange(changeId: string): void {
       // @endStateApi — live. Delegates.
       runtime.acceptChange(changeId);