@beyondwork/docx-react-component 1.0.86 → 1.0.88

package/src/runtime/document-runtime.ts

@@ -124,6 +124,7 @@ import {
   MAIN_STORY_TARGET,
   storyTargetsEqual,
   type EditorAnchorProjection as InternalEditorAnchorProjection,
+  type TransactionMapping,
 } from "../core/selection/mapping.ts";
 import {
   toInternalAnchorProjection,
@@ -291,6 +292,7 @@ import type {
   ParagraphNode,
   SectionProperties,
   SubPartsCatalog,
+  TocRegion,
 } from "../model/canonical-document.ts";
 import {
   isSupportedFieldFamily,
@@ -1173,6 +1175,8 @@ export function createDocumentRuntime(
   // to a single microtask-deferred emit. Declared early because emit() (which
   // checks this flag) runs during construction.
   let analyticsEmitScheduled = false;
+  let analyticsEmitScheduleMode: "none" | "microtask" | "idle" = "none";
+  let deferNextContextAnalyticsEmit = false;
 
   // V6c — heading fingerprint for TOC auto-invalidation. Compared in notify();
   // a mismatch schedules a microtask refresh of TOC fields.
@@ -1379,6 +1383,8 @@ export function createDocumentRuntime(
   let viewportBlockRanges: readonly { start: number; end: number }[] | null = null;
   /** Serialized fingerprint of the active ranges — used as the idempotency key for `refreshSurfaceOnly`. */
   let viewportRangesKey: string = serializeViewportRanges(null);
+  const EDITING_CORRIDOR_BLOCK_RADIUS = 8;
+  const EDITING_CORRIDOR_MIN_BLOCKS = 24;
 
   function applyViewportRanges(
     incoming: readonly { start: number; end: number }[] | null,
@@ -1566,19 +1572,35 @@ export function createDocumentRuntime(
   function getCachedSurface(
     document: CanonicalDocumentEnvelope,
     nextActiveStory: EditorStoryTarget,
+    options: {
+      viewportBlockRangesOverride?: readonly { start: number; end: number }[] | null;
+      enrichCulledPlaceholders?: boolean;
+    } = {},
   ): RuntimeRenderSnapshot["surface"] {
     const activeStoryKey = storyTargetKey(nextActiveStory);
+    const surfaceViewportRanges =
+      "viewportBlockRangesOverride" in options
+        ? options.viewportBlockRangesOverride ?? null
+        : viewportBlockRanges;
+    const surfaceViewportRangesKey =
+      "viewportBlockRangesOverride" in options
+        ? serializeViewportRanges(surfaceViewportRanges)
+        : viewportRangesKey;
+    const surfaceCacheKey =
+      options.enrichCulledPlaceholders === false
+        ? `${surfaceViewportRangesKey}|raw-placeholders`
+        : surfaceViewportRangesKey;
     if (
       cachedSurface &&
       cachedSurface.revisionToken === state.revisionToken &&
       cachedSurface.activeStoryKey === activeStoryKey &&
-      cachedSurface.viewportRangesKey === viewportRangesKey
+      cachedSurface.viewportRangesKey === surfaceCacheKey
     ) {
       return cachedSurface.snapshot;
     }
 
     const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, {
-      viewportBlockRanges,
+      viewportBlockRanges: surfaceViewportRanges,
       ...(effectiveMarkupModeProvider
         ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
         : {}),
@@ -1604,20 +1626,57 @@ export function createDocumentRuntime(
     //
     // No-op on pre-pagination calls (engine not yet ready → empty map)
     // and on the inert facet.
-    const enrichedSnapshot = enrichCulledPlaceholdersWithHeights(snapshot);
+    const enrichedSnapshot =
+      options.enrichCulledPlaceholders === false
+        ? snapshot
+        : enrichCulledPlaceholdersWithHeights(snapshot);
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey,
-      viewportRangesKey,
+      viewportRangesKey: surfaceCacheKey,
       snapshot: enrichedSnapshot,
     };
     // Keep the scroll-path fingerprint in lockstep so a subsequent
     // `maybeRefreshSurfaceForViewport` sees the freshly-built snapshot
     // and short-circuits instead of paying a redundant projection.
-    cachedSurfaceFingerprint = `${state.revisionToken}|${activeStoryKey}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
+    cachedSurfaceFingerprint = `${state.revisionToken}|${activeStoryKey}|${surfaceCacheKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     return enrichedSnapshot;
   }
 
+  function getLocalTextCommitViewportRanges(
+    previousSurface: RuntimeRenderSnapshot["surface"] | undefined,
+  ): readonly { start: number; end: number }[] | null {
+    if (!previousSurface || previousSurface.blocks.length < EDITING_CORRIDOR_MIN_BLOCKS) {
+      return viewportBlockRanges;
+    }
+    const caretBlockIndex = findSurfaceBlockIndexForSelection(previousSurface, state.selection);
+    if (caretBlockIndex === -1) {
+      return viewportBlockRanges;
+    }
+    const corridor = {
+      start: Math.max(0, caretBlockIndex - EDITING_CORRIDOR_BLOCK_RADIUS),
+      end: Math.min(previousSurface.blocks.length, caretBlockIndex + EDITING_CORRIDOR_BLOCK_RADIUS + 1),
+    };
+    return normalizeViewportRanges([...(viewportBlockRanges ?? []), corridor]);
+  }
+
+  function findSurfaceBlockIndexForSelection(
+    surface: RuntimeRenderSnapshot["surface"],
+    selection: EditorState["selection"],
+  ): number {
+    if (!surface) return -1;
+    const from = Math.min(selection.anchor, selection.head);
+    const to = Math.max(selection.anchor, selection.head);
+    for (let index = 0; index < surface.blocks.length; index += 1) {
+      const block = surface.blocks[index];
+      if (!block) continue;
+      if (to >= block.from && from <= block.to) {
+        return index;
+      }
+    }
+    return -1;
+  }
+
   function enrichCulledPlaceholdersWithHeights(
     snapshot: EditorSurfaceSnapshot,
   ): EditorSurfaceSnapshot {
@@ -2468,6 +2527,57 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
+  function refreshLocalTextCommitSnapshot(
+    surface: RuntimeRenderSnapshot["surface"],
+    mapping: TransactionMapping,
+  ): RuntimeRenderSnapshot {
+    perfCounters.increment("refresh.localTextEquivalent");
+    return {
+      ...cachedRenderSnapshot,
+      documentId: state.documentId,
+      sessionId: state.sessionId,
+      sourceLabel: state.sourceLabel,
+      revisionToken: state.revisionToken,
+      isReady: state.phase === "ready",
+      isDirty: state.isDirty,
+      readOnly: state.readOnly,
+      documentMode: viewState.documentMode,
+      selection: toPublicSelectionSnapshot(state.selection, activeStory),
+      activeStory,
+      documentStats: updateDocumentStatsForLocalTextCommit(
+        cachedRenderSnapshot.documentStats,
+        mapping,
+      ),
+      warnings: cachedRenderSnapshot.warnings,
+      fatalError: state.fatalError ? toPublicError(state.fatalError) : undefined,
+      commandState: {
+        canUndo: history.past.length > 0,
+        canRedo: history.future.length > 0,
+        readOnly: state.readOnly,
+      },
+      surface,
+      protectionSnapshot,
+      grabbedObjectId: grabState.objectId,
+    };
+  }
+
+  function updateDocumentStatsForLocalTextCommit(
+    previousStats: RuntimeRenderSnapshot["documentStats"],
+    mapping: TransactionMapping,
+  ): RuntimeRenderSnapshot["documentStats"] {
+    if (!previousStats) {
+      return toPublicDocumentStats(state);
+    }
+    let delta = 0;
+    for (const step of mapping.steps) {
+      delta += step.insertSize - Math.max(0, step.to - step.from);
+    }
+    return {
+      ...previousStats,
+      storyLength: Math.max(0, previousStats.storyLength + delta),
+    };
+  }
+
   /**
    * Fingerprint over the inputs that the viewport-refresh fast-path knows
    * about. Used to short-circuit {@link maybeRefreshSurfaceForViewport}
@@ -3565,6 +3675,7 @@ export function createDocumentRuntime(
         emitError(runtimeError);
         return {
           kind: "rejected",
+          refreshClass: "blocked",
           opId: (command.origin as { opId?: string } | undefined)?.opId,
           newRevisionToken: "",
           blockedReasons: [
@@ -4890,14 +5001,52 @@ export function createDocumentRuntime(
       history.future = [];
     }
 
-    applyTransactionToState(transaction);
+    applyTransactionToState(transaction, { allowLocalTextFastPath: true });
   }
 
   function commitRemote(transaction: EditorTransaction): void {
     applyTransactionToState(transaction);
   }
 
-  function applyTransactionToState(transaction: EditorTransaction): void {
+  function shouldUseLocalTextCommitSnapshot(
+    previous: EditorState,
+    next: EditorState,
+    transaction: EditorTransaction,
+    effects: EditorTransaction["effects"],
+  ): boolean {
+    if (activeStory.kind !== "main") return false;
+    if (!transaction.markDirty || transaction.mapping.steps.length === 0) {
+      return false;
+    }
+    if (transaction.mapping.metadata?.invalidatesStructures) {
+      return false;
+    }
+    if (previous.document.subParts !== next.document.subParts) {
+      return false;
+    }
+    if (effects.warningsAdded.length > 0 || effects.warningsCleared.length > 0) {
+      return false;
+    }
+    if ((effects.transientWarnings?.length ?? 0) > 0) {
+      return false;
+    }
+    return (
+      !effects.commentAdded &&
+      !effects.commentResolved &&
+      !effects.commentReopened &&
+      !effects.commentReplyAdded &&
+      !effects.commentBodyEdited &&
+      !effects.changeAccepted &&
+      !effects.changeRejected &&
+      !effects.revisionAuthored &&
+      !effects.commandBlocked
+    );
+  }
+
+  function applyTransactionToState(
+    transaction: EditorTransaction,
+    options: { allowLocalTextFastPath?: boolean } = {},
+  ): 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.
@@ -4939,7 +5088,9 @@ export function createDocumentRuntime(
     const previous = state;
 
     const tApply0 = performance.now();
+    const tProtection0 = performance.now();
     protectionSnapshot = remapProtectionSnapshot(protectionSnapshot, transaction.mapping);
+    perfCounters.increment("commit.protectionRemap.us", Math.round((performance.now() - tProtection0) * 1000));
     const tFinalize0 = performance.now();
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     perfCounters.increment("commit.finalizeState.us", Math.round((performance.now() - tFinalize0) * 1000));
@@ -4947,8 +5098,10 @@ export function createDocumentRuntime(
     // Re-sync marker-backed scope IDs against the new document; the
     // store handles set computation + telemetry. `replaceOverlay(current, doc)`
     // is idempotent on state and re-derives the marker-backed set.
+    const tOverlay0 = performance.now();
     overlayStore.replaceOverlay(overlayStore.getOverlay(), state.document);
     const detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
+    perfCounters.increment("commit.overlaySync.us", Math.round((performance.now() - tOverlay0) * 1000));
 
     const tInvalidate0 = performance.now();
     if (transaction.markDirty && transaction.mapping.steps.length > 0) {
@@ -4972,12 +5125,37 @@ export function createDocumentRuntime(
     }
     perfCounters.increment("commit.invalidate.us", Math.round((performance.now() - tInvalidate0) * 1000));
 
+    const notifyEffects: EditorTransaction["effects"] = {
+      ...transaction.effects,
+      warningsAdded: [
+        ...transaction.effects.warningsAdded,
+        ...detachedWorkflowScopeWarnings.added,
+      ],
+      warningsCleared: [
+        ...transaction.effects.warningsCleared,
+        ...detachedWorkflowScopeWarnings.cleared,
+      ],
+    };
+
+    const tClassify0 = performance.now();
+    const useLocalTextCommitSnapshot =
+      options.allowLocalTextFastPath === true &&
+      shouldUseLocalTextCommitSnapshot(
+        previous,
+        state,
+        transaction,
+        notifyEffects,
+      );
+    perfCounters.increment("commit.refreshClassify.us", Math.round((performance.now() - tClassify0) * 1000));
+
     // I5: validate post-mutation selection against the new document bound.
     // First call to getCachedSurface() here computes the post-mutation surface
     // snapshot (cache miss — revisionToken just changed in finalizeState).
-    // refreshRenderSnapshot's internal call below hits the cache and reuses it.
-    // Net cost: identical to pre-I5 — one surface walk per commit, just shifted
-    // a few lines earlier so the validator can read storySize.
+    // For local text commits, this is an editing-corridor surface (current
+    // block plus a small halo) so the immediate typing path keeps visible
+    // truth hot without rebuilding offscreen table/comment markup. Structural,
+    // review, and warning commits still use the full current viewport surface
+    // and fall back to refreshRenderSnapshot().
     //
     // Wired ONLY at this chokepoint. The other 12 `cachedRenderSnapshot =
     // refreshRenderSnapshot()` sites in this file are intentionally skipped:
@@ -4997,7 +5175,13 @@ export function createDocumentRuntime(
     // The return type of getCachedSurface is `RuntimeRenderSnapshot["surface"]`
     // 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 tValidation0 = performance.now();
+    const surfaceForValidation = useLocalTextCommitSnapshot
+      ? getCachedSurface(state.document, activeStory, {
+          viewportBlockRangesOverride: getLocalTextCommitViewportRanges(cachedRenderSnapshot.surface),
+          enrichCulledPlaceholders: false,
+        })!
+      : getCachedSurface(state.document, activeStory)!;
     const validationOptions = state.selection.activeRange.kind === "node"
       ? {
           isValidNodeTarget: createSurfaceNodeSelectionProbe(surfaceForValidation),
@@ -5013,26 +5197,24 @@ export function createDocumentRuntime(
       state = { ...state, selection: validatedSelection };
       storySelections.set(storyTargetKey(activeStory), state.selection);
     }
+    perfCounters.increment("commit.selectionValidation.us", Math.round((performance.now() - tValidation0) * 1000));
 
     const tRefresh0 = performance.now();
-    cachedRenderSnapshot = refreshRenderSnapshot();
+    cachedRenderSnapshot = useLocalTextCommitSnapshot
+      ? refreshLocalTextCommitSnapshot(surfaceForValidation, transaction.mapping)
+      : refreshRenderSnapshot();
     perfCounters.increment("commit.refresh.us", Math.round((performance.now() - tRefresh0) * 1000));
 
     const tNotify0 = performance.now();
-    notify(previous, state, {
-      ...transaction,
-      effects: {
-        ...transaction.effects,
-        warningsAdded: [
-          ...transaction.effects.warningsAdded,
-          ...detachedWorkflowScopeWarnings.added,
-        ],
-        warningsCleared: [
-          ...transaction.effects.warningsCleared,
-          ...detachedWorkflowScopeWarnings.cleared,
-        ],
-      },
-    });
+    deferNextContextAnalyticsEmit = useLocalTextCommitSnapshot;
+    try {
+      notify(previous, state, {
+        ...transaction,
+        effects: notifyEffects,
+      });
+    } finally {
+      deferNextContextAnalyticsEmit = false;
+    }
     perfCounters.increment("commit.notify.us", Math.round((performance.now() - tNotify0) * 1000));
     perfCounters.increment("commit.total.us", Math.round((performance.now() - tApply0) * 1000));
     emitStageToken(telemetryBus, "commit", "commit.apply.complete", {
@@ -5319,6 +5501,7 @@ export function createDocumentRuntime(
       });
       return completeDispatch({
         kind: "rejected",
+        refreshClass: "blocked",
         opId,
         newRevisionToken: "",
         blockedReasons: [{ code: "suggesting_unsupported", message }],
@@ -5335,6 +5518,7 @@ export function createDocumentRuntime(
         });
         return completeDispatch({
           kind: "rejected",
+          refreshClass: "blocked",
           opId,
           newRevisionToken: "",
           blockedReasons: blockedReasons.map((r) => ({ code: r.code, message: r.message })),
@@ -5408,6 +5592,7 @@ export function createDocumentRuntime(
       });
       return completeDispatch({
         kind: "equivalent",
+        refreshClass: "local-text-equivalent",
         opId,
         newRevisionToken: state.revisionToken,
       });
@@ -5475,6 +5660,7 @@ export function createDocumentRuntime(
     if (meta.invalidatesStructures) {
       return {
         kind: "structural-divergence",
+        refreshClass: "full-projection",
         opId,
         newRevisionToken,
         scopeTagTouches: touches,
@@ -5499,6 +5685,7 @@ export function createDocumentRuntime(
       const adjustedRange = computeAdjustedRange(priorState, transaction);
       return {
         kind: "adjusted",
+        refreshClass: "surface-only",
         opId,
         newRevisionToken,
         adjustedRange,
@@ -5508,6 +5695,7 @@ export function createDocumentRuntime(
 
     return {
       kind: "equivalent",
+      refreshClass: "local-text-equivalent",
       opId,
       newRevisionToken,
       scopeTagTouches: touches,
@@ -5600,23 +5788,58 @@ export function createDocumentRuntime(
   // synchronous call stack — one per commit. (Flag declared above near
   // perfCounters so it is initialized before construction-time emits run.)
   function scheduleContextAnalyticsEmit(): void {
+    const shouldDefer = deferNextContextAnalyticsEmit;
+    deferNextContextAnalyticsEmit = false;
     if (analyticsEmitScheduled) {
+      if (shouldDefer && analyticsEmitScheduleMode === "microtask") {
+        analyticsEmitScheduleMode = "idle";
+        perfCounters.increment("emit.contextAnalytics.deferred");
+        return;
+      }
       perfCounters.increment("emit.contextAnalytics.coalesced");
       return;
     }
     analyticsEmitScheduled = true;
-    queueMicrotask(() => {
+    analyticsEmitScheduleMode = shouldDefer ? "idle" : "microtask";
+    const run = () => {
       // Reset BEFORE the emit so any synchronous re-entrant emits triggered
       // by listener callbacks schedule a fresh second microtask (no lost
       // updates). Reversing this order would drop bursts originating in
       // listeners.
       analyticsEmitScheduled = false;
+      analyticsEmitScheduleMode = "none";
       const t = performance.now();
       emitContextAnalyticsChanged();
       perfCounters.increment("emit.contextAnalytics.us", Math.round((performance.now() - t) * 1000));
+    };
+    if (shouldDefer) {
+      perfCounters.increment("emit.contextAnalytics.deferred");
+      scheduleIdleContextAnalytics(run);
+      return;
+    }
+    queueMicrotask(() => {
+      if (analyticsEmitScheduleMode === "idle") {
+        scheduleIdleContextAnalytics(run);
+        return;
+      }
+      run();
     });
   }
 
+  function scheduleIdleContextAnalytics(callback: () => void): void {
+    const requestIdle = (globalThis as {
+      requestIdleCallback?: (
+        cb: () => void,
+        options?: { timeout?: number },
+      ) => number;
+    }).requestIdleCallback;
+    if (typeof requestIdle === "function") {
+      requestIdle(callback, { timeout: 250 });
+      return;
+    }
+    setTimeout(callback, 0);
+  }
+
   // V6c — TOC auto-refresh scheduler. Mirrors scheduleContextAnalyticsEmit's
   // microtask-coalesce shape. Bursts of heading edits within one synchronous
   // call stack collapse to a single rebuild + a single toc_auto_refreshed
@@ -5685,6 +5908,10 @@ export function createDocumentRuntime(
       emit({
         type: "toc_auto_refreshed",
         documentId: state.documentId,
+        ...(refreshed.result.tocId ? { tocId: refreshed.result.tocId } : {}),
+        ...(refreshed.document.fieldRegistry?.tocRegions
+          ? { regionCount: refreshed.document.fieldRegistry.tocRegions.length }
+          : {}),
         entryCount: refreshed.result.entryCount,
         trigger: flushedTrigger,
       });
@@ -7161,6 +7388,29 @@ function refreshDocumentTableOfContents(
   changed: boolean;
   protectionSelection?: import("../core/state/editor-state.ts").SelectionSnapshot;
 } {
+  const selectedRegion = selectTocRegion(document.fieldRegistry?.tocRegions, options?.tocId);
+  const refreshMode = options?.mode ?? "regenerate";
+  if (refreshMode === "preserveCached") {
+    const cachedEntries = selectedRegion?.cachedEntries ?? [];
+    return {
+      document,
+      result: {
+        ...(selectedRegion ? { tocId: selectedRegion.tocId } : {}),
+        mode: "preserveCached",
+        status: selectedRegion?.status ?? (cachedEntries.length > 0 ? "stale" : "missing"),
+        entryCount: cachedEntries.length,
+        entries: cachedEntries.map((entry) => ({
+          level: entry.level,
+          text: entry.text,
+          pageIndex: tocPageTextToPageIndex(entry.pageText),
+          ...(entry.pageText ? { pageText: entry.pageText } : {}),
+          source: "cached",
+        })),
+      },
+      changed: false,
+    };
+  }
+
   const navigation = createDocumentNavigationSnapshot(document, selectionHead, activeStory);
   // Build a single O(N) map from paragraph offset → bookmark name so the
   // per-heading lookup below is O(1) instead of O(N) per heading.
@@ -7189,16 +7439,16 @@ function refreshDocumentTableOfContents(
     }
   }
   let changed = false;
-  let resultEntries: Array<{ level: number; text: string; pageIndex: number; bookmarkName?: string }> = [];
+  let resultEntries: RuntimeTocEntry[] = [];
   let changedFrom: number | undefined;
   let changedTo: number | undefined;
-  const nextChildren = refreshBlocksWithCursor(document.content.children, (field, range) => {
-    if (field.fieldFamily !== "TOC") {
-      return field;
-    }
+
+  const buildEntriesForField = (field: FieldNode): RuntimeTocEntry[] => {
     const levelRange = options?.maxLevel
       ? { from: 1, to: options.maxLevel }
-      : parseTocLevelRange(field.instruction);
+      : selectedRegion && normalizeTocInstruction(selectedRegion.instruction.raw) === normalizeTocInstruction(field.instruction)
+        ? selectedRegion.instruction.outlineRange
+        : parseTocLevelRange(field.instruction);
     const entries = navigation.headings
       .filter((heading) => heading.level >= levelRange.from && heading.level <= levelRange.to)
       .map((heading) => {
@@ -7213,6 +7463,30 @@ function refreshDocumentTableOfContents(
     if (resultEntries.length === 0) {
       resultEntries = entries;
     }
+    return entries;
+  };
+
+  const tocRangeRefresh = refreshTocBlockRanges(
+    document.content.children,
+    buildEntriesForField,
+    resolveDisplayPageNumber,
+    selectedRegion,
+  );
+  if (tocRangeRefresh.changed) {
+    changed = true;
+  }
+
+  const nextChildren = refreshBlocksWithCursor(tocRangeRefresh.blocks, (field, range) => {
+    if (field.fieldFamily !== "TOC") {
+      return field;
+    }
+    if (selectedRegion && normalizeTocInstruction(field.instruction) !== normalizeTocInstruction(selectedRegion.instruction.raw)) {
+      return field;
+    }
+    if (field.refreshStatus === "current" && field.children.length === 0) {
+      return field;
+    }
+    const entries = buildEntriesForField(field);
     const nextField: FieldNode = {
       ...field,
       children: buildTocInlineNodes(entries, resolveDisplayPageNumber),
@@ -7228,7 +7502,7 @@ function refreshDocumentTableOfContents(
   if (!changed) {
     return {
       document,
-      result: { entryCount: resultEntries.length, entries: resultEntries },
+      result: buildTocRefreshResult(selectedRegion, "regenerate", resultEntries, "current"),
       changed: false,
     };
   }
@@ -7245,13 +7519,24 @@ function refreshDocumentTableOfContents(
     styles: nextDocument.styles,
     subParts: nextDocument.subParts,
   });
-  nextDocument.fieldRegistry = nextRegistry.tocStructure
+  const nextTocRegions = nextRegistry.tocRegions?.map((region) => {
+    if (!selectedRegion || normalizeTocInstruction(region.instruction.raw) === normalizeTocInstruction(selectedRegion.instruction.raw)) {
+      return { ...region, status: "current" as const };
+    }
+    return region;
+  });
+  nextDocument.fieldRegistry = nextRegistry.tocStructure || nextTocRegions
     ? {
         ...nextRegistry,
-        tocStructure: {
-          ...nextRegistry.tocStructure,
-          status: "current",
-        },
+        ...(nextTocRegions ? { tocRegions: nextTocRegions } : {}),
+        ...(nextRegistry.tocStructure
+          ? {
+              tocStructure: {
+                ...nextRegistry.tocStructure,
+                status: "current",
+              },
+            }
+          : {}),
       }
     : nextRegistry;
   let protectionSelection:
@@ -7263,12 +7548,267 @@ function refreshDocumentTableOfContents(
 
   return {
     document: nextDocument,
-    result: { entryCount: resultEntries.length, entries: resultEntries },
+    result: buildTocRefreshResult(selectedRegion, "regenerate", resultEntries, "current"),
     changed: true,
     ...(protectionSelection ? { protectionSelection } : {}),
   };
 }
 
+type RuntimeTocEntry = {
+  level: number;
+  text: string;
+  pageIndex: number;
+  bookmarkName?: string;
+};
+
+function selectTocRegion(
+  regions: readonly TocRegion[] | undefined,
+  tocId: string | undefined,
+): TocRegion | undefined {
+  if (!regions || regions.length === 0) {
+    return undefined;
+  }
+  if (!tocId) {
+    return regions[0];
+  }
+  return regions.find((region) => region.tocId === tocId);
+}
+
+function buildTocRefreshResult(
+  region: TocRegion | undefined,
+  mode: "preserveCached" | "regenerate",
+  entries: readonly RuntimeTocEntry[],
+  status: "current" | "stale" | "missing",
+): TocRefreshResult {
+  return {
+    ...(region ? { tocId: region.tocId } : {}),
+    mode,
+    status,
+    entryCount: entries.length,
+    entries: entries.map((entry) => ({
+      level: entry.level,
+      text: entry.text,
+      pageIndex: entry.pageIndex,
+      source: "generated",
+    })),
+  };
+}
+
+function tocPageTextToPageIndex(pageText: string | undefined): number {
+  const value = Number.parseInt(pageText ?? "", 10);
+  return Number.isFinite(value) && value > 0 ? value - 1 : 0;
+}
+
+function normalizeTocInstruction(instruction: string): string {
+  return instruction.replace(/\s+/gu, " ").trim();
+}
+
+function refreshTocBlockRanges(
+  blocks: readonly BlockNode[],
+  buildEntriesForField: (field: FieldNode) => RuntimeTocEntry[],
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
+  selectedRegion?: TocRegion,
+): { blocks: BlockNode[]; changed: boolean } {
+  const nextBlocks: BlockNode[] = [];
+  let changed = false;
+
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index];
+
+    if (block.type === "paragraph") {
+      const tocField = findTocFieldNode(block);
+      if (
+        tocField &&
+        (!selectedRegion || normalizeTocInstruction(tocField.instruction) === normalizeTocInstruction(selectedRegion.instruction.raw)) &&
+        startsTocParagraphRegion(blocks, index)
+      ) {
+        const endIndex = findTocParagraphRegionEnd(blocks, index);
+        const region = blocks.slice(index, endIndex + 1).filter(
+          (candidate): candidate is ParagraphNode => candidate.type === "paragraph",
+        );
+        const replacement = buildTocRegionParagraphs(
+          region,
+          tocField,
+          buildEntriesForField(tocField),
+          resolveDisplayPageNumber,
+        );
+        if (tocRegionSignature(region) !== tocRegionSignature(replacement)) {
+          changed = true;
+        }
+        nextBlocks.push(...replacement);
+        index = endIndex;
+        continue;
+      }
+      nextBlocks.push(block);
+      continue;
+    }
+
+    if (block.type === "sdt" || block.type === "custom_xml") {
+      const refreshed = refreshTocBlockRanges(
+        block.children,
+        buildEntriesForField,
+        resolveDisplayPageNumber,
+        selectedRegion,
+      );
+      if (refreshed.changed) {
+        changed = true;
+        nextBlocks.push({ ...block, children: refreshed.blocks });
+      } else {
+        nextBlocks.push(block);
+      }
+      continue;
+    }
+
+    if (block.type === "table") {
+      let tableChanged = false;
+      const rows = block.rows.map((row) => {
+        let rowChanged = false;
+        const cells = row.cells.map((cell) => {
+          const refreshed = refreshTocBlockRanges(
+            cell.children,
+            buildEntriesForField,
+            resolveDisplayPageNumber,
+            selectedRegion,
+          );
+          if (!refreshed.changed) {
+            return cell;
+          }
+          tableChanged = true;
+          rowChanged = true;
+          return { ...cell, children: refreshed.blocks };
+        });
+        return rowChanged ? { ...row, cells } : row;
+      });
+      nextBlocks.push(tableChanged ? { ...block, rows } : block);
+      changed = changed || tableChanged;
+      continue;
+    }
+
+    nextBlocks.push(block);
+  }
+
+  return { blocks: nextBlocks, changed };
+}
+
+function startsTocParagraphRegion(blocks: readonly BlockNode[], index: number): boolean {
+  const current = blocks[index];
+  if (current?.type === "paragraph" && isTocParagraphStyle(current.styleId)) {
+    return true;
+  }
+  const next = blocks[index + 1];
+  return next?.type === "paragraph" && isTocParagraphStyle(next.styleId);
+}
+
+function findTocParagraphRegionEnd(blocks: readonly BlockNode[], startIndex: number): number {
+  let endIndex = startIndex;
+  while (endIndex + 1 < blocks.length) {
+    const next = blocks[endIndex + 1];
+    if (next?.type !== "paragraph" || !isTocParagraphStyle(next.styleId)) {
+      break;
+    }
+    endIndex += 1;
+  }
+  return endIndex;
+}
+
+function isTocParagraphStyle(styleId: string | undefined): boolean {
+  return /^TOC\d+$/u.test(styleId ?? "");
+}
+
+function findTocFieldNode(paragraph: ParagraphNode): FieldNode | undefined {
+  return paragraph.children.find(
+    (child): child is FieldNode => child.type === "field" && child.fieldFamily === "TOC",
+  );
+}
+
+function buildTocRegionParagraphs(
+  existingRegion: readonly ParagraphNode[],
+  tocField: FieldNode,
+  entries: readonly RuntimeTocEntry[],
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
+): ParagraphNode[] {
+  const firstTemplate = existingRegion[0];
+  if (!firstTemplate) {
+    return [];
+  }
+  const templateByStyle = new Map<string, ParagraphNode>();
+  for (const paragraph of existingRegion) {
+    if (paragraph.styleId && !templateByStyle.has(paragraph.styleId)) {
+      templateByStyle.set(paragraph.styleId, paragraph);
+    }
+  }
+  const refreshedField: FieldNode = {
+    ...tocField,
+    children: [],
+    refreshStatus: "current",
+  };
+
+  if (entries.length === 0) {
+    return [{ ...firstTemplate, children: [refreshedField] }];
+  }
+
+  return entries.map((entry, index) => {
+    const styleId = `TOC${Math.max(1, Math.min(9, entry.level))}`;
+    const template = templateByStyle.get(styleId) ?? firstTemplate;
+    const children = buildTocEntryInlineNodes(entry, resolveDisplayPageNumber);
+    return {
+      ...template,
+      styleId,
+      children: index === 0 ? [refreshedField, ...children] : children,
+    };
+  });
+}
+
+function buildTocEntryInlineNodes(
+  entry: RuntimeTocEntry,
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
+): InlineNode[] {
+  const children: InlineNode[] = [];
+  if (entry.bookmarkName) {
+    children.push({
+      type: "hyperlink",
+      href: `#${entry.bookmarkName}`,
+      children: [{ type: "text", text: entry.text }],
+    });
+  } else {
+    children.push({ type: "text", text: entry.text });
+  }
+  children.push({ type: "tab" });
+  const displayed = resolveDisplayPageNumber?.(entry.pageIndex);
+  children.push({
+    type: "text",
+    text: String(displayed ?? entry.pageIndex + 1),
+  });
+  return children;
+}
+
+function tocRegionSignature(paragraphs: readonly ParagraphNode[]): string {
+  return paragraphs
+    .map((paragraph) => `${paragraph.styleId ?? ""}\u0001${tocInlineSignature(paragraph.children)}`)
+    .join("\u0002");
+}
+
+function tocInlineSignature(children: readonly InlineNode[]): string {
+  return children
+    .map((child) => {
+      switch (child.type) {
+        case "text":
+          return `t:${child.text}`;
+        case "tab":
+          return "tab";
+        case "hard_break":
+          return "br";
+        case "hyperlink":
+          return `link:${child.href}:${tocInlineSignature(child.children)}`;
+        case "field":
+          return `field:${child.fieldFamily ?? ""}:${child.refreshStatus ?? ""}:${child.instruction}:${tocInlineSignature(child.children)}`;
+        default:
+          return child.type;
+      }
+    })
+    .join("\u0001");
+}
+
 function refreshBlocksWithCursor(
   blocks: readonly BlockNode[],
   visitField: (field: FieldNode, range: { from: number; to: number }) => FieldNode,