@beyondwork/docx-react-component 1.0.87 → 1.0.89

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,
@@ -190,6 +191,7 @@ import {
 } from "../core/commands/add-scope.ts";
 import {
   applyFormattingOperationToDocument,
+  applyTextMarkOperationToDocumentRange,
   type FormattingOperation,
 } from "../core/commands/formatting-commands.ts";
 import { resolveActiveParagraphIndex } from "../core/commands/paragraph-layout-commands.ts";
@@ -449,6 +451,12 @@ export interface DocumentRuntime {
    * UI paths.
    */
   applyScopeReplacement(plan: RuntimeOperationPlan): void;
+  /**
+   * Layer-08 scoped formatting dispatch. Returns true when at least one
+   * document.replace transaction was committed, which lets the compiler
+   * suppress no-op audits.
+   */
+  applyScopeFormatting(plan: RuntimeOperationPlan): boolean;
   dispatch(command: EditorCommand): void;
   /**
    * Apply a command received from a remote collaborator. The command
@@ -1174,6 +1182,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.
@@ -1380,6 +1390,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,
@@ -1567,19 +1579,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 }
         : {}),
@@ -1605,20 +1633,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 {
@@ -2469,6 +2534,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}
@@ -3275,6 +3391,7 @@ export function createDocumentRuntime(
               {
                 type: "text.insert",
                 text: step.text,
+                ...(step.formatting ? { formatting: step.formatting } : {}),
                 origin: createOrigin("api", timestamp),
               },
               {
@@ -3349,6 +3466,7 @@ export function createDocumentRuntime(
               {
                 type: "text.insert",
                 text: step.text,
+                ...(step.formatting ? { formatting: step.formatting } : {}),
                 origin: createOrigin("api", timestamp),
               },
               {
@@ -3397,6 +3515,48 @@ export function createDocumentRuntime(
         }
       }
     },
+    applyScopeFormatting(plan: RuntimeOperationPlan) {
+      let changed = false;
+      for (const step of plan.steps) {
+        if (
+          step.kind !== "formatting-apply" ||
+          !step.range ||
+          !step.formattingAction
+        ) {
+          continue;
+        }
+
+        const operation =
+          step.formattingAction.kind === "clear-mark"
+            ? {
+                type: "clear-mark" as const,
+                mark: step.formattingAction.mark,
+              }
+            : {
+                type: "set-mark" as const,
+                mark: step.formattingAction.mark,
+              };
+        const result = applyTextMarkOperationToDocumentRange(
+          state.document,
+          step.range,
+          operation,
+        );
+        if (!result.changed) {
+          continue;
+        }
+
+        const timestamp = clock();
+        this.dispatch({
+          type: "document.replace",
+          document: { ...result.document, updatedAt: timestamp },
+          mapping: createEmptyMapping(),
+          selection: toInternalSelectionSnapshot(result.selection),
+          origin: createOrigin("api", timestamp),
+        });
+        changed = true;
+      }
+      return changed;
+    },
     insertFragment(fragment, target) {
       // I2 Tier B Slice 1 — dispatch `fragment.insert` against the active story. The
       // runtime command handler routes into `applyFragmentInsert` (structure-ops).
@@ -4892,14 +5052,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.
@@ -4941,7 +5139,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));
@@ -4949,8 +5149,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) {
@@ -4974,12 +5176,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:
@@ -4999,7 +5226,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),
@@ -5015,26 +5248,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", {
@@ -5608,23 +5839,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

package/src/runtime/scopes/_scope-dependencies.ts

@@ -32,6 +32,7 @@ export type {
   EditorStoryTarget,
   EffectiveSelectionMode,
   InteractionGuardSnapshot,
+  TextFormattingDirective,
   WorkflowBlockedCommandReason,
   WorkflowMetadataEntry,
   WorkflowMetadataSnapshot,

package/src/runtime/scopes/action-validation.ts

@@ -62,8 +62,8 @@ import {
 } from "./preservation-boundary.ts";
 import { resolveScopeRange } from "./scope-range.ts";
 import type {
-  ReplacementOperationKind,
   ReplacementScope,
+  ScopeActionOperationKind,
   SemanticScope,
   ValidationApproval,
   ValidationIssue,
@@ -85,7 +85,7 @@ export interface ScopeValidationRuntime {
 
 export interface ComposeScopeValidationInputs {
   readonly scope: SemanticScope;
-  readonly operation: ReplacementOperationKind;
+  readonly operation: ScopeActionOperationKind;
   readonly proposedContent: ReplacementScope["proposedContent"];
   readonly runtime: ScopeValidationRuntime;
   /**
@@ -119,6 +119,11 @@ export interface ComposeScopeValidationInputs {
    * here; the compile step consumes them to drive per-step behavior.
    */
   readonly preservePolicy?: ReplacementScope["preserve"];
+  /**
+   * Formatting-only actions do not destroy opaque fragments or nested scope
+   * markers, so they bypass the replacement preservation-boundary check.
+   */
+  readonly skipPreservation?: boolean;
 }
 
 /**
@@ -127,9 +132,12 @@ export interface ComposeScopeValidationInputs {
  * entry in the 37-op policy matrix.
  */
 function inferActionId(
-  operation: ReplacementOperationKind,
+  operation: ScopeActionOperationKind,
   content: ReplacementScope["proposedContent"],
 ): AIAction {
+  if (operation === "formatting") {
+    return "fix_formatting";
+  }
   switch (operation) {
     case "replace":
       return content.kind === "text" ? "rewrite_paragraph" : "generate_text";
@@ -287,6 +295,7 @@ function collectPreservationVerdict(
   warnings: ValidationIssue[],
 ): void {
   const { document, scope, positionMap } = inputs;
+  if (inputs.skipPreservation === true) return;
   if (!document) return;
   const pm = positionMap ?? buildScopePositionMap(document);
   const range = inputs.enumeratedScope

package/src/runtime/scopes/audit-bundle.ts

@@ -10,9 +10,9 @@
 
 import type { TelemetryBus } from "../debug/telemetry-bus.ts";
 import type {
-  ReplacementScope,
   RuntimeOperationPlan,
   ScopeActionAudit,
+  ScopeActionProposal,
   SemanticScope,
   ValidationResult,
 } from "./semantic-scope-types.ts";
@@ -24,7 +24,7 @@ export interface EmitScopeActionAuditInputs {
   readonly documentHashBefore: string;
   readonly documentHashAfter?: string;
   readonly targetScopeSnapshot: SemanticScope;
-  readonly proposed: ReplacementScope;
+  readonly proposed: ScopeActionProposal;
   readonly plan: RuntimeOperationPlan;
   readonly validation: ValidationResult;
   readonly emittedAtUtc: string;