@beyondwork/docx-react-component 1.0.58 → 1.0.59

package/src/runtime/document-runtime.ts

@@ -88,6 +88,11 @@ import type {
   WorkflowScopeSnapshot,
   ScopeQueryFilter,
   ScopeQueryResult,
+  ScopeVisibility,
+  ScopeChromeVisibilityState,
+  SearchOptions,
+  TextStyleFilter,
+  WorkflowScopeMode,
   WorkspaceMode,
   WordReviewEditorEvent,
   ZoomLevel,
@@ -138,6 +143,7 @@ import {
 } from "../review/store/revision-store.ts";
 import { createSuggestionsSnapshot } from "./suggestions-snapshot.ts";
 import { validateSelectionAgainstDocument } from "./selection/post-edit-validator.ts";
+import { createSurfaceNodeSelectionProbe } from "./selection/post-edit-validator.ts";
 import {
   collectScopeLocations,
   findAllScopesAt,
@@ -155,6 +161,10 @@ import {
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
+import {
+  findTextMatches,
+  findTextWithStyleMatches,
+} from "./document-search.ts";
 import {
   collectWorkflowMarkupSnapshot,
   deriveWorkflowCandidateRangesFromMarkup,
@@ -420,6 +430,15 @@ export interface DocumentRuntime {
    */
   applyRemoteCommandBatch(envelopes: ReadonlyArray<RemoteCommandEnvelope>): void;
   emitBlockedCommand(command: string, reasons: WorkflowBlockedCommandReason[]): void;
+  /**
+   * Emit a fire-and-forget `warning_added` event + `onWarning` callback for
+   * a host-layer no-op (e.g. `applyRuntimeDeleteComment` invoked with an
+   * unknown id). The warning is NOT persisted to `state.warnings` or the
+   * compatibility report — same semantics as a reducer-emitted
+   * `effects.transientWarnings` entry, exposed here for host-side paths
+   * that never reach a reducer.
+   */
+  emitTransientWarning(warning: InternalEditorWarning): void;
   undo(): void;
   redo(): void;
   focus(): void;
@@ -430,11 +449,33 @@ export interface DocumentRuntime {
   openComment(commentId: string): void;
   resolveComment(commentId: string): void;
   reopenComment(commentId: string): void;
-  addCommentReply(commentId: string, body: string, authorId?: string): AddCommentReplyResult;
+  /**
+   * Append a reply entry to an existing thread. Returns the minted
+   * `{ commentId, entryId }` on success. Returns `null` when the thread
+   * is unknown, resolved, or detached — in that case a
+   * `review_target_not_found` warning fires on `onWarning` / `warning_added`
+   * with structured `details.op = "addCommentReply"` and `details.reason`
+   * ∈ `{ "comment_unknown", "comment_status" }`.
+   */
+  addCommentReply(
+    commentId: string,
+    body: string,
+    authorId?: string,
+  ): AddCommentReplyResult | null;
   editCommentBody(commentId: string, body: string): void;
   addScope(params: AddScopeParams): AddScopeResult;
   getScope(scopeId: string): WorkflowScope | null;
   removeScope(scopeId: string): void;
+  /** §C8 — Add a scope with visibility: "invisible" atomically. */
+  addInvisibleScope(params: Omit<AddScopeParams, "mode"> & { mode?: WorkflowScopeMode }): AddScopeResult;
+  /** §C8 — Set a scope's visibility (collab-replicated). */
+  setScopeVisibility(scopeId: string, visibility: ScopeVisibility): void;
+  /** §C8 — Get a scope's current visibility (absent = "visible"). */
+  getScopeVisibility(scopeId: string): ScopeVisibility;
+  /** §C7 — Set local chrome visibility state (never collab-replicated). */
+  setScopeChromeVisibility(state: ScopeChromeVisibilityState): void;
+  /** §C7 — Get local chrome visibility state (default: { mode: "all" }). */
+  getScopeChromeVisibility(): ScopeChromeVisibilityState;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
@@ -520,6 +561,23 @@ export interface DocumentRuntime {
    * `WordReviewEditorRef.queryScopes` for contract.
    */
   queryScopes(filter?: ScopeQueryFilter): ScopeQueryResult[];
+  /** Phase C §C1 — live subscription; returns unsubscribe fn. */
+  subscribeToScopeQuery(
+    filter: ScopeQueryFilter,
+    callback: (results: ScopeQueryResult[]) => void,
+  ): () => void;
+  /** Phase C §C4 — text search + style filter. */
+  findAllText(query: string, options?: SearchOptions): EditorAnchorProjection[];
+  findTextWithStyle(
+    query: string,
+    filter: TextStyleFilter,
+    options?: SearchOptions,
+  ): EditorAnchorProjection[];
+  selectTextWithStyle(
+    query: string,
+    filter: TextStyleFilter,
+    options?: SearchOptions,
+  ): number;
   /**
    * Phase C §C2 — geometric scope queries. See `WordReviewEditorRef`
    * for contract. Non-range anchors yield `[]`.
@@ -815,6 +873,8 @@ export function createDocumentRuntime(
     ?? options.initialSnapshot?.workflowMetadata?.entries
     ?? [];
   let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
+  // §C7 — local view-state for scope chrome visibility; never collab-replicated.
+  let scopeChromeVisibilityState: ScopeChromeVisibilityState = { mode: "all" };
   // P13 Slice B: shared workflow state from the collab Y.Map "workflow".
   // Set via setSharedWorkflowState(); observed by evaluateWorkflowBlockedReasons.
   let sharedWorkflowState: SharedWorkflowState | null = null;
@@ -957,6 +1017,10 @@ export function createDocumentRuntime(
   let cachedCompatibility:
     | {
         revisionToken: string;
+        /** Block count at the time of the last full rebuild. O(1) proxy for structural stability. */
+        blockCount: number;
+        /** Warning count at time of rebuild — warnings array gets remapped on every edit. */
+        warningCount: number;
         warnings: EditorState["warnings"];
         fatalError: EditorState["fatalError"];
         report: RuntimeRenderSnapshot["compatibility"];
@@ -1107,6 +1171,14 @@ export function createDocumentRuntime(
         snapshot: WorkflowMarkupSnapshot;
       }
     | undefined;
+  // Keyed on block count + subParts identity (not revisionToken) — fields only
+  // change when blocks are inserted/deleted or subParts (headers/footers) change,
+  // NOT on text-only edits. Cleared explicitly by updateFields() for field-refresh.
+  let cachedFieldSnapshotEntry: {
+    blockCount: number;
+    subParts: CanonicalDocumentEnvelope["subParts"];
+    snapshot: FieldSnapshot;
+  } | null = null;
   const cachedContextAnalyticsSnapshots = new Map<
     string,
     {
@@ -1152,16 +1224,53 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
+  function getCachedFieldSnapshot(document: CanonicalDocumentEnvelope): FieldSnapshot {
+    const blockCount = document.content.children.length;
+    if (
+      cachedFieldSnapshotEntry &&
+      cachedFieldSnapshotEntry.blockCount === blockCount &&
+      cachedFieldSnapshotEntry.subParts === document.subParts
+    ) {
+      return cachedFieldSnapshotEntry.snapshot;
+    }
+    const snapshot = buildFieldSnapshot(document);
+    cachedFieldSnapshotEntry = { blockCount, subParts: document.subParts, snapshot };
+    return snapshot;
+  }
+
   function getCachedCompatibilityReport(
     nextState: EditorState,
   ): RuntimeRenderSnapshot["compatibility"] {
-    if (
-      cachedCompatibility &&
-      cachedCompatibility.revisionToken === nextState.revisionToken &&
-      cachedCompatibility.warnings === nextState.warnings &&
-      cachedCompatibility.fatalError === nextState.fatalError
-    ) {
-      return cachedCompatibility.report;
+    const blockCount = nextState.document.content.children.length;
+    const warningCount = nextState.warnings?.length ?? 0;
+    if (cachedCompatibility) {
+      // Fast path 1: same revisionToken (selection move, surface-only refresh).
+      if (
+        cachedCompatibility.revisionToken === nextState.revisionToken &&
+        cachedCompatibility.warnings === nextState.warnings &&
+        cachedCompatibility.fatalError === nextState.fatalError
+      ) {
+        return cachedCompatibility.report;
+      }
+      // Fast path 2: revisionToken changed but block structure and warning
+      // count are stable (text-only edit). buildCompatibilityReport reads
+      // block types, review counts, preservation, and warnings — NOT run text.
+      // Block count + warning count + fatalError identity is an O(1) proxy:
+      // if these are stable, the compatibility report output is unchanged.
+      // `warnings` array gets remapped to a new reference on every commit via
+      // remapReviewStateAfterContentChange, so we can't use reference equality.
+      if (
+        cachedCompatibility.blockCount === blockCount &&
+        cachedCompatibility.warningCount === warningCount &&
+        cachedCompatibility.fatalError === nextState.fatalError
+      ) {
+        cachedCompatibility = {
+          ...cachedCompatibility,
+          revisionToken: nextState.revisionToken,
+          warnings: nextState.warnings,
+        };
+        return cachedCompatibility.report;
+      }
     }
 
     const derived = createDerivedCompatibility(nextState);
@@ -1178,6 +1287,8 @@ export function createDocumentRuntime(
     };
     cachedCompatibility = {
       revisionToken: nextState.revisionToken,
+      blockCount,
+      warningCount,
       warnings: nextState.warnings,
       fatalError: nextState.fatalError,
       report,
@@ -1424,8 +1535,13 @@ export function createDocumentRuntime(
     if (normalizedWorkflowOverlay) {
       const matchingScope = getMatchingWorkflowScope(selection);
       const activeScopes = getEffectiveWorkflowScopes(normalizedWorkflowOverlay);
+      // §C8: invisible non-view scopes are transparent to the interaction guard.
+      // Don't count them toward the "outside_workflow_scope" threshold.
+      const guardingScopes = activeScopes.filter(
+        (s) => !(s.visibility === "invisible" && s.mode !== "view"),
+      );
 
-      if (!matchingScope && activeScopes.length > 0) {
+      if (!matchingScope && guardingScopes.length > 0) {
         reasons.push({
           code: "outside_workflow_scope",
           message: "Selection is outside any active workflow scope.",
@@ -1456,24 +1572,60 @@ export function createDocumentRuntime(
     return reasons;
   }
 
-  function getMatchingWorkflowScope(
-    selection: EditorState["selection"],
-  ): WorkflowOverlay["scopes"][number] | null {
-    if (!workflowOverlay) {
-      return null;
-    }
+  // §C6 — most-restrictive-wins ordering for overlap layering.
+  const MODE_RESTRICTIVENESS: Record<WorkflowScopeMode, number> = {
+    edit: 0,
+    suggest: 1,
+    comment: 2,
+    view: 3,
+  };
 
+  /**
+   * §C6 — Collect all guard-eligible scopes that contain `selection`,
+   * sorted outermost→innermost (startPos ASC, endPos DESC, scopeId ASC).
+   * Excludes invisible non-view scopes per §C8.
+   */
+  function buildMatchingScopeStack(
+    selection: EditorState["selection"],
+  ): WorkflowOverlay["scopes"] {
+    if (!workflowOverlay) return [];
     const selectionBounds = {
       from: Math.min(selection.anchor, selection.head),
       to: Math.max(selection.anchor, selection.head),
     };
     const activeScopes = getEffectiveWorkflowScopes(workflowOverlay);
-    return activeScopes.find((scope) => {
+    const matching = activeScopes.filter((scope) => {
+      // §C8
+      if (scope.visibility === "invisible" && scope.mode !== "view") return false;
       if (scope.anchor.kind === "detached") return false;
       const scopeFrom = scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
       const scopeTo = scope.anchor.kind === "range" ? scope.anchor.to : scope.anchor.at;
       return selectionBounds.from >= scopeFrom && selectionBounds.to <= scopeTo;
-    }) ?? null;
+    });
+    // Outermost first: startPos ASC, endPos DESC (wider span = outer), scopeId ASC tiebreak
+    matching.sort((a, b) => {
+      const aFrom = a.anchor.kind === "range" ? a.anchor.from : (a.anchor as { at: number }).at;
+      const bFrom = b.anchor.kind === "range" ? b.anchor.from : (b.anchor as { at: number }).at;
+      if (aFrom !== bFrom) return aFrom - bFrom;
+      const aTo = a.anchor.kind === "range" ? a.anchor.to : (a.anchor as { at: number }).at;
+      const bTo = b.anchor.kind === "range" ? b.anchor.to : (b.anchor as { at: number }).at;
+      if (aTo !== bTo) return bTo - aTo; // wider first
+      return a.scopeId < b.scopeId ? -1 : a.scopeId > b.scopeId ? 1 : 0;
+    });
+    return matching;
+  }
+
+  function getMatchingWorkflowScope(
+    selection: EditorState["selection"],
+  ): WorkflowOverlay["scopes"][number] | null {
+    const stack = buildMatchingScopeStack(selection);
+    if (stack.length === 0) return null;
+    // §C6 — most-restrictive scope wins across all overlapping scopes.
+    return stack.reduce((best, scope) =>
+      (MODE_RESTRICTIVENESS[scope.mode] ?? 0) > (MODE_RESTRICTIVENESS[best.mode] ?? 0)
+        ? scope
+        : best,
+    );
   }
 
   function getEffectiveDocumentMode(
@@ -1892,6 +2044,7 @@ export function createDocumentRuntime(
 
     const blockedReasons = evaluateWorkflowBlockedReasons(state.selection);
     const matchingScope = getMatchingWorkflowScope(state.selection);
+    const scopeStack = buildMatchingScopeStack(state.selection);
     const primaryBlockedReason = blockedReasons[0];
     const effectiveMode = primaryBlockedReason
       ? (
@@ -1904,10 +2057,19 @@ export function createDocumentRuntime(
       : getEffectiveDocumentMode(state.selection) === "suggesting"
         ? "suggest"
         : matchingScope?.mode ?? "edit";
+    const matchedScopeStack: InteractionGuardSnapshot["matchedScopeStack"] =
+      scopeStack.length > 0
+        ? scopeStack.map((s) => ({
+            scopeId: s.scopeId,
+            mode: s.mode,
+            visibility: s.visibility ?? "visible",
+          }))
+        : undefined;
     const snapshot: InteractionGuardSnapshot = {
       effectiveMode,
       ...(matchingScope?.scopeId ? { matchedScopeId: matchingScope.scopeId } : {}),
       ...(matchingScope?.mode ? { matchedScopeMode: matchingScope.mode } : {}),
+      ...(matchedScopeStack ? { matchedScopeStack } : {}),
       targetAccess:
         effectiveMode === "edit"
           ? "direct-edit"
@@ -1992,7 +2154,7 @@ export function createDocumentRuntime(
 
     const snapshot = collectWorkflowMarkupSnapshot({
       renderSnapshot: cachedRenderSnapshot,
-      fieldSnapshot: buildFieldSnapshot(state.document),
+      fieldSnapshot: getCachedFieldSnapshot(state.document),
       protectionSnapshot,
       preservation: state.document.preservation,
       workflowMetadataSnapshot: deriveWorkflowMetadataSnapshot(),
@@ -2297,6 +2459,7 @@ export function createDocumentRuntime(
     cachedWorkflowScopeSnapshot = undefined;
     cachedNormalizedWorkflowOverlay = undefined;
     cachedWorkflowMarkupSnapshot = undefined;
+    cachedFieldSnapshotEntry = null;
     cachedContextAnalyticsSnapshots.clear();
     lastEmittedContextAnalyticsSnapshots = undefined;
   }
@@ -2313,8 +2476,11 @@ export function createDocumentRuntime(
       document,
     };
     if (previousDocument.subParts !== document.subParts) {
-      fontLoader.refresh(collectFontLoaderInput(document));
-      layoutEngine.invalidateMeasurementCache();
+      const fontInput = collectFontLoaderInput(document);
+      if (!fontFamiliesEqual(fontInput.families, collectFontLoaderInput(previousDocument).families)) {
+        fontLoader.refresh(fontInput);
+        layoutEngine.invalidateMeasurementCache();
+      }
     }
     invalidateDerivedRuntimeCaches();
     cachedRenderSnapshot = refreshRenderSnapshot();
@@ -2473,6 +2639,15 @@ export function createDocumentRuntime(
         reasons,
       });
     },
+    emitTransientWarning(warning) {
+      const publicWarning = toPublicWarning(warning);
+      emit({
+        type: "warning_added",
+        documentId: state.documentId,
+        warning: publicWarning,
+      });
+      options.onWarning?.(publicWarning);
+    },
     dispatch(command) {
       const commandSelection = getCommandSelection(command, state.selection);
       if (isMutationCommand(command)) {
@@ -3083,7 +3258,7 @@ export function createDocumentRuntime(
       });
     },
     addCommentReply(commentId, body, authorId) {
-      const priorEntryCount =
+      const priorCount =
         state.document.review.comments[commentId]?.entries?.length ?? 0;
       this.dispatch({
         type: "comment.add-reply",
@@ -3092,8 +3267,16 @@ export function createDocumentRuntime(
         authorId: authorId ?? defaultAuthorId,
         origin: createOrigin("api", clock()),
       });
-      const entryId = `${commentId}-entry-${priorEntryCount + 1}`;
-      return { commentId, entryId };
+      // Read post-dispatch state. The reducer skips silently on unknown /
+      // resolved / detached threads and emits a `review_target_not_found`
+      // transient warning from `effects.transientWarnings` — callers who
+      // need to know about the skip listen on `onWarning`.
+      const entries = state.document.review.comments[commentId]?.entries ?? [];
+      if (entries.length <= priorCount) {
+        return null;
+      }
+      const last = entries[entries.length - 1]!;
+      return { commentId, entryId: last.entryId };
     },
     editCommentBody(commentId, body) {
       this.dispatch({
@@ -3250,6 +3433,38 @@ export function createDocumentRuntime(
         }
       }
     },
+    addInvisibleScope(params) {
+      const result = this.addScope({
+        ...params,
+        mode: params.mode ?? "comment",
+      });
+      this.setScopeVisibility(result.scopeId, "invisible");
+      return result;
+    },
+    setScopeVisibility(scopeId, visibility) {
+      if (!workflowOverlay) return;
+      const idx = workflowOverlay.scopes.findIndex((s) => s.scopeId === scopeId);
+      if (idx === -1) return;
+      const nextScopes = workflowOverlay.scopes.map((s) =>
+        s.scopeId === scopeId ? { ...s, visibility } : s,
+      );
+      this.dispatch({
+        type: "workflow.set-overlay",
+        overlay: { ...workflowOverlay, scopes: nextScopes },
+        origin: createOrigin("api", clock()),
+      });
+    },
+    getScopeVisibility(scopeId): ScopeVisibility {
+      if (!workflowOverlay) return "visible";
+      const scope = workflowOverlay.scopes.find((s) => s.scopeId === scopeId);
+      return scope?.visibility ?? "visible";
+    },
+    setScopeChromeVisibility(state) {
+      scopeChromeVisibilityState = state;
+    },
+    getScopeChromeVisibility(): ScopeChromeVisibilityState {
+      return scopeChromeVisibilityState;
+    },
     acceptChange(changeId) {
       this.dispatch({
         type: "change.accept",
@@ -3382,7 +3597,11 @@ export function createDocumentRuntime(
     getFootnoteResolver(): FootnoteResolver | undefined {
       const collection = state.document.subParts?.footnoteCollection;
       if (!collection) return undefined;
-      return createFootnoteResolver(collection, collectSectionPropertiesInOrder(state.document));
+      return createFootnoteResolver(
+        collection,
+        collectSectionPropertiesInOrder(state.document),
+        state.document,
+      );
     },
     layout: layoutFacet,
     getCurrentLocation() {
@@ -3529,6 +3748,9 @@ export function createDocumentRuntime(
         options,
       );
       if (refreshed.changed) {
+        // Field display text changed — clear field snapshot cache so the
+        // next getCachedFieldSnapshot call rebuilds with fresh displayText.
+        cachedFieldSnapshotEntry = null;
         this.dispatch({
           type: "document.replace",
           document: refreshed.document,
@@ -3733,6 +3955,68 @@ export function createDocumentRuntime(
         filter,
       );
     },
+    subscribeToScopeQuery(filter, callback) {
+      const buildKey = (results: ScopeQueryResult[]) =>
+        results
+          .map(
+            (r) =>
+              `${r.scope.scopeId}:${r.scope.version ?? 0}:${r.scope.visibility ?? "visible"}`,
+          )
+          .join(",");
+
+      let lastKey = "";
+      const fire = () => {
+        const results = this.queryScopes(filter);
+        const key = buildKey(results);
+        if (key !== lastKey) {
+          lastKey = key;
+          callback(results);
+        }
+      };
+
+      // Immediate initial fire
+      fire();
+
+      let pendingTimer: ReturnType<typeof setTimeout> | null = null;
+      const unsub = this.subscribe(() => {
+        if (pendingTimer !== null) return;
+        pendingTimer = setTimeout(() => {
+          pendingTimer = null;
+          fire();
+        }, 0);
+      });
+
+      return () => {
+        unsub();
+        if (pendingTimer !== null) {
+          clearTimeout(pendingTimer);
+          pendingTimer = null;
+        }
+      };
+    },
+    findAllText(query, options) {
+      const sel = makePublicSelectionSnapshot(state.selection.anchor, state.selection.head);
+      return findTextMatches(state.document, sel, query, options ?? {});
+    },
+    findTextWithStyle(query, filter, options) {
+      const sel = makePublicSelectionSnapshot(state.selection.anchor, state.selection.head);
+      return findTextWithStyleMatches(state.document, sel, query, filter, options ?? {});
+    },
+    selectTextWithStyle(query, filter, options) {
+      const sel = makePublicSelectionSnapshot(state.selection.anchor, state.selection.head);
+      const hits = findTextWithStyleMatches(state.document, sel, query, filter, options ?? {});
+      if (hits.length > 0 && hits[0]) {
+        const first = hits[0];
+        if (first.kind === "range") {
+          this.dispatch({
+            type: "selection.set",
+            selection: createSelectionSnapshot(first.from, first.to),
+            origin: createOrigin("api", clock()),
+          });
+        }
+      }
+      return hits.length;
+    },
     findScopesAt(position, options) {
       const pos =
         position.kind === "range"
@@ -3925,6 +4209,38 @@ export function createDocumentRuntime(
   }
 
   function applyTransactionToState(transaction: EditorTransaction): void {
+    // Pure-no-op short-circuit: when a reducer skipped without emitting any
+    // observable effect AND the selection is identical, skip finalizeState
+    // / invalidate / refresh / notify entirely. This keeps hot paths (e.g.
+    // host loops that query invalid ids) cheap — no clock allocation, no
+    // listener loop, no snapshot rebuild for nothing. Transient-warning
+    // commits (the `review_target_not_found` path) carry
+    // `transientWarnings.length > 0` and MUST fall through so `notify`
+    // can emit them. Selection-only dispatches (e.g. `selection.set`) also
+    // fall through because `nextState.selection !== state.selection`.
+    const effects = transaction.effects;
+    const selectionUnchanged = transaction.nextState.selection === state.selection;
+    const isPureNoop =
+      !transaction.markDirty &&
+      transaction.historyBoundary === "skip" &&
+      transaction.mapping.steps.length === 0 &&
+      selectionUnchanged &&
+      effects.warningsAdded.length === 0 &&
+      effects.warningsCleared.length === 0 &&
+      (effects.transientWarnings?.length ?? 0) === 0 &&
+      !effects.commentAdded &&
+      !effects.commentResolved &&
+      !effects.commentReopened &&
+      !effects.commentReplyAdded &&
+      !effects.commentBodyEdited &&
+      !effects.changeAccepted &&
+      !effects.changeRejected &&
+      !effects.revisionAuthored &&
+      !effects.commandBlocked;
+    if (isPureNoop) {
+      return;
+    }
+
     const previous = state;
 
     const tApply0 = performance.now();
@@ -3948,8 +4264,11 @@ export function createDocumentRuntime(
       }
     }
     if (previous.document.subParts !== state.document.subParts) {
-      fontLoader.refresh(collectFontLoaderInput(state.document));
-      layoutEngine.invalidateMeasurementCache();
+      const fontInput = collectFontLoaderInput(state.document);
+      if (!fontFamiliesEqual(fontInput.families, collectFontLoaderInput(previous.document).families)) {
+        fontLoader.refresh(fontInput);
+        layoutEngine.invalidateMeasurementCache();
+      }
     }
     perfCounters.increment("commit.invalidate.us", Math.round((performance.now() - tInvalidate0) * 1000));
 
@@ -3979,10 +4298,16 @@ export function createDocumentRuntime(
     // which is optional in the public API for shape-only reasons — the helper
     // itself always returns a defined snapshot.
     const surfaceForValidation = getCachedSurface(state.document, activeStory)!;
+    const validationOptions = state.selection.activeRange.kind === "node"
+      ? {
+          isValidNodeTarget: createSurfaceNodeSelectionProbe(surfaceForValidation),
+        }
+      : undefined;
     const validatedSelection = validateSelectionAgainstDocument(
       state.document,
       state.selection,
       surfaceForValidation.storySize,
+      validationOptions,
     );
     if (validatedSelection !== state.selection) {
       state = { ...state, selection: validatedSelection };
@@ -4184,6 +4509,23 @@ export function createDocumentRuntime(
       options.onWarning?.(publicWarning);
     }
 
+    if (transaction.effects.transientWarnings) {
+      // Fire-and-forget diagnostics (e.g. `review_target_not_found` on a
+      // silent-skip reducer). Surfaces on `warning_added` + `onWarning`
+      // like any other warning, but never touches `state.warnings` or the
+      // compatibility report, so repeated no-op calls (e.g. a host
+      // looping `resolveComment` over stale ids) do not accumulate entries.
+      for (const warning of transaction.effects.transientWarnings) {
+        const publicWarning = toPublicWarning(warning);
+        emit({
+          type: "warning_added",
+          documentId: next.documentId,
+          warning: publicWarning,
+        });
+        options.onWarning?.(publicWarning);
+      }
+    }
+
     for (const cleared of transaction.effects.warningsCleared) {
       emit({
         type: "warning_cleared",
@@ -4433,9 +4775,16 @@ export function createDocumentRuntime(
     base: EditorTransaction["effects"],
     local: EditorTransaction["effects"],
   ): EditorTransaction["effects"] {
+    const baseTransient = base.transientWarnings ?? [];
+    const localTransient = local.transientWarnings ?? [];
+    const mergedTransient =
+      baseTransient.length + localTransient.length === 0
+        ? undefined
+        : [...baseTransient, ...localTransient];
     return {
       warningsAdded: [...base.warningsAdded, ...local.warningsAdded],
       warningsCleared: [...base.warningsCleared, ...local.warningsCleared],
+      ...(mergedTransient ? { transientWarnings: mergedTransient } : {}),
       commentAdded: base.commentAdded ?? local.commentAdded,
       commentResolved: base.commentResolved ?? local.commentResolved,
       commentReopened: base.commentReopened ?? local.commentReopened,
@@ -4979,7 +5328,13 @@ function toRuntimeError(error: unknown): InternalEditorError {
 function toStructuredRuntimeException<T extends InternalEditorError>(
   error: T,
 ): Error & T {
-  return Object.assign(new Error(error.message), error);
+  const exception = Object.assign(new Error(error.message), error);
+  // Set `name` so host wrappers that must branch across process / bundle
+  // boundaries (e.g. the gRPC handlers in `vendor/beyondwork/src/ts/docx-api`)
+  // can discriminate structured editor errors from generic `Error` objects
+  // via `error.name === "EditorError"` — `instanceof` is unreliable there.
+  exception.name = "EditorError";
+  return exception;
 }
 
 function toPublicDocumentStats(state: Pick<EditorState, "document">) {
@@ -5077,11 +5432,14 @@ function extractSelectionFragment(
 }
 
 /**
- * Collect the stable ids of comment threads whose entry differs
- * (present in one side but not the other, OR present in both but
- * referencing a different object — which indicates any mutation to
- * the thread, since the runtime treats `review.comments` as
- * immutable per commit). Used by the `comments_changed` event.
+ * Collect the stable ids of comment threads whose host-observable state
+ * differs between two commits. A reference-identity diff was too noisy —
+ * any `remapCommentStore` pass (fired on every text edit that touches a
+ * thread's anchor region) rebuilt the thread objects and would have marked
+ * every thread as "changed" even when only their anchor numerics shifted
+ * in a way that doesn't affect what the host renders. The semantic diff
+ * below compares the fields hosts actually consume: status, anchor shape,
+ * entry count + ordering, resolution metadata, and warning ids.
  */
 function diffCommentMapKeys(
   previous: CanonicalDocumentEnvelope["review"]["comments"],
@@ -5089,14 +5447,65 @@ function diffCommentMapKeys(
 ): string[] {
   const changed = new Set<string>();
   for (const id of Object.keys(previous)) {
-    if (previous[id] !== next[id]) changed.add(id);
+    if (!next[id]) changed.add(id);
   }
   for (const id of Object.keys(next)) {
-    if (previous[id] !== next[id]) changed.add(id);
+    const prev = previous[id];
+    if (!prev) {
+      changed.add(id);
+      continue;
+    }
+    if (prev === next[id]) continue;
+    if (!semanticallyEqualCommentThreads(prev, next[id]!)) changed.add(id);
   }
   return Array.from(changed);
 }
 
+function semanticallyEqualCommentThreads(
+  prev: CanonicalDocumentEnvelope["review"]["comments"][string],
+  next: CanonicalDocumentEnvelope["review"]["comments"][string],
+): boolean {
+  if (prev.status !== next.status) return false;
+  if (prev.isResolved !== next.isResolved) return false;
+  if (prev.resolvedAt !== next.resolvedAt) return false;
+  if (prev.resolution?.resolvedAt !== next.resolution?.resolvedAt) return false;
+  if (prev.resolution?.resolvedBy !== next.resolution?.resolvedBy) return false;
+  if (prev.body !== next.body) return false;
+  if ((prev.entries?.length ?? 0) !== (next.entries?.length ?? 0)) return false;
+  const prevEntries = prev.entries ?? [];
+  const nextEntries = next.entries ?? [];
+  for (let i = 0; i < prevEntries.length; i++) {
+    const pe = prevEntries[i]!;
+    const ne = nextEntries[i]!;
+    if (pe.entryId !== ne.entryId) return false;
+    if (pe.body !== ne.body) return false;
+    if (pe.authorId !== ne.authorId) return false;
+  }
+  const prevWarnings = prev.warningIds ?? [];
+  const nextWarnings = next.warningIds ?? [];
+  if (prevWarnings.length !== nextWarnings.length) return false;
+  for (let i = 0; i < prevWarnings.length; i++) {
+    if (prevWarnings[i] !== nextWarnings[i]) return false;
+  }
+  const prevAnchor = prev.anchor;
+  const nextAnchor = next.anchor;
+  if (prevAnchor === nextAnchor) return true;
+  if (prevAnchor.kind !== nextAnchor.kind) return false;
+  if (prevAnchor.kind === "range" && nextAnchor.kind === "range") {
+    return (
+      prevAnchor.range.from === nextAnchor.range.from &&
+      prevAnchor.range.to === nextAnchor.range.to
+    );
+  }
+  if (prevAnchor.kind === "node" && nextAnchor.kind === "node") {
+    return prevAnchor.at === nextAnchor.at;
+  }
+  if (prevAnchor.kind === "detached" && nextAnchor.kind === "detached") {
+    return prevAnchor.reason === nextAnchor.reason;
+  }
+  return false;
+}
+
 function toPublicCompatibilityReport(
   report: InternalCompatibilityReport,
 ): CompatibilityReport {
@@ -5510,6 +5919,22 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+function makePublicSelectionSnapshot(anchor: number, head: number): SelectionSnapshot {
+  const from = Math.min(anchor, head);
+  const to = Math.max(anchor, head);
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: {
+      kind: "range",
+      from,
+      to,
+      assoc: { start: -1, end: 1 },
+    },
+  };
+}
+
 /** Commands that are safe in viewing mode (no document mutation). */
 const NON_MUTATION_COMMANDS = new Set([
   "selection.set",
@@ -5526,6 +5951,9 @@ const NON_MUTATION_COMMANDS = new Set([
   "workflow.clear-metadata-entries",
   "host-annotation.set-overlay",
   "host-annotation.clear-overlay",
+  // API-level full-document replacement (scope markers, protection refresh,
+  // collab replay). Not user-initiated — must bypass the workflow guard.
+  "document.replace",
 ]);
 
 /** Mutation commands that are not yet supported in suggesting mode. */
@@ -6626,6 +7054,17 @@ const fontLoaderInputCache = new WeakMap<
   WeakMap<object, { families: readonly string[] }>
 >();
 
+function fontFamiliesEqual(
+  a: readonly string[],
+  b: readonly string[],
+): boolean {
+  if (a.length !== b.length) return false;
+  // Both arrays are Set-derived (no duplicates); sort for order-independence.
+  const sortedA = [...a].sort();
+  const sortedB = [...b].sort();
+  return sortedA.every((v, i) => v === sortedB[i]);
+}
+
 function collectFontLoaderInput(
   document: CanonicalDocumentEnvelope,
 ): { families: readonly string[] } {
@@ -6678,6 +7117,9 @@ function collectFontLoaderInputUncached(
 /** Test-only export of the uncached walk so memoization tests can spy on it. */
 export const __collectFontLoaderInputUncached = collectFontLoaderInputUncached;
 
+/** Test-only export of the font-family set equality helper. */
+export const __fontFamiliesEqual = fontFamiliesEqual;
+
 /**
  * Asynchronously upgrade the engine's measurement backend to canvas once
  * the platform supports it and fonts have resolved.  Errors are swallowed