@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/runtime/document-runtime.ts

@@ -187,6 +187,13 @@ import {
   createWorkflowCoordinator,
   type WorkflowCoordinator,
 } from "./workflow/coordinator.ts";
+import {
+  areWorkflowReviewOverlayLaneSnapshotsEqual,
+  shouldRefreshWorkflowReviewOverlayLane,
+  type WorkflowReviewOverlayLaneListener,
+  type WorkflowReviewOverlayLaneKind,
+  type WorkflowReviewOverlayLaneSnapshot,
+} from "./workflow/overlay-lanes.ts";
 import {
   insertScopeMarkers,
   removeScopeMarkers,
@@ -307,7 +314,7 @@ import { rebuildFieldRegistry } from "./formatting/field/registry.ts";
 import {
   incrementInvalidationCounter,
   recordPerfSample,
-} from "../ui-tailwind/editor-surface/perf-probe.ts";
+} from "./telemetry/perf-probe.ts";
 import {
   createLoadScheduler,
   type LoadScheduler,
@@ -689,6 +696,19 @@ export interface DocumentRuntime {
      * kernel is available) primary anchor rects.
      */
     getAllScopeCardModels(): readonly import("../api/public-types.ts").ScopeCardModel[];
+    /**
+     * Durable review/workflow overlay lane projection. Presence remains
+     * awareness-owned and returns an explicit unavailable snapshot here.
+     */
+    getReviewOverlayLane(kind: WorkflowReviewOverlayLaneKind): WorkflowReviewOverlayLaneSnapshot;
+    /**
+     * Subscribe to durable review/workflow lane changes. The presence lane is
+     * awareness-owned and must be subscribed through the awareness/UI source.
+     */
+    subscribeReviewOverlayLane(
+      kind: WorkflowReviewOverlayLaneKind,
+      listener: WorkflowReviewOverlayLaneListener,
+    ): Unsubscribe;
   };
   /**
    * Runtime-owned geometry facet (Layer 05 · Geometry Projection).
@@ -756,6 +776,8 @@ export interface DocumentRuntime {
   getFootnoteResolver(): FootnoteResolver | undefined;
   updateFields(options?: UpdateFieldsOptions): UpdateFieldsResult;
   updateTableOfContents(options?: TocRefreshOptions): TocRefreshResult;
+  /** Runtime wall-clock timestamp source used for audit/event emission. */
+  now(): string;
   getSessionState(): EditorSessionState;
   getPersistedSnapshot(): PersistedEditorSnapshot;
   getCompatibilityReport(): CompatibilityReport;
@@ -774,7 +796,10 @@ export interface DocumentRuntime {
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
   setWorkflowMetadataDefinitions(definitions: WorkflowMetadataDefinition[]): void;
   clearWorkflowMetadataDefinitions(): void;
-  setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
+  setWorkflowMetadataEntries(
+    entries: WorkflowMetadataEntry[],
+    origin?: WorkflowEventOrigin,
+  ): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
   /** W10 — class-A overlay-visibility policy (per-kind read). */
@@ -1015,8 +1040,8 @@ export interface CreateDocumentRuntimeOptions {
    * L7 Phase 2.5 — prerender cache seed. When set, the internal
    * LayoutEngineInstance is seeded with this graph so the first
    * `getPageGraph()` call returns it directly, skipping `fullRebuild`.
-   * The seeded graph must have been produced with the current
-   * `LAYOUT_ENGINE_VERSION` (callers rely on the cache-key scheme in
+   * The seeded graph must have been produced with the current layout engine
+   * and laycache schema versions (callers rely on the cache-key scheme in
    * `src/runtime/prerender/cache-key.ts` to guarantee this).
    *
    * See CLAUDE.md (lane status table) §Phase 2.5 §3.7.
@@ -1150,6 +1175,46 @@ function computeReviewStateHash(
   return `${commentParts.join(",")}|${revisionParts.join(",")}`;
 }
 
+function normalizeCompatibilityTextNode(text: string): string {
+  return [
+    text.length > 0 ? "nonempty" : "empty",
+    /^\s/u.test(text) ? "leading-space" : "",
+    /\s$/u.test(text) ? "trailing-space" : "",
+    text.includes("  ") ? "double-space" : "",
+  ].filter(Boolean).join(":");
+}
+
+function normalizeCompatibilityCacheValue(key: string, value: unknown): unknown {
+  if (key === "updatedAt" || key === "generatedAt") {
+    return undefined;
+  }
+  if (
+    value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    (value as { type?: unknown }).type === "text" &&
+    typeof (value as { text?: unknown }).text === "string"
+  ) {
+    return {
+      ...value,
+      text: normalizeCompatibilityTextNode((value as { text: string }).text),
+    };
+  }
+  return value;
+}
+
+function computeCompatibilityCacheKey(state: EditorState): string {
+  return JSON.stringify(
+    {
+      document: state.document,
+      warnings: state.warnings,
+      fatalError: state.fatalError,
+      baseCompatibility: state.compatibility,
+    },
+    normalizeCompatibilityCacheValue,
+  );
+}
+
 export function createDocumentRuntime(
   options: CreateDocumentRuntimeOptions,
 ): DocumentRuntime {
@@ -1315,7 +1380,7 @@ export function createDocumentRuntime(
     // runtime's current document identity so `keyEqual` passes without
     // triggering a rebuild. The cache-key scheme in
     // src/runtime/prerender/cache-key.ts guarantees the seed is produced
-    // by the same LAYOUT_ENGINE_VERSION.
+    // by the same layout engine and laycache schema versions.
     layoutEngine.seedCachedGraph(options.seedLayoutCache, state.document);
     perfCounters.increment("loadSession.layoutCache.seeded");
   }
@@ -1326,6 +1391,15 @@ export function createDocumentRuntime(
   // `renderKernelRef` is a forward reference so the facet can reach the
   // kernel after it is created below (kernel creation needs the facet).
   let renderKernelRef: RenderKernel | null = null;
+  // `runtimeRef` is a forward reference so the facet can call the runtime's
+  // viewport methods without duplicating their implementation.
+  let runtimeRef: DocumentRuntime | null = null;
+  const getRuntimeForLayoutFacet = (): DocumentRuntime => {
+    if (!runtimeRef) {
+      throw new Error("Document runtime viewport methods are not initialized");
+    }
+    return runtimeRef;
+  };
   const layoutFacet: WordReviewEditorLayoutFacet = createLayoutFacet({
     engine: layoutEngine,
     getQueryInput: () => ({
@@ -1344,24 +1418,15 @@ export function createDocumentRuntime(
     // input via the getQueryInput + engine accessors above.
     // L7 Phase 2 — delegate viewport culling through the facet so the
     // workspace (which only holds a `layoutFacet` ref) can drive culling
-    // without a separate `DocumentRuntime` prop.  The lambdas forward to
-    // the runtime's own `setVisibleBlockRange` / `requestViewportRefresh`
-    // implementations which are defined below.  Capturing by closure works
-    // because the lambdas are only invoked after the full runtime object is
-    // built and the methods below have been assigned.
-    // TODO(L7 Phase 2 post-merge): this lambda duplicates the setVisibleBlockRange
-    // logic implemented on `runtime` at line ~2874. Consolidate after Phase 2 ships
-    // so the facet forwards to the runtime method. Forward-reference pattern matches
-    // `renderKernelRef` — see that example. See spec-review notes on commit 0b03bfa7.
+    // without a separate `DocumentRuntime` prop.
     setVisibleBlockRange: (range) => {
-      applyViewportRanges([range]);
+      getRuntimeForLayoutFacet().setVisibleBlockRange(range);
     },
     setVisibleBlockRanges: (ranges) => {
-      applyViewportRanges(ranges);
+      getRuntimeForLayoutFacet().setVisibleBlockRanges(ranges);
     },
     requestViewportRefresh: () => {
-      perfCounters.increment("runtime.viewport.refreshes");
-      maybeRefreshSurfaceForViewport();
+      getRuntimeForLayoutFacet().requestViewportRefresh();
     },
   });
   // D1 — wire the layout-guard warning emitter so `return []` guard sites
@@ -1416,7 +1481,14 @@ export function createDocumentRuntime(
 
   let cachedSurface:
     | {
-        revisionToken: string;
+        content: CanonicalDocumentEnvelope["content"];
+        subParts: CanonicalDocumentEnvelope["subParts"];
+        styles: CanonicalDocumentEnvelope["styles"];
+        numbering: CanonicalDocumentEnvelope["numbering"];
+        media: CanonicalDocumentEnvelope["media"];
+        preservation: CanonicalDocumentEnvelope["preservation"];
+        review: CanonicalDocumentEnvelope["review"];
+        effectiveMarkupModeProvider: typeof effectiveMarkupModeProvider;
         activeStoryKey: string;
         /**
          * Serialized viewport ranges at build time. A surface snapshot is
@@ -1424,9 +1496,9 @@ export function createDocumentRuntime(
          * runtime's current `viewportRangesKey` matches — otherwise the
          * cached snapshot realizes a different set of blocks as real vs
          * placeholder-culled than the current runtime state demands.
-         * Pre-refactor/11b this was a (revisionToken, activeStoryKey) key
-         * only, which was silently stale-prone when callers applied new
-         * viewport ranges without also calling `requestViewportRefresh()`.
+         * Do not key this cache on `revisionToken`: commits can advance the
+         * token without changing the structural inputs surface projection
+         * consumes.
          */
         viewportRangesKey: string;
         snapshot: RuntimeRenderSnapshot["surface"];
@@ -1435,10 +1507,7 @@ 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;
+        structuralKey: string;
         warnings: EditorState["warnings"];
         fatalError: EditorState["fatalError"];
         report: RuntimeRenderSnapshot["compatibility"];
@@ -1454,7 +1523,7 @@ export function createDocumentRuntime(
   let cachedTrackedChanges:
     | {
         revisions: CanonicalDocumentEnvelope["review"]["revisions"];
-        revisionToken: string;
+        comments: CanonicalDocumentEnvelope["review"]["comments"];
         snapshot: TrackedChangesSnapshot;
       }
     | undefined;
@@ -1534,19 +1603,22 @@ export function createDocumentRuntime(
     | undefined;
   let cachedNavigation:
     | {
-        revisionToken: string;
+        document: CanonicalDocumentEnvelope;
         activeStoryKey: string;
+        workspaceMode: WorkspaceMode;
+        zoomLevel: ZoomLevel;
         selectionHead: number;
         snapshot: DocumentNavigationSnapshot;
       }
     | undefined;
   let cachedViewStateSnapshot:
     | {
-        revisionToken: string;
         activeStoryKey: string;
         selection: EditorState["selection"];
         viewStateRef: ViewState;
+        surface: RuntimeRenderSnapshot["surface"];
         pageLayout: PageLayoutSnapshot | null | undefined;
+        numbering: CanonicalDocumentEnvelope["numbering"];
         snapshot: EditorViewStateSnapshot;
       }
     | undefined;
@@ -1605,7 +1677,14 @@ export function createDocumentRuntime(
         : surfaceViewportRangesKey;
     if (
       cachedSurface &&
-      cachedSurface.revisionToken === state.revisionToken &&
+      cachedSurface.content === document.content &&
+      cachedSurface.subParts === document.subParts &&
+      cachedSurface.styles === document.styles &&
+      cachedSurface.numbering === document.numbering &&
+      cachedSurface.media === document.media &&
+      cachedSurface.preservation === document.preservation &&
+      cachedSurface.review === document.review &&
+      cachedSurface.effectiveMarkupModeProvider === effectiveMarkupModeProvider &&
       cachedSurface.activeStoryKey === activeStoryKey &&
       cachedSurface.viewportRangesKey === surfaceCacheKey
     ) {
@@ -1644,7 +1723,14 @@ export function createDocumentRuntime(
         ? snapshot
         : enrichCulledPlaceholdersWithHeights(snapshot);
     cachedSurface = {
-      revisionToken: state.revisionToken,
+      content: document.content,
+      subParts: document.subParts,
+      styles: document.styles,
+      numbering: document.numbering,
+      media: document.media,
+      preservation: document.preservation,
+      review: document.review,
+      effectiveMarkupModeProvider,
       activeStoryKey,
       viewportRangesKey: surfaceCacheKey,
       snapshot: enrichedSnapshot,
@@ -1652,7 +1738,7 @@ export function createDocumentRuntime(
     // 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}|${surfaceCacheKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
+    cachedSurfaceFingerprint = `${activeStoryKey}|${surfaceCacheKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     return enrichedSnapshot;
   }
 
@@ -1761,8 +1847,7 @@ export function createDocumentRuntime(
   function getCachedCompatibilityReport(
     nextState: EditorState,
   ): RuntimeRenderSnapshot["compatibility"] {
-    const blockCount = nextState.document.content.children.length;
-    const warningCount = nextState.warnings?.length ?? 0;
+    let structuralKey: string | undefined;
     if (cachedCompatibility) {
       // Fast path 1: same revisionToken (selection move, surface-only refresh).
       if (
@@ -1772,27 +1857,21 @@ export function createDocumentRuntime(
       ) {
         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.
+      structuralKey = computeCompatibilityCacheKey(nextState);
       if (
-        cachedCompatibility.blockCount === blockCount &&
-        cachedCompatibility.warningCount === warningCount &&
-        cachedCompatibility.fatalError === nextState.fatalError
+        cachedCompatibility.structuralKey === structuralKey
       ) {
         cachedCompatibility = {
           ...cachedCompatibility,
           revisionToken: nextState.revisionToken,
           warnings: nextState.warnings,
+          fatalError: nextState.fatalError,
         };
         return cachedCompatibility.report;
       }
     }
 
+    structuralKey ??= computeCompatibilityCacheKey(nextState);
     const derived = createDerivedCompatibility(nextState);
     recordPerfSample("snapshot.compatibility");
     incrementInvalidationCounter("runtime.snapshot.compatibilityMisses");
@@ -1807,8 +1886,7 @@ export function createDocumentRuntime(
     };
     cachedCompatibility = {
       revisionToken: nextState.revisionToken,
-      blockCount,
-      warningCount,
+      structuralKey,
       warnings: nextState.warnings,
       fatalError: nextState.fatalError,
       report,
@@ -1841,7 +1919,7 @@ export function createDocumentRuntime(
     if (
       cachedTrackedChanges &&
       cachedTrackedChanges.revisions === nextState.document.review.revisions &&
-      cachedTrackedChanges.revisionToken === nextState.revisionToken
+      cachedTrackedChanges.comments === nextState.document.review.comments
     ) {
       return cachedTrackedChanges.snapshot;
     }
@@ -1849,7 +1927,7 @@ export function createDocumentRuntime(
     const snapshot = toPublicTrackedChangesSnapshot(nextState);
     cachedTrackedChanges = {
       revisions: nextState.document.review.revisions,
-      revisionToken: nextState.revisionToken,
+      comments: nextState.document.review.comments,
       snapshot,
     };
     return snapshot;
@@ -1899,8 +1977,10 @@ export function createDocumentRuntime(
       );
     if (
       cachedNavigation &&
-      cachedNavigation.revisionToken === nextState.revisionToken &&
-      cachedNavigation.activeStoryKey === activeStoryKey
+      cachedNavigation.document === nextState.document &&
+      cachedNavigation.activeStoryKey === activeStoryKey &&
+      cachedNavigation.workspaceMode === viewState.workspaceMode &&
+      cachedNavigation.zoomLevel === viewState.zoomLevel
     ) {
       if (cachedNavigation.selectionHead === nextState.selection.head) {
         return cachedNavigation.snapshot;
@@ -1912,16 +1992,20 @@ export function createDocumentRuntime(
         snapshot.activeSectionIndex === cachedNavigation.snapshot.activeSectionIndex
       ) {
         cachedNavigation = {
-          revisionToken: nextState.revisionToken,
+          document: nextState.document,
           activeStoryKey,
+          workspaceMode: viewState.workspaceMode,
+          zoomLevel: viewState.zoomLevel,
           selectionHead: nextState.selection.head,
           snapshot: cachedNavigation.snapshot,
         };
         return cachedNavigation.snapshot;
       }
       cachedNavigation = {
-        revisionToken: nextState.revisionToken,
+        document: nextState.document,
         activeStoryKey,
+        workspaceMode: viewState.workspaceMode,
+        zoomLevel: viewState.zoomLevel,
         selectionHead: nextState.selection.head,
         snapshot,
       };
@@ -1932,8 +2016,10 @@ export function createDocumentRuntime(
     recordPerfSample("snapshot.navigation");
     incrementInvalidationCounter("runtime.snapshot.navigationMisses");
     cachedNavigation = {
-      revisionToken: nextState.revisionToken,
+      document: nextState.document,
       activeStoryKey,
+      workspaceMode: viewState.workspaceMode,
+      zoomLevel: viewState.zoomLevel,
       selectionHead: nextState.selection.head,
       snapshot,
     };
@@ -2115,6 +2201,10 @@ export function createDocumentRuntime(
       }
 
       if (block.kind === "sdt_block") {
+        const lockedSdtMatch = matchWorkflowLockedSurfaceBlock(block, range);
+        if (lockedSdtMatch) {
+          return lockedSdtMatch;
+        }
         const match = findSurfaceOpaqueTargetIntersectingRange(block.children, range);
         if (match) {
           return match;
@@ -2146,6 +2236,49 @@ export function createDocumentRuntime(
     return null;
   }
 
+  function matchWorkflowLockedSurfaceBlock(
+    block: Extract<SurfaceBlockSnapshot, { kind: "sdt_block" }>,
+    range: { from: number; to: number },
+  ): {
+    from: number;
+    to: number;
+    label: string;
+    blockedReasonCode: "workflow_preserve_only" | "workflow_blocked_import";
+  } | null {
+    if (!block.blockedReasonCode) {
+      return null;
+    }
+
+    const blockRange = {
+      from: block.from,
+      to: block.to > block.from ? block.to : block.from + 1,
+    };
+    const targetRange = normalizeCaretRangeForSurfaceIntersection(range);
+    if (!rangesIntersect(blockRange, targetRange)) {
+      return null;
+    }
+
+    return {
+      from: blockRange.from,
+      to: blockRange.to,
+      label: block.label ?? block.alias ?? "Content control",
+      blockedReasonCode: block.blockedReasonCode,
+    };
+  }
+
+  function normalizeCaretRangeForSurfaceIntersection(range: {
+    from: number;
+    to: number;
+  }): { from: number; to: number } {
+    if (range.to > range.from) {
+      return range;
+    }
+    return {
+      from: range.from,
+      to: range.from + 1,
+    };
+  }
+
   function matchOpaqueInlineSegment(
     segment: SurfaceInlineSegment,
     range: { from: number; to: number },
@@ -2632,13 +2765,20 @@ export function createDocumentRuntime(
           : {}),
       },
     );
-    cachedSurfaceFingerprint = `${state.revisionToken}|${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
+    cachedSurfaceFingerprint = `${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     // Refresh the cache with the just-built snapshot so a subsequent
     // refreshRenderSnapshot (same revisionToken + activeStoryKey) hits cache.
     // Without this repopulate, the next non-mutation refresh wastes a second
     // createEditorSurfaceSnapshot call on an identical rebuild.
     cachedSurface = {
-      revisionToken: state.revisionToken,
+      content: state.document.content,
+      subParts: state.document.subParts,
+      styles: state.document.styles,
+      numbering: state.document.numbering,
+      media: state.document.media,
+      preservation: state.document.preservation,
+      review: state.document.review,
+      effectiveMarkupModeProvider,
       activeStoryKey: storyTargetKey(activeStory),
       viewportRangesKey,
       snapshot: newSurface,
@@ -2660,12 +2800,12 @@ export function createDocumentRuntime(
    * a full projection + listener fan-out on every tick.
    *
    * Safe because every external input that can change the projection
-   * output without ticking revisionToken / selection / viewportRanges /
-   * activeStory is wired to call `refreshSurfaceOnly` directly (see
-   * `setEffectiveMarkupModeProvider`, `invalidateForMarkupModeChange`).
+   * output without changing the tracked selection / viewportRanges /
+   * activeStory tuple is wired to call `refreshSurfaceOnly` directly
+   * (see `setEffectiveMarkupModeProvider`, `invalidateForMarkupModeChange`).
    */
   function maybeRefreshSurfaceForViewport(): void {
-    const fingerprint = `${state.revisionToken}|${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
+    const fingerprint = `${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     if (cachedSurfaceFingerprint === fingerprint && cachedSurface) {
       return;
     }
@@ -2722,19 +2862,20 @@ export function createDocumentRuntime(
 
   function getCachedViewStateSnapshot(): EditorViewStateSnapshot {
     const activeStoryKey = storyTargetKey(activeStory);
+    const surface = cachedRenderSnapshot.surface;
     const pageLayout = cachedRenderSnapshot.pageLayout;
     if (
       cachedViewStateSnapshot &&
-      cachedViewStateSnapshot.revisionToken === state.revisionToken &&
       cachedViewStateSnapshot.activeStoryKey === activeStoryKey &&
       cachedViewStateSnapshot.selection === state.selection &&
       cachedViewStateSnapshot.viewStateRef === viewState &&
-      cachedViewStateSnapshot.pageLayout === pageLayout
+      cachedViewStateSnapshot.surface === surface &&
+      cachedViewStateSnapshot.pageLayout === pageLayout &&
+      cachedViewStateSnapshot.numbering === state.document.numbering
     ) {
       return cachedViewStateSnapshot.snapshot;
     }
 
-    const surface = cachedRenderSnapshot.surface;
     const mainSurface =
       activeStory.kind === "main"
         ? surface
@@ -2749,11 +2890,12 @@ export function createDocumentRuntime(
       state.document.numbering,
     );
     cachedViewStateSnapshot = {
-      revisionToken: state.revisionToken,
       activeStoryKey,
       selection: state.selection,
       viewStateRef: viewState,
+      surface,
       pageLayout,
+      numbering: state.document.numbering,
       snapshot,
     };
     return snapshot;
@@ -3207,7 +3349,9 @@ export function createDocumentRuntime(
       try {
         const timestamp = clock();
         const selection = target ? createSelectionFromPublicAnchor(target) : state.selection;
+        const effectiveDocumentMode = workflowCoordinator.getEffectiveDocumentMode(selection);
         if (
+          effectiveDocumentMode !== "suggesting" &&
           shouldPreserveEquivalentReplacement(formatting) &&
           replacementTextMatchesCurrentRange(state.document, activeStory, selection, text)
         ) {
@@ -4384,6 +4528,27 @@ export function createDocumentRuntime(
       getAllScopeCardModels() {
         return workflowCoordinator.getAllScopeCardModels();
       },
+      getReviewOverlayLane(kind: WorkflowReviewOverlayLaneKind) {
+        return workflowCoordinator.getReviewOverlayLane(kind);
+      },
+      subscribeReviewOverlayLane(
+        kind: WorkflowReviewOverlayLaneKind,
+        listener: WorkflowReviewOverlayLaneListener,
+      ) {
+        if (kind === "presence") {
+          throw new Error(
+            "runtime.workflow.subscribeReviewOverlayLane: presence is awareness-owned; use the awareness-backed presence lane source",
+          );
+        }
+        let lastSnapshot = workflowCoordinator.getReviewOverlayLane(kind);
+        return runtime.subscribeToEvents((event) => {
+          if (!shouldRefreshWorkflowReviewOverlayLane(kind, event)) return;
+          const nextSnapshot = workflowCoordinator.getReviewOverlayLane(kind);
+          if (areWorkflowReviewOverlayLaneSnapshotsEqual(lastSnapshot, nextSnapshot)) return;
+          lastSnapshot = nextSnapshot;
+          listener(nextSnapshot);
+        });
+      },
     },
     geometry: geometryFacet,
     getLayoutFacet() {
@@ -4579,9 +4744,18 @@ export function createDocumentRuntime(
           protectionSelection: refreshed.protectionSelection,
           origin: createOrigin("api", clock()),
         });
+        // TOC refresh is an explicit structural API operation, not a typing
+        // hot path. Re-realize the full surface so refreshed generated rows
+        // remain inspectable instead of collapsing to selection-corridor
+        // viewport placeholders immediately after the replacement.
+        applyViewportRanges(null);
+        cachedRenderSnapshot = refreshRenderSnapshot();
       }
       return refreshed.result;
     },
+    now() {
+      return clock();
+    },
     getSessionState() {
       const compatibility = createDerivedCompatibility(state);
       const normalizedWorkflowOverlay = workflowCoordinator.getWorkflowOverlay();
@@ -4737,8 +4911,8 @@ export function createDocumentRuntime(
     clearWorkflowMetadataDefinitions() {
       workflowCoordinator.clearWorkflowMetadataDefinitions();
     },
-    setWorkflowMetadataEntries(entries) {
-      workflowCoordinator.setWorkflowMetadataEntries(entries);
+    setWorkflowMetadataEntries(entries, origin) {
+      workflowCoordinator.setWorkflowMetadataEntries(entries, origin);
     },
     clearWorkflowMetadataEntries() {
       workflowCoordinator.clearWorkflowMetadataEntries();
@@ -5025,6 +5199,7 @@ export function createDocumentRuntime(
       maybeRefreshSurfaceForViewport();
     },
   };
+  runtimeRef = runtime;
 
   // Late-bind the workflow coordinator's dispatch accessor now that
   // the runtime object exists. addScope / removeScope / setWorkflowOverlay /
@@ -5556,30 +5731,6 @@ export function createDocumentRuntime(
     };
     const opId = (command.origin as { opId?: string } | undefined)?.opId;
     const selection = textOptions.selection ?? state.selection;
-    if (
-      activeStory.kind !== "main" &&
-      workflowCoordinator.getEffectiveDocumentMode(selection) === "suggesting" &&
-      command.type === "paragraph.split"
-    ) {
-      const message = `"${command.type}" is not supported in suggesting mode for this story.`;
-      emit({
-        type: "command_blocked",
-        documentId: state.documentId,
-        command: textOptions.blockedCommandName ?? command.type,
-        reasons: [{
-          code: "suggesting_unsupported",
-          message,
-          storyTarget: activeStory,
-        }],
-      });
-      return completeDispatch({
-        kind: "rejected",
-        refreshClass: "blocked",
-        opId,
-        newRevisionToken: "",
-        blockedReasons: [{ code: "suggesting_unsupported", message }],
-      });
-    }
     if (!textOptions.skipWorkflowGuard) {
       const blockedReasons = workflowCoordinator.evaluateBlockedReasons(selection, command.type);
       if (blockedReasons.length > 0) {
@@ -7145,14 +7296,6 @@ const NON_MUTATION_COMMANDS = new Set([
 /** Mutation commands that are not yet supported in suggesting mode. */
 const SUGGESTING_UNSUPPORTED_COMMANDS = new Set<string>([]);
 
-const SUGGESTING_SECONDARY_STORY_UNSUPPORTED_COMMANDS = new Set<string>([
-  "text.insert",
-  "text.delete-backward",
-  "text.delete-forward",
-  "text.insert-tab",
-  "text.insert-hard-break",
-]);
-
 function isMutationCommand(command: EditorCommand): boolean {
   return !NON_MUTATION_COMMANDS.has(command.type);
 }

package/src/runtime/edit-dispatch/dispatch-text-command.ts

@@ -47,6 +47,17 @@ export function dispatchTextCommand(
     }]);
     return;
   }
+  if (
+    effectiveSelectionMode === "suggest" &&
+    command.type === "split-paragraph" &&
+    context.activeStory.kind !== "main"
+  ) {
+    runtime.emitBlockedCommand(getMountedTextCommandName(command), [{
+      code: "suggesting_unsupported",
+      message: "Structural suggestions are only supported in the main story.",
+    }]);
+    return;
+  }
 
   if (listAwareResult) {
     deps.dispatchStoryMutationResult(runtime, context, listAwareResult, context.timestamp);