@beyondwork/docx-react-component 1.0.58 → 1.0.60

package/src/runtime/document-runtime.ts

@@ -88,6 +88,11 @@ import type {
   WorkflowScopeSnapshot,
   ScopeQueryFilter,
   ScopeQueryResult,
+  ScopeVisibility,
+  ScopeChromeVisibilityState,
+  SearchOptions,
+  TextStyleFilter,
+  WorkflowScopeMode,
   WorkspaceMode,
   WordReviewEditorEvent,
   ZoomLevel,
@@ -138,12 +143,14 @@ 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,
   findScopesIntersecting,
   resolveScope,
 } from "./scope-resolver.ts";
+import { buildDiagnosticFromLegacyWarningCode } from "./diagnostics/build-diagnostic.ts";
 import {
   projectScopeQueryResults,
   queryScopes as runQueryScopes,
@@ -155,6 +162,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 +431,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 +450,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 +562,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 `[]`.
@@ -814,7 +873,10 @@ export function createDocumentRuntime(
     options.initialSessionState?.workflowMetadata?.entries
     ?? options.initialSnapshot?.workflowMetadata?.entries
     ?? [];
+  let markerBackedScopeIds = new Set<string>();
   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;
@@ -849,6 +911,32 @@ export function createDocumentRuntime(
   storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
   lastHeadingFingerprint = computeHeadingFingerprint(state.document);
 
+  function syncMarkerBackedScopeIds(
+    document: CanonicalDocumentEnvelope,
+    overlay: WorkflowOverlay | null,
+  ): void {
+    const presentScopeIds = new Set(collectScopeLocations(document).keys());
+    if (!overlay) {
+      markerBackedScopeIds = presentScopeIds;
+      return;
+    }
+    const overlayScopeIds = new Set(overlay.scopes.map((scope) => scope.scopeId));
+    const next = new Set<string>();
+    for (const scopeId of markerBackedScopeIds) {
+      if (overlayScopeIds.has(scopeId)) {
+        next.add(scopeId);
+      }
+    }
+    for (const scopeId of presentScopeIds) {
+      if (overlayScopeIds.has(scopeId)) {
+        next.add(scopeId);
+      }
+    }
+    markerBackedScopeIds = next;
+  }
+
+  syncMarkerBackedScopeIds(state.document, workflowOverlay);
+
   // Runtime-owned paginated layout engine (Phase 1+ of the layout facet work).
   // The engine caches graph + resolved-formatting + fragment mapper keyed on
   // (content, styles, subParts).  It is the single internal source of truth
@@ -957,6 +1045,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 +1199,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 +1252,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 +1315,8 @@ export function createDocumentRuntime(
     };
     cachedCompatibility = {
       revisionToken: nextState.revisionToken,
+      blockCount,
+      warningCount,
       warnings: nextState.warnings,
       fatalError: nextState.fatalError,
       report,
@@ -1424,8 +1563,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 +1600,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(
@@ -1772,19 +1952,37 @@ export function createDocumentRuntime(
         return scope;
       }
       const location = locations.get(scope.scopeId);
+      const isMarkerBacked = markerBackedScopeIds.has(scope.scopeId);
+      let nextAnchor: EditorAnchorProjection | null = null;
       if (
-        !location ||
-        location.startPos === undefined ||
-        location.endPos === undefined
+        location &&
+        location.startPos !== undefined &&
+        location.endPos !== undefined
       ) {
+        nextAnchor = {
+          kind: "range",
+          from: Math.min(location.startPos, location.endPos),
+          to: Math.max(location.startPos, location.endPos),
+          assoc: { start: -1, end: 1 },
+        };
+      } else if (isMarkerBacked) {
+        const lastKnownRange =
+          scope.anchor.kind === "range"
+            ? { from: scope.anchor.from, to: scope.anchor.to }
+            : scope.anchor.kind === "node"
+              ? { from: scope.anchor.at, to: scope.anchor.at }
+              : scope.anchor.lastKnownRange;
+        nextAnchor = {
+          kind: "detached",
+          reason:
+            location && (location.startPos !== undefined || location.endPos !== undefined)
+              ? "deleted"
+              : "invalidatedByStructureChange",
+          lastKnownRange,
+        };
+      } else {
         return scope;
       }
-      const nextAnchor: EditorAnchorProjection = {
-        kind: "range",
-        from: Math.min(location.startPos, location.endPos),
-        to: Math.max(location.startPos, location.endPos),
-        assoc: { start: -1, end: 1 },
-      };
       if (workflowAnchorsEqual(scope.anchor, nextAnchor)) {
         return scope;
       }
@@ -1814,6 +2012,161 @@ export function createDocumentRuntime(
     return normalizeWorkflowOverlayForDocument(state.document, workflowOverlay);
   }
 
+  function buildWarningSignature(warning: InternalEditorWarning): string {
+    return JSON.stringify({
+      code: warning.code,
+      severity: warning.severity,
+      message: warning.message,
+      source: warning.source,
+      featureEntryId: warning.featureEntryId ?? null,
+      details: warning.details ?? null,
+      affectedAnchor: warning.affectedAnchor ?? null,
+    });
+  }
+
+  function mergeDetachedWorkflowScopeWarnings(
+    overlay: WorkflowOverlay | null,
+    existingWarnings: readonly InternalEditorWarning[],
+  ): {
+    nextWarnings: InternalEditorWarning[];
+    added: InternalEditorWarning[];
+    cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+  } {
+    const detachedScopesById = new Map<string, WorkflowScope>();
+    for (const scope of overlay?.scopes ?? []) {
+      if (scope.anchor.kind === "detached") {
+        detachedScopesById.set(scope.scopeId, scope);
+      }
+    }
+
+    const retainedWarnings = existingWarnings.filter(
+      (warning) => warning.code !== "workflow_scope_invalidated",
+    );
+    const existingDetachedWarnings = existingWarnings.filter(
+      (warning) => warning.code === "workflow_scope_invalidated",
+    );
+    const existingById = new Map(
+      existingDetachedWarnings.map((warning) => [warning.warningId, warning] as const),
+    );
+    const desiredById = new Map(
+      [...detachedScopesById.values()].map((scope) => {
+        const warning = createInvalidatedWorkflowScopeWarning(scope);
+        return [warning.warningId, warning] as const;
+      }),
+    );
+
+    const added: InternalEditorWarning[] = [];
+    const cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }> = [];
+
+    for (const [warningId, existingWarning] of existingById) {
+      const desiredWarning = desiredById.get(warningId);
+      if (!desiredWarning) {
+        cleared.push({ warningId, code: existingWarning.code });
+        continue;
+      }
+      if (buildWarningSignature(existingWarning) !== buildWarningSignature(desiredWarning)) {
+        cleared.push({ warningId, code: existingWarning.code });
+        added.push(desiredWarning);
+      }
+    }
+
+    for (const [warningId, desiredWarning] of desiredById) {
+      if (!existingById.has(warningId)) {
+        added.push(desiredWarning);
+      }
+    }
+
+    return {
+      nextWarnings: [...retainedWarnings, ...desiredById.values()],
+      added,
+      cleared,
+    };
+  }
+
+  function createInvalidatedWorkflowScopeWarning(
+    scope: WorkflowScope,
+  ): InternalEditorWarning {
+    const anchor = scope.anchor.kind === "detached" ? scope.anchor : null;
+    const subject = scope.label
+      ? `Workflow scope "${scope.label}" (${scope.scopeId})`
+      : `Workflow scope ${scope.scopeId}`;
+    const reasonPhrase =
+      anchor?.reason === "deleted"
+        ? "its anchored text was deleted"
+        : anchor?.reason === "invalidatedByStructureChange"
+          ? "document structure changed around it"
+          : "its anchor could not be resolved unambiguously";
+    const modePhrase =
+      scope.mode === "view"
+        ? "read-only enforcement"
+        : `${scope.mode} enforcement`;
+
+    return {
+      warningId: `warning:workflow-scope-invalidated:${scope.scopeId}`,
+      code: "workflow_scope_invalidated",
+      severity: "warning",
+      message: `${subject} was invalidated because ${reasonPhrase}. Reapply the scope before relying on ${modePhrase}.`,
+      source: "runtime",
+      affectedAnchor: anchor ? toInternalAnchorProjection(anchor) : undefined,
+      diagnostic: buildDiagnosticFromLegacyWarningCode("workflow_scope_invalidated", {
+        diagnosticId: `warning-diag:workflow-scope-invalidated:${scope.scopeId}`,
+        technical: {
+          message: `${subject} lost its trusted anchor and is now detached.`,
+          source: "runtime",
+        },
+        details: {
+          scopeId: scope.scopeId,
+          label: scope.label,
+          mode: scope.mode,
+          reason: anchor?.reason,
+          lastKnownRange: anchor?.lastKnownRange,
+          storyTarget: scope.storyTarget,
+          reapplySuggested: true,
+        },
+        affectedAnchor: anchor ? scope.anchor : undefined,
+        llmMetadata: {
+          userSummary: `${subject} is no longer attached to trusted document content. Reapply the scope before relying on it.`,
+          remediation: {
+            kind: "fallback",
+            suggestion:
+              "Locate the intended text using warning.details.scopeId and warning.details.lastKnownRange, then call addScope again for the repaired range.",
+          },
+          recoveryClass: "requires-input",
+          echoedInput: {
+            scopeId: scope.scopeId,
+            lastKnownRange: anchor?.lastKnownRange,
+          },
+        },
+      }),
+      details: {
+        scopeId: scope.scopeId,
+        label: scope.label,
+        mode: scope.mode,
+        reason: anchor?.reason,
+        lastKnownRange: anchor?.lastKnownRange,
+        storyTarget: scope.storyTarget,
+        reapplySuggested: true,
+        actionabilityNote:
+          "Resolve the intended text again, then reapply the scope; the previous anchor is no longer trusted.",
+      },
+    };
+  }
+
+  function syncDetachedWorkflowScopeWarningsInState(): {
+    added: InternalEditorWarning[];
+    cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+  } {
+    const { nextWarnings, added, cleared } = mergeDetachedWorkflowScopeWarnings(
+      getNormalizedWorkflowOverlay(),
+      state.warnings,
+    );
+    if (added.length === 0 && cleared.length === 0) {
+      return { added, cleared };
+    }
+    state = { ...state, warnings: nextWarnings };
+    return { added, cleared };
+  }
+
   function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
     const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
     if (!normalizedWorkflowOverlay) return null;
@@ -1892,6 +2245,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 +2258,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 +2355,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 +2660,7 @@ export function createDocumentRuntime(
     cachedWorkflowScopeSnapshot = undefined;
     cachedNormalizedWorkflowOverlay = undefined;
     cachedWorkflowMarkupSnapshot = undefined;
+    cachedFieldSnapshotEntry = null;
     cachedContextAnalyticsSnapshots.clear();
     lastEmittedContextAnalyticsSnapshots = undefined;
   }
@@ -2313,8 +2677,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();
@@ -2363,6 +2730,7 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
+  syncDetachedWorkflowScopeWarningsInState();
   let cachedRenderSnapshot = refreshRenderSnapshot();
 
   emit({
@@ -2473,6 +2841,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 +3460,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 +3469,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({
@@ -3168,17 +3553,29 @@ export function createDocumentRuntime(
       });
 
       if (params.persistence && params.persistence !== "runtime-only") {
+        const requestedMetadata = params.metadata ?? {};
+        const entryPersistence =
+          requestedMetadata.metadataPersistence ??
+          (params.persistence === "session" ? "external" : "internal");
         const entry: WorkflowMetadataEntry = {
-          entryId: `scope-metadata-${scopeId}`,
-          metadataId: "workflow.scope",
+          entryId: requestedMetadata.entryId ?? `scope-metadata-${scopeId}`,
+          metadataId: requestedMetadata.metadataId ?? "workflow.scope",
           anchor: publicAnchor,
+          ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
           scopeId,
-          value:
-            params.persistence === "document-metadata"
-              ? { ...(params.metadata?.value ?? {}), label: params.label }
-              : params.metadata?.value,
-          metadataPersistence:
-            params.persistence === "session" ? "external" : "internal",
+          ...(requestedMetadata.workItemId ? { workItemId: requestedMetadata.workItemId } : {}),
+          ...(requestedMetadata.value !== undefined
+            ? { value: requestedMetadata.value }
+            : params.persistence === "document-metadata" && params.label
+              ? { value: { label: params.label } }
+              : {}),
+          metadataPersistence: entryPersistence,
+          ...(requestedMetadata.storageRef !== undefined
+            ? { storageRef: requestedMetadata.storageRef }
+            : {}),
+          ...(requestedMetadata.metadataVersion !== undefined
+            ? { metadataVersion: requestedMetadata.metadataVersion }
+            : {}),
         };
         this.dispatch({
           type: "workflow.set-metadata-entries",
@@ -3250,6 +3647,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 +3811,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 +3962,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,
@@ -3729,10 +4165,98 @@ export function createDocumentRuntime(
           overlay: workflowOverlay,
           entries: workflowMetadataEntries,
           document: state.document,
+          markerBackedScopeIds,
         },
         filter,
       );
     },
+    subscribeToScopeQuery(filter, callback) {
+      const buildAnchorKey = (anchor: EditorAnchorProjection): string => {
+        switch (anchor.kind) {
+          case "range":
+            return `range:${anchor.from}:${anchor.to}:${anchor.assoc.start}:${anchor.assoc.end}`;
+          case "node":
+            return `node:${anchor.at}`;
+          case "detached":
+            return `detached:${anchor.reason}:${anchor.lastKnownRange.from}:${anchor.lastKnownRange.to}`;
+          default:
+            return "unknown";
+        }
+      };
+
+      const buildKey = (results: ScopeQueryResult[]) =>
+        results
+          .map(
+            (r) =>
+              [
+                r.scope.scopeId,
+                r.scope.version ?? 0,
+                r.scope.visibility ?? "visible",
+                buildAnchorKey(r.scope.anchor),
+                r.workItem?.workItemId ?? "",
+                r.entries
+                  .map(
+                    (entry) =>
+                      `${entry.entryId}:${entry.metadataVersion ?? 0}:${buildAnchorKey(entry.anchor)}`,
+                  )
+                  .join("|"),
+              ].join(":"),
+          )
+          .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"
@@ -3743,7 +4267,12 @@ export function createDocumentRuntime(
       if (pos === null) return [];
       const hits = findAllScopesAt(state.document, pos);
       return projectScopeQueryResults(
-        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        {
+          overlay: workflowOverlay,
+          entries: workflowMetadataEntries,
+          document: state.document,
+          markerBackedScopeIds,
+        },
         hits.map((h) => h.scopeId),
         options,
       );
@@ -3752,7 +4281,12 @@ export function createDocumentRuntime(
       if (range.kind !== "range") return [];
       const hits = findScopesIntersecting(state.document, range.from, range.to, options?.mode);
       return projectScopeQueryResults(
-        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        {
+          overlay: workflowOverlay,
+          entries: workflowMetadataEntries,
+          document: state.document,
+          markerBackedScopeIds,
+        },
         hits.map((h) => h.scopeId),
         options,
       );
@@ -3925,6 +4459,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();
@@ -3933,6 +4499,8 @@ export function createDocumentRuntime(
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     perfCounters.increment("commit.finalizeState.us", Math.round((performance.now() - tFinalize0) * 1000));
     storySelections.set(storyTargetKey(activeStory), state.selection);
+    syncMarkerBackedScopeIds(state.document, workflowOverlay);
+    const detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
 
     const tInvalidate0 = performance.now();
     if (transaction.markDirty && transaction.mapping.steps.length > 0) {
@@ -3948,8 +4516,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 +4550,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 };
@@ -3994,7 +4571,20 @@ export function createDocumentRuntime(
     perfCounters.increment("commit.refresh.us", Math.round((performance.now() - tRefresh0) * 1000));
 
     const tNotify0 = performance.now();
-    notify(previous, state, transaction);
+    notify(previous, state, {
+      ...transaction,
+      effects: {
+        ...transaction.effects,
+        warningsAdded: [
+          ...transaction.effects.warningsAdded,
+          ...detachedWorkflowScopeWarnings.added,
+        ],
+        warningsCleared: [
+          ...transaction.effects.warningsCleared,
+          ...detachedWorkflowScopeWarnings.cleared,
+        ],
+      },
+    });
     perfCounters.increment("commit.notify.us", Math.round((performance.now() - tNotify0) * 1000));
     perfCounters.increment("commit.total.us", Math.round((performance.now() - tApply0) * 1000));
   }
@@ -4184,6 +4774,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 +5040,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,
@@ -4599,10 +5213,18 @@ export function createDocumentRuntime(
   function applyRuntimeStateOverlayCommand(
     command: RuntimeStateOverlayCommand,
   ): void {
+    let detachedWorkflowScopeWarnings:
+      | {
+          added: InternalEditorWarning[];
+          cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+        }
+      | null = null;
     switch (command.type) {
       case "workflow.set-overlay": {
         workflowOverlay = structuredClone(command.overlay);
+        syncMarkerBackedScopeIds(state.document, workflowOverlay);
         cachedNormalizedWorkflowOverlay = undefined;
+        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
         cachedRenderSnapshot = refreshRenderSnapshot();
         const snapshot = deriveWorkflowScopeSnapshot()!;
         emit({
@@ -4621,7 +5243,9 @@ export function createDocumentRuntime(
       }
       case "workflow.clear-overlay": {
         workflowOverlay = null;
+        syncMarkerBackedScopeIds(state.document, workflowOverlay);
         cachedNormalizedWorkflowOverlay = undefined;
+        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
         cachedRenderSnapshot = refreshRenderSnapshot();
         emit({
           type: "workflow_active_work_item_changed",
@@ -4696,6 +5320,25 @@ export function createDocumentRuntime(
         break;
       }
     }
+    if (detachedWorkflowScopeWarnings) {
+      for (const warning of detachedWorkflowScopeWarnings.added) {
+        const publicWarning = toPublicWarning(warning);
+        emit({
+          type: "warning_added",
+          documentId: state.documentId,
+          warning: publicWarning,
+        });
+        options.onWarning?.(publicWarning);
+      }
+      for (const cleared of detachedWorkflowScopeWarnings.cleared) {
+        emit({
+          type: "warning_cleared",
+          documentId: state.documentId,
+          warningId: cleared.warningId,
+          code: cleared.code,
+        });
+      }
+    }
     for (const listener of listeners) {
       listener();
     }
@@ -4979,7 +5622,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 +5726,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 +5741,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 {
@@ -5124,11 +5827,42 @@ function toPublicCompatibilityFeatureEntry(
 }
 
 function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
+  const diagnostic =
+    warning.diagnostic ??
+    (() => {
+      switch (warning.code) {
+        case "unsupported_ooxml_preserved":
+        case "unsupported_ooxml_locked":
+        case "import_normalized":
+        case "export_roundtrip_risk":
+        case "comment_anchor_detached":
+        case "revision_anchor_detached":
+        case "workflow_scope_invalidated":
+        case "large_document_degraded":
+        case "font_substitution":
+        case "image_missing":
+          return buildDiagnosticFromLegacyWarningCode(warning.code, {
+            diagnosticId: `warning-diag:${warning.warningId}`,
+            emittedAt: new Date(0).toISOString(),
+            technical: {
+              message: warning.message,
+              source: warning.source,
+            },
+            details: warning.details,
+            affectedAnchor: warning.affectedAnchor
+              ? toPublicAnchorProjection(warning.affectedAnchor)
+              : undefined,
+          });
+        default:
+          return undefined;
+      }
+    })();
   return {
     ...warning,
     affectedAnchor: warning.affectedAnchor
       ? toPublicAnchorProjection(warning.affectedAnchor)
       : undefined,
+    diagnostic,
   };
 }
 
@@ -5510,6 +6244,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 +6276,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 +7379,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 +7442,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