@beyondwork/docx-react-component 1.0.43 → 1.0.45

package/src/runtime/document-runtime.ts

@@ -14,6 +14,8 @@ import {
 } from "../core/state/editor-state.ts";
 import type {
   AddCommentParams,
+  AddCommentReplyResult,
+  AddCommentResult,
   CommentSidebarSnapshot,
   CommentSidebarThreadSnapshot,
   CompatibilityReport,
@@ -113,6 +115,7 @@ import {
   type RevisionStore,
 } from "../review/store/revision-store.ts";
 import { createSuggestionsSnapshot } from "./suggestions-snapshot.ts";
+import { validateSelectionAgainstDocument } from "./selection/post-edit-validator.ts";
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
@@ -244,6 +247,7 @@ export type ActiveStoryTextCommand =
   | Extract<EditorCommand, { type: "text.delete-backward" }>
   | Extract<EditorCommand, { type: "text.delete-forward" }>
   | Extract<EditorCommand, { type: "text.insert-tab" }>
+  | Extract<EditorCommand, { type: "text.outdent-tab" }>
   | Extract<EditorCommand, { type: "text.insert-hard-break" }>
   | Extract<EditorCommand, { type: "paragraph.split" }>;
 
@@ -281,11 +285,11 @@ export interface DocumentRuntime {
   blur(): void;
   setDefaultAuthorId?(authorId?: string): void;
   getDefaultAuthorId?(): string | undefined;
-  addComment(params: AddCommentParams): string;
+  addComment(params: AddCommentParams): AddCommentResult;
   openComment(commentId: string): void;
   resolveComment(commentId: string): void;
   reopenComment(commentId: string): void;
-  addCommentReply(commentId: string, body: string, authorId?: string): void;
+  addCommentReply(commentId: string, body: string, authorId?: string): AddCommentReplyResult;
   editCommentBody(commentId: string, body: string): void;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
@@ -382,6 +386,21 @@ export interface DocumentRuntime {
    */
   getPerfCountersSnapshot(): Record<string, number>;
   resetPerfCounters(): void;
+  /**
+   * Notifies the runtime that the UI's visible block range changed.
+   * The next `refreshRenderSnapshot()` (triggered by any mutation) uses this
+   * range to cull off-screen blocks in the surface projection. Calling this
+   * method alone does NOT trigger a snapshot rebuild — a subsequent mutation
+   * or an explicit `requestViewportRefresh()` is required.
+   *
+   * Safe to call at any frequency; identical ranges are a no-op.
+   */
+  setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Triggers a surface-only refresh that applies the latest visible block range
+   * without running the full commit pipeline. Used by scroll handlers.
+   */
+  requestViewportRefresh(): void;
 }
 
 export interface CommandAppliedMeta {
@@ -437,6 +456,17 @@ export interface CreateDocumentRuntimeOptions {
    * See `docs/plans/fastload.md` and `src/io/load-scheduler.ts`.
    */
   loadScheduler?: LoadScheduler;
+  /**
+   * 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
+   * `src/runtime/prerender/cache-key.ts` to guarantee this).
+   *
+   * See docs/plans/lane-2-render-performance.md §Phase 2.5 §3.7.
+   */
+  seedLayoutCache?: import("./layout/page-graph.ts").RuntimePageGraph;
 }
 
 interface HistoryState {
@@ -444,6 +474,84 @@ interface HistoryState {
   future: EditorState[];
 }
 
+/**
+ * L7 Phase 1.7.4 — structural-counts hash for the reviewWork cache key.
+ *
+ * `getCachedWorkflowMarkupSnapshot()` returns a NEW object on every
+ * `revisionToken` bump, so the previous reference-equality check
+ * (`cachedReviewWork.workflowMarkup === wfMarkup`) always failed on pure
+ * text edits — forcing `createReviewWorkSnapshot` to re-walk every comment,
+ * revision, protected range, and opaque fragment on every keystroke
+ * (94 % of typing latency on large-tables, 97 % on extra-large).
+ *
+ * The hash is a colon-joined string of per-category item counts. Pure text
+ * edits within unchanged blocks do not change any count, so the hash
+ * compares equal and the cached snapshot is reused. Structural changes
+ * (comment added, revision authored, block inserted/deleted) alter at
+ * least one count, so the hash diverges and the cache misses correctly.
+ *
+ * Correctness: the cached `items` include absolute-position `anchor`s that
+ * get stale under a text edit. That is safe here because this cache lives
+ * ONLY inside `getCachedRuntimeContextAnalytics`, whose consumers
+ * (`buildDocumentAnalytics`, `buildSelectionAnalytics`, etc.) read only the
+ * numeric `openCommentCount` and `actionableRevisionCount` fields — the
+ * stale `items[].anchor` never reaches a consumer. The direct
+ * `runtime.getReviewWorkSnapshot()` API does not use this cache.
+ */
+function computeWorkflowMarkupStructuralHash(
+  wfMarkup: WorkflowMarkupSnapshot,
+): string {
+  return [
+    wfMarkup.totalCount,
+    wfMarkup.highlights.length,
+    wfMarkup.metadata.length,
+    wfMarkup.comments.length,
+    wfMarkup.revisions.length,
+    wfMarkup.fields.length,
+    wfMarkup.protectedRanges.length,
+    wfMarkup.opaqueFragments.length,
+  ].join(":");
+}
+
+/**
+ * L7 Phase 1.7.4 — review-status hash for the reviewWork cache key.
+ *
+ * `state.document.review.comments` and `.revisions` are rebuilt with new
+ * object identities on every text command (via `remapReviewStateAfterContent
+ * Change` → `remapCommentThreads` → `Object.fromEntries`), so a reference
+ * check on those records always fails on pure text edits. But the
+ * `reviewWork` snapshot's observable output depends only on:
+ *   - which comments are OPEN (`openCommentCount = openCommentIds.length`)
+ *   - which revisions are ACTIONABLE
+ *     (`actionableRevisionCount = actionableChangeIds.length`)
+ * plus the per-category item counts already captured by
+ * `computeWorkflowMarkupStructuralHash`.
+ *
+ * `comments` / `revisions` keys and statuses are stable across text edits
+ * (remap only rewrites anchors and wraps in `{...thread, anchor}` — status
+ * is carried through). Hashing "id+status" for each record is O(N) over
+ * the small review set and captures the semantic identity we need.
+ *
+ * We intentionally do NOT include anchor positions in the hash: anchor
+ * shifts are exactly the staleness the cache is allowed to tolerate (see
+ * `cachedReviewWork` correctness note above).
+ */
+function computeReviewStateHash(
+  review: CanonicalDocumentEnvelope["review"],
+): string {
+  const commentParts: string[] = [];
+  for (const commentId of Object.keys(review.comments).sort()) {
+    const thread = review.comments[commentId];
+    commentParts.push(`${commentId}=${thread?.status ?? ""}`);
+  }
+  const revisionParts: string[] = [];
+  for (const revisionId of Object.keys(review.revisions).sort()) {
+    const revision = review.revisions[revisionId];
+    revisionParts.push(`${revisionId}=${revision?.status ?? ""}`);
+  }
+  return `${commentParts.join(",")}|${revisionParts.join(",")}`;
+}
+
 export function createDocumentRuntime(
   options: CreateDocumentRuntimeOptions,
 ): DocumentRuntime {
@@ -537,6 +645,16 @@ export function createDocumentRuntime(
   // upgrades to the canvas backend once fonts resolve.  `swapMeasurementProvider`
   // emits `measurement_backend_ready` so chrome consumers can re-read metrics.
   const layoutEngine: LayoutEngineInstance = createLayoutEngine();
+  if (options.seedLayoutCache) {
+    // L7 Phase 2.5 — seed the cached graph from the prerender envelope so
+    // the first getPageGraph call skips fullRebuild. Seed is keyed on the
+    // 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.
+    layoutEngine.seedCachedGraph(options.seedLayoutCache, state.document);
+    perfCounters.increment("loadSession.layoutCache.seeded");
+  }
   const fontLoader: DocxFontLoader = createDocxFontLoader(
     collectFontLoaderInput(state.document),
   );
@@ -579,11 +697,40 @@ export function createDocumentRuntime(
     // runtime already builds for comment/revision/search consumers.
     getWorkflowMarkupMetadata: () =>
       getCachedWorkflowMarkupSnapshot().metadata,
+    // 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.
+    setVisibleBlockRange: (range) => {
+      if (
+        viewportBlockRange &&
+        viewportBlockRange.start === range.start &&
+        viewportBlockRange.end === range.end
+      ) {
+        return;
+      }
+      viewportBlockRange = { start: range.start, end: range.end };
+      perfCounters.increment("runtime.viewport.updates");
+    },
+    requestViewportRefresh: () => {
+      perfCounters.increment("runtime.viewport.refreshes");
+      refreshSurfaceOnly();
+    },
   });
   renderKernelRef = createRenderKernel({
     facet: layoutFacet,
     getActiveStory: () => activeStory,
   });
+  // L7 Phase 2 — viewport block range for surface culling.
+  let viewportBlockRange: { start: number; end: number } | null = null;
+
   let cachedSurface:
     | {
         revisionToken: string;
@@ -620,17 +767,62 @@ export function createDocumentRuntime(
       }
     | undefined;
   // L7 Phase 1 — review-work snapshot cache. Independent of selection.
-  // Inputs that bust it: workflowMarkup, comments, trackedChanges,
-  // document, navigation references. Per-keystroke profiling on the
-  // 40-page CCEP fixture showed createReviewWorkSnapshot at 211ms/call
-  // with no cache, dominated by per-item createDocumentLocationSnapshot.
+  //
+  // What we cache. `createReviewWorkSnapshot`'s observable output is:
+  //   - `openCommentCount` = `comments.openCommentIds.length`
+  //   - `actionableRevisionCount` = `trackedChanges.actionableChangeIds.length`
+  //   - `items[]` (each with stale-tolerable `anchor`/`sectionIndex`/
+  //     `pageIndex` — see "Correctness" below)
+  //
+  // Cache-busting inputs (L7 Phase 1.7.4 — two complementary hashes):
+  //   - `workflowMarkupHash` — structural-counts hash over wfMarkup.
+  //     Replaces the old `workflowMarkup === wfMarkup` reference check,
+  //     which always failed on pure text edits because
+  //     `getCachedWorkflowMarkupSnapshot()` is keyed on revisionToken.
+  //     Pure text edits keep all per-category item counts stable → hash
+  //     equal. A comment ADDITION, revision AUTHORED, protected-range added,
+  //     opaque-fragment added → at least one count changes → hash diverges.
+  //   - `reviewStateHash` — "id+status" hash over `state.document.review`.
+  //     Captures the open/resolved/detached distribution that item COUNTS
+  //     alone can't see (a comment RESOLVED leaves the count stable but
+  //     shifts openCommentCount). Stable across text edits because
+  //     `remapCommentThreads` preserves status on every record.
+  //
+  // Note we intentionally DO NOT key on `cachedRenderSnapshot.comments` or
+  // `.trackedChanges` (the snapshot references) because those projections
+  // are rebuilt on every revisionToken bump — their text previews depend on
+  // live document text. And we DO NOT key on `state.document.review.comments`
+  // or `.revisions` directly: every text command rebuilds those records via
+  // `remapReviewStateAfterContentChange`, producing new object identities
+  // even when no anchor or status changed. The two hashes above capture the
+  // semantic identity that actually matters for ReviewWorkSnapshot output
+  // without churning on each keystroke.
+  //
+  // We also DO NOT store a `document` or `navigation` reference: both churn
+  // on every revisionToken bump, so those checks forced a 100 % miss rate
+  // on text edits with no compensating correctness gain.
+  //
+  // Correctness. Any change that affects the cached snapshot's observable
+  // output (`openCommentCount`, `actionableRevisionCount`, or the set of
+  // workflow items) shifts at least one of (workflowMarkupHash,
+  // reviewStateHash). The per-item `anchor` positions stored on stale cached
+  // items can be out of date, but this cache is consumed only inside
+  // `getCachedRuntimeContextAnalytics` where downstream
+  // `buildDocumentAnalytics` / `buildSelectionAnalytics` /
+  // `buildWorkflowScopeAnalytics` / `buildWorkItemAnalytics` read ONLY
+  // `reviewWorkSnapshot.openCommentCount` and `.actionableRevisionCount`
+  // (numbers). The stale `items[].anchor` never reaches a consumer. The
+  // public `runtime.getReviewWorkSnapshot()` API calls
+  // `createReviewWorkSnapshot` fresh and does not use this cache.
+  //
+  // Per-keystroke profiling on CCEP fixtures showed createReviewWorkSnapshot
+  // at 188 ms/call on large-tables (40 pp) and ~5 s/call on extra-large
+  // (100 pp) — dominated by per-item createDocumentLocationSnapshot. Phase
+  // 1.7.4 takes the 20/20 miss rate on pure text edits to ≤2/20.
   let cachedReviewWork:
     | {
-        comments: CommentSidebarSnapshot;
-        trackedChanges: TrackedChangesSnapshot;
-        workflowMarkup: WorkflowMarkupSnapshot;
-        document: CanonicalDocumentEnvelope;
-        navigation: DocumentNavigationSnapshot;
+        workflowMarkupHash: string;
+        reviewStateHash: string;
         snapshot: ReviewWorkSnapshot;
       }
     | undefined;
@@ -725,7 +917,7 @@ export function createDocumentRuntime(
       return cachedSurface.snapshot;
     }
 
-    const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory);
+    const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, { viewportBlockRange });
     recordPerfSample("snapshot.surface");
     incrementInvalidationCounter("runtime.snapshot.surfaceMisses");
     cachedSurface = {
@@ -1523,13 +1715,25 @@ export function createDocumentRuntime(
 
     const tReview = performance.now();
     let reviewWork: ReviewWorkSnapshot;
+    // L7 Phase 1.7.4 — two structural hashes replace the old reference
+    // checks. `workflowMarkupHash` captures per-category wfMarkup item
+    // counts (see computeWorkflowMarkupStructuralHash); `reviewStateHash`
+    // captures id+status over state.document.review (see
+    // computeReviewStateHash). Together they bust on any mutation that can
+    // change ReviewWorkSnapshot's observable output
+    // (openCommentCount, actionableRevisionCount, or the item set), while
+    // staying stable under pure text edits so the expensive
+    // createReviewWorkSnapshot walk is skipped. The prior `comments` /
+    // `trackedChanges` / `workflowMarkup` / `document` / `navigation`
+    // reference checks are dropped: all of them were churned on every
+    // revisionToken bump and forced a 20/20 miss rate. See the
+    // `cachedReviewWork` declaration above for the full rationale.
+    const wfMarkupHash = computeWorkflowMarkupStructuralHash(wfMarkup);
+    const reviewStateHash = computeReviewStateHash(state.document.review);
     if (
       cachedReviewWork &&
-      cachedReviewWork.comments === cachedRenderSnapshot.comments &&
-      cachedReviewWork.trackedChanges === cachedRenderSnapshot.trackedChanges &&
-      cachedReviewWork.workflowMarkup === wfMarkup &&
-      cachedReviewWork.document === state.document &&
-      cachedReviewWork.navigation === navigation
+      cachedReviewWork.workflowMarkupHash === wfMarkupHash &&
+      cachedReviewWork.reviewStateHash === reviewStateHash
     ) {
       reviewWork = cachedReviewWork.snapshot;
       perfCounters.increment("ctxa.reviewWork.cacheHit");
@@ -1542,11 +1746,8 @@ export function createDocumentRuntime(
         navigation,
       });
       cachedReviewWork = {
-        comments: cachedRenderSnapshot.comments,
-        trackedChanges: cachedRenderSnapshot.trackedChanges,
-        workflowMarkup: wfMarkup,
-        document: state.document,
-        navigation,
+        workflowMarkupHash: wfMarkupHash,
+        reviewStateHash,
         snapshot: reviewWork,
       };
       perfCounters.increment("ctxa.reviewWork.cacheMiss");
@@ -1702,6 +1903,38 @@ export function createDocumentRuntime(
     };
   }
 
+  /**
+   * L7 Phase 2 — surface-only refresh triggered by viewport scroll.
+   * Rebuilds only the surface facet (with the current viewportBlockRange) and
+   * splices it into cachedRenderSnapshot. Does NOT rebuild layout, comments,
+   * trackedChanges, or compatibility. Does NOT increment "refresh.all".
+   */
+  function refreshSurfaceOnly(): void {
+    const newSurface = createEditorSurfaceSnapshot(
+      state.document,
+      state.selection,
+      activeStory,
+      { viewportBlockRange },
+    );
+    // 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,
+      activeStoryKey: storyTargetKey(activeStory),
+      snapshot: newSurface,
+    };
+    cachedRenderSnapshot = {
+      ...cachedRenderSnapshot,
+      surface: newSurface,
+    };
+    // Notify listeners using the same pattern as other setX methods.
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
   function getCachedViewStateSnapshot(): EditorViewStateSnapshot {
     const activeStoryKey = storyTargetKey(activeStory);
     const pageLayout = cachedRenderSnapshot.pageLayout;
@@ -2029,13 +2262,13 @@ export function createDocumentRuntime(
       const selection = params.anchor
         ? createSelectionFromPublicAnchor(params.anchor)
         : state.selection;
-      if (!canCreateDocxCommentAnchor(state.document.content, anchor)) {
+      if (!canCreateDocxCommentAnchor(cachedRenderSnapshot.surface, anchor)) {
         const error: InternalEditorError = {
           errorId: createSessionId("comment-anchor", clock()),
           code: "validation_failed",
           isFatal: false,
           message:
-            "DOCX comments must use a non-empty range that stays within a single paragraph.",
+            "DOCX comments must use a non-empty range that stays within a single story and does not cross table or opaque-fragment boundaries.",
           source: "runtime",
           details: {
             reason: "invalid_comment_anchor",
@@ -2077,7 +2310,10 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
 
-      return commentId;
+      return {
+        commentId,
+        anchor: toPublicAnchorProjection(anchor),
+      };
     },
     openComment(commentId) {
       this.dispatch({
@@ -2102,6 +2338,8 @@ export function createDocumentRuntime(
       });
     },
     addCommentReply(commentId, body, authorId) {
+      const priorEntryCount =
+        state.document.review.comments[commentId]?.entries?.length ?? 0;
       this.dispatch({
         type: "comment.add-reply",
         commentId,
@@ -2109,6 +2347,8 @@ export function createDocumentRuntime(
         authorId: authorId ?? defaultAuthorId,
         origin: createOrigin("api", clock()),
       });
+      const entryId = `${commentId}-entry-${priorEntryCount + 1}`;
+      return { commentId, entryId };
     },
     editCommentBody(commentId, body) {
       this.dispatch({
@@ -2658,6 +2898,21 @@ export function createDocumentRuntime(
     resetPerfCounters() {
       perfCounters.reset();
     },
+    setVisibleBlockRange(range) {
+      if (
+        viewportBlockRange &&
+        viewportBlockRange.start === range.start &&
+        viewportBlockRange.end === range.end
+      ) {
+        return;
+      }
+      viewportBlockRange = { start: range.start, end: range.end };
+      perfCounters.increment("runtime.viewport.updates");
+    },
+    requestViewportRefresh() {
+      perfCounters.increment("runtime.viewport.refreshes");
+      refreshSurfaceOnly();
+    },
   };
 
   function applyHistory(direction: "undo" | "redo"): void {
@@ -2731,6 +2986,42 @@ export function createDocumentRuntime(
     }
     perfCounters.increment("commit.invalidate.us", Math.round((performance.now() - tInvalidate0) * 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.
+    //
+    // Wired ONLY at this chokepoint. The other 12 `cachedRenderSnapshot =
+    // refreshRenderSnapshot()` sites in this file are intentionally skipped:
+    // - Initial setup (line ~1878): no prior selection to validate.
+    // - View-mode setters (lines ~2313–2351): zoom/mode/preview changes don't
+    //   change state.document; validator pass would always be identity.
+    // - applyHistory / undo-redo (line ~2813): restores a {document, selection}
+    //   snapshot that was already validated at the commit that produced it.
+    // - Workflow overlay / error / story switch (lines ~3398, 3416, 3582, 3608):
+    //   substitute a stored selection that was validated at the commit that
+    //   stored it. If a future structural command can mutate state.document
+    //   without going through applyTransactionToState, validation must be added
+    //   at that site.
+    //
+    // Using the post-mutation storySize (not cachedRenderSnapshot's pre-mutation
+    // storySize) avoids clamping the caret behind every keystroke at end-of-doc.
+    // 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 validatedSelection = validateSelectionAgainstDocument(
+      state.document,
+      state.selection,
+      surfaceForValidation.storySize,
+    );
+    if (validatedSelection !== state.selection) {
+      state = { ...state, selection: validatedSelection };
+      storySelections.set(storyTargetKey(activeStory), state.selection);
+    }
+
     const tRefresh0 = performance.now();
     cachedRenderSnapshot = refreshRenderSnapshot();
     perfCounters.increment("commit.refresh.us", Math.round((performance.now() - tRefresh0) * 1000));

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

@@ -0,0 +1,98 @@
+import type { DocumentRuntime } from "../document-runtime.ts";
+import {
+  applyListAwareTextCommand,
+  type DispatchTextCommand,
+  type ListAwareDispatchDeps,
+  type ListAwareMutationResult,
+  type StoryMutationContext,
+} from "./list-aware-dispatch.ts";
+
+export type { DispatchTextCommand };
+
+// TODO(Part 2): collapse DispatchContext into the runtime layer.
+// The four UI-private helpers (getStoryMutationContext, dispatchStoryMutationResult,
+// resolveActiveParagraphContext, toRuntimeSelectionSnapshot) currently live in
+// WordReviewEditor.tsx for historical reasons but are pure runtime adapters with
+// no React/UI dependencies. The four-shell refactor (R.1-R.4) will move them
+// into src/runtime/edit-dispatch/, at which point this DI bundle dissolves.
+export interface DispatchContext extends ListAwareDispatchDeps {
+  getStoryMutationContext(
+    runtime: DocumentRuntime,
+    command?: string,
+  ): StoryMutationContext | null;
+  dispatchStoryMutationResult(
+    runtime: DocumentRuntime,
+    context: StoryMutationContext,
+    result: ListAwareMutationResult,
+    timestamp: string,
+  ): void;
+}
+
+export function dispatchTextCommand(
+  runtime: DocumentRuntime,
+  command: DispatchTextCommand,
+  deps: DispatchContext,
+): void {
+  const context = deps.getStoryMutationContext(runtime, getMountedTextCommandName(command));
+  if (!context) {
+    return;
+  }
+
+  const effectiveSelectionMode = runtime.getInteractionGuardSnapshot().effectiveMode;
+  const listAwareResult = applyListAwareTextCommand(context, command, deps);
+  if (effectiveSelectionMode === "suggest" && listAwareResult) {
+    runtime.emitBlockedCommand(getMountedTextCommandName(command), [{
+      code: "suggesting_unsupported",
+      message: "List structure changes are not supported in suggesting mode.",
+    }]);
+    return;
+  }
+
+  if (listAwareResult) {
+    deps.dispatchStoryMutationResult(runtime, context, listAwareResult, context.timestamp);
+    return;
+  }
+
+  switch (command.type) {
+    case "insert-text":
+      runtime.applyActiveStoryTextCommand({ type: "text.insert", text: command.text });
+      return;
+    case "delete-backward":
+      runtime.applyActiveStoryTextCommand({ type: "text.delete-backward" });
+      return;
+    case "delete-forward":
+      runtime.applyActiveStoryTextCommand({ type: "text.delete-forward" });
+      return;
+    case "insert-tab":
+      runtime.applyActiveStoryTextCommand({ type: "text.insert-tab" });
+      return;
+    case "outdent-tab":
+      runtime.applyActiveStoryTextCommand({ type: "text.outdent-tab" });
+      return;
+    case "insert-hard-break":
+      runtime.applyActiveStoryTextCommand({ type: "text.insert-hard-break" });
+      return;
+    case "split-paragraph":
+      runtime.applyActiveStoryTextCommand({ type: "paragraph.split" });
+      return;
+  }
+}
+
+function getMountedTextCommandName(command: DispatchTextCommand): string {
+  switch (command.type) {
+    case "insert-text":
+      return "text.insert";
+    case "delete-backward":
+      return "text.delete-backward";
+    case "delete-forward":
+      return "text.delete-forward";
+    case "insert-tab":
+      return "text.insert-tab";
+    case "outdent-tab":
+      return "text.outdent-tab";
+    case "insert-hard-break":
+      return "text.insert-hard-break";
+    case "split-paragraph":
+      return "paragraph.split";
+  }
+}

package/src/runtime/edit-dispatch/index.ts

@@ -0,0 +1,2 @@
+export { dispatchTextCommand } from "./dispatch-text-command.ts";
+export type { DispatchTextCommand, DispatchContext } from "./dispatch-text-command.ts";