@beyondwork/docx-react-component 1.0.43 → 1.0.46

package/src/runtime/selection/post-edit-validator.ts

@@ -0,0 +1,77 @@
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { SelectionSnapshot } from "../../core/state/editor-state.ts";
+
+/**
+ * Snap a selection to a valid position relative to the document.
+ *
+ * Pure function.  O(1) on the identity (in-bounds) fast path — returns
+ * the SAME object reference when no change is needed.  Callers should
+ * compare with `!==` to detect a snap (e.g. to decide whether to
+ * re-spread runtime state).
+ *
+ * Wired into the runtime snapshot-emit chokepoint
+ * (`applyTransactionToState` -> `cachedRenderSnapshot = refreshRenderSnapshot()`),
+ * so it runs once per transaction commit.  Must NOT walk the document;
+ * the caller is responsible for passing a valid `maxOffset` (the
+ * POST-mutation `surface.storySize`, primed via
+ * `getCachedSurface(state.document, activeStory).storySize`).
+ *
+ * NodeAnchor invalidation is deferred until CanonicalDocumentEnvelope
+ * grows an O(1) node-by-id accessor.  Until then, NodeAnchor selections
+ * are returned unchanged (identity).
+ *
+ * @param document   The post-mutation canonical document.  Currently
+ *                   unused except for the deferred NodeAnchor branch;
+ *                   the parameter is kept for API stability.
+ * @param selection  The selection to validate.
+ * @param maxOffset  The POST-mutation maximum story offset.  Caller
+ *                   passes `getCachedSurface(state.document,
+ *                   activeStory).storySize` (which primes the cache
+ *                   that `refreshRenderSnapshot` reuses on its next
+ *                   call — no extra surface walk).  The validator does
+ *                   NOT walk the document to compute this.  Do NOT pass
+ *                   the pre-mutation snapshot's storySize: at end-of-doc
+ *                   inserts, the new selection legitimately exceeds the
+ *                   old bound and the validator would clamp the caret
+ *                   backward by one position per keystroke.  Pass
+ *                   `Number.POSITIVE_INFINITY` to skip the upper-bound
+ *                   clamp.
+ */
+export function validateSelectionAgainstDocument(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- reserved for deferred NodeAnchor lookup
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  maxOffset: number,
+): SelectionSnapshot {
+  if (selection.activeRange.kind === "node") {
+    // Deferred: NodeAnchor invalidation requires an O(1) node-by-id
+    // accessor on CanonicalDocumentEnvelope.  Until that lands, return
+    // identity so we never falsely invalidate a still-valid node anchor.
+    return selection;
+  }
+
+  const anchor = clamp(selection.anchor, 0, maxOffset);
+  const head = clamp(selection.head, 0, maxOffset);
+
+  if (anchor === selection.anchor && head === selection.head) {
+    // Identity fast path — no allocation, same reference returned.
+    return selection;
+  }
+
+  const range = { from: Math.min(anchor, head), to: Math.max(anchor, head) };
+  const assoc =
+    selection.activeRange.kind === "range"
+      ? selection.activeRange.assoc
+      : { start: 1 as const, end: 1 as const };
+
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: { kind: "range", range, assoc },
+  };
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  return n < lo ? lo : n > hi ? hi : n;
+}

package/src/runtime/surface-projection.ts

@@ -68,11 +68,17 @@ interface ParagraphAccumulator {
   segments: SurfaceInlineSegment[];
 }
 
+export interface SurfaceProjectionOptions {
+  viewportBlockRange?: { start: number; end: number } | null;
+}
+
 export function createEditorSurfaceSnapshot(
   document: CanonicalDocumentEnvelope,
   _selection: SelectionSnapshot,
   activeStory: EditorStoryTarget = { kind: "main" },
+  options: SurfaceProjectionOptions = {},
 ): EditorSurfaceSnapshot {
+  const viewportBlockRange = options.viewportBlockRange ?? null;
   const root = normalizeDocumentRoot({
     type: "doc",
     children: [...getStoryBlocks(document, activeStory)],
@@ -99,8 +105,34 @@ export function createEditorSurfaceSnapshot(
       numberingPrefixResolver,
       activeStory.kind !== "main",
     );
-    blocks.push(surfaceBlock.block);
-    lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
+    const isInViewport =
+      viewportBlockRange === null ||
+      (index >= viewportBlockRange.start && index < viewportBlockRange.end);
+
+    if (isInViewport) {
+      blocks.push(surfaceBlock.block);
+      lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
+    } else {
+      // Replace with size-preserving placeholder. from/to track the SAME
+      // position range as the real block, so selection and anchor stability
+      // outside the viewport is preserved.
+      const placeholderSize = surfaceBlock.nextCursor - cursor;
+      const placeholderBlockId = `placeholder-culled-${index}`;
+      blocks.push({
+        blockId: placeholderBlockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: surfaceBlock.nextCursor,
+        fragmentId: placeholderBlockId,
+        warningId: placeholderBlockId,
+        label: "",
+        detail: "",
+        placeholderSize,
+        state: "placeholder-culled",
+      } as SurfaceBlockSnapshot);
+      // Do NOT push lockedFragmentIds — placeholder has no real fragment.
+    }
+
     cursor = surfaceBlock.nextCursor;
     if (index < root.children.length - 1 && root.children[index + 1]?.type === "paragraph") {
       cursor += 1;
@@ -115,6 +147,7 @@ export function createEditorSurfaceSnapshot(
     blocks,
     lockedFragmentIds,
     secondaryStories,
+    viewportBlockRange,
   };
 }
 

package/src/ui/WordReviewEditor.tsx

@@ -97,14 +97,15 @@ import {
 } from "../core/commands/style-commands.ts";
 import {
   continueNumbering as continueListNumbering,
-  backspaceAtListStart,
-  indentListItems,
-  outdentListItems,
   restartNumbering as restartListNumbering,
-  splitListParagraph,
   toggleBulletedList,
   toggleNumberedList,
 } from "../core/commands/list-commands.ts";
+import {
+  dispatchTextCommand,
+  type DispatchContext,
+  type DispatchTextCommand,
+} from "../runtime/edit-dispatch/index.ts";
 import {
   resolveActiveParagraphIndex,
   setActiveParagraphIndentation,
@@ -242,6 +243,12 @@ const BROWSER_SAFE_PREVIEW_TYPES = new Set([
   "image/gif",
   "image/webp",
   "image/bmp",
+  // SVG is served through `<img src="data:image/svg+xml;base64,...">` by
+  // `createImageDataUrl`. Chromium sandboxes SVGs loaded via <img> — scripts
+  // don't execute, external references are blocked, XSS surface matches PNG.
+  // Needed for docs/plans/lane-5-charts.md Stage 0B synthesized chart previews and
+  // any host that ships .svg inside `word/media/` as a logo or figure.
+  "image/svg+xml",
 ]);
 
 const ACCESSIBLE_REGION_ORDER = [
@@ -1001,16 +1008,9 @@ export function __createWordReviewEditorRefBridge(
 
 export function __applyRuntimeTextCommand(
   runtime: WordReviewEditorRuntime,
-  command:
-    | { type: "insert-text"; text: string }
-    | { type: "delete-backward" }
-    | { type: "delete-forward" }
-    | { type: "insert-tab" }
-    | { type: "outdent-tab" }
-    | { type: "insert-hard-break" }
-    | { type: "split-paragraph" },
+  command: DispatchTextCommand,
 ): void {
-  applyRuntimeTextCommand(runtime, command);
+  dispatchTextCommand(runtime, command, DISPATCH_CONTEXT);
 }
 
 export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditorProps>(
@@ -1039,6 +1039,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onWarning,
       onReviewSidebarTrackedChanges,
       onReviewSidebarComments,
+      onFindRequested,
+      onPrintRequested,
+      onZoomRequested,
       readOnly = false,
       reviewMode = "review",
       suggestionsEnabled = false,
@@ -2141,7 +2144,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
 
     function addReviewComment(): string | null {
       try {
-        const commentId = activeRuntime.addComment({
+        const { commentId } = activeRuntime.addComment({
           anchor: snapshot.selection.activeRange,
           body: "",
           authorId: currentUser.userId,
@@ -2570,7 +2573,46 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         },
       );
 
-      if (shortcut.kind === "none" || shortcut.kind === "delegate") {
+      if (shortcut.kind === "none") {
+        return;
+      }
+
+      if (shortcut.kind === "delegate") {
+        // Host-delegated shortcuts: if the host has wired a typed
+        // callback we call it and suppress the browser default; if
+        // not, the event falls through to the browser (Ctrl+F opens
+        // Find, Ctrl+Plus zooms, etc.) — matching the legacy behavior.
+        let handled = false;
+        if (shortcut.shortcut === "find" && onFindRequested) {
+          // selectionText is intentionally empty — hosts that need the
+          // selected text already receive it via the selection_changed
+          // event + canonicalDocument they have via onEvent listeners.
+          // The range is the load-bearing field so host Find panels can
+          // scope their search to the selection or pre-populate from it.
+          onFindRequested({
+            selectionText: "",
+            selectionRange: snapshot.selection,
+          });
+          handled = true;
+        } else if (shortcut.shortcut === "print" && onPrintRequested) {
+          onPrintRequested();
+          handled = true;
+        } else if (
+          (shortcut.shortcut === "zoom-in" ||
+            shortcut.shortcut === "zoom-out" ||
+            shortcut.shortcut === "zoom-reset") &&
+          onZoomRequested
+        ) {
+          const direction =
+            shortcut.shortcut === "zoom-in" ? "in" :
+            shortcut.shortcut === "zoom-out" ? "out" : "reset";
+          onZoomRequested(direction);
+          handled = true;
+        }
+        if (handled) {
+          event.preventDefault();
+          event.stopPropagation();
+        }
         return;
       }
 
@@ -2636,13 +2678,13 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onFocus: handleSurfaceFocus,
       onBlur: handleSurfaceBlur,
       onSelectionChange: dispatchSelection,
-      onInsertText: (text: string) => applyRuntimeTextCommand(activeRuntime, { type: "insert-text", text }),
-      onDeleteBackward: () => applyRuntimeTextCommand(activeRuntime, { type: "delete-backward" }),
-      onDeleteForward: () => applyRuntimeTextCommand(activeRuntime, { type: "delete-forward" }),
-      onInsertTab: () => applyRuntimeTextCommand(activeRuntime, { type: "insert-tab" }),
-      onOutdentTab: () => applyRuntimeTextCommand(activeRuntime, { type: "outdent-tab" }),
-      onInsertHardBreak: () => applyRuntimeTextCommand(activeRuntime, { type: "insert-hard-break" }),
-      onSplitParagraph: () => applyRuntimeTextCommand(activeRuntime, { type: "split-paragraph" }),
+      onInsertText: (text: string) => dispatchTextCommand(activeRuntime, { type: "insert-text", text }, DISPATCH_CONTEXT),
+      onDeleteBackward: () => dispatchTextCommand(activeRuntime, { type: "delete-backward" }, DISPATCH_CONTEXT),
+      onDeleteForward: () => dispatchTextCommand(activeRuntime, { type: "delete-forward" }, DISPATCH_CONTEXT),
+      onInsertTab: () => dispatchTextCommand(activeRuntime, { type: "insert-tab" }, DISPATCH_CONTEXT),
+      onOutdentTab: () => dispatchTextCommand(activeRuntime, { type: "outdent-tab" }, DISPATCH_CONTEXT),
+      onInsertHardBreak: () => dispatchTextCommand(activeRuntime, { type: "insert-hard-break" }, DISPATCH_CONTEXT),
+      onSplitParagraph: () => dispatchTextCommand(activeRuntime, { type: "split-paragraph" }, DISPATCH_CONTEXT),
       onUndo: () => activeRuntime.undo(),
       onRedo: () => activeRuntime.redo(),
       onBlockedInput: (command: "paste" | "drop", message: string) =>
@@ -3294,7 +3336,11 @@ function applyRuntimeListToggle(
   dispatchStoryMutationResult(
     runtime,
     context,
-    createListMutationResult(result, context.localSnapshot.selection),
+    {
+      changed: result.affectedParagraphIndexes.length > 0,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+    },
     context.timestamp,
   );
 }
@@ -4418,175 +4464,12 @@ function buildTablesFacet(
 
 export { buildTablesFacet as __buildTablesFacet };
 
-function applyRuntimeTextCommand(
-  runtime: WordReviewEditorRuntime,
-  command:
-    | { type: "insert-text"; text: string }
-    | { type: "delete-backward" }
-    | { type: "delete-forward" }
-    | { type: "insert-tab" }
-    | { type: "outdent-tab" }
-    | { type: "insert-hard-break" }
-    | { type: "split-paragraph" },
-): void {
-  const snapshot = runtime.getRenderSnapshot();
-  const context = getStoryMutationContext(runtime, getMountedTextCommandName(command));
-  if (!context) {
-    return;
-  }
-
-  const effectiveSelectionMode = runtime.getInteractionGuardSnapshot().effectiveMode;
-  const listAwareResult = applyListAwareTextCommand(context, command);
-  if (effectiveSelectionMode === "suggest" && listAwareResult) {
-    runtime.emitBlockedCommand(getMountedTextCommandName(command), [{
-      code: "suggesting_unsupported",
-      message: "List structure changes are not supported in suggesting mode.",
-    }]);
-    return;
-  }
-
-  if (listAwareResult) {
-    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":
-      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:
-    | { type: "insert-text"; text: string }
-    | { type: "delete-backward" }
-    | { type: "delete-forward" }
-    | { type: "insert-tab" }
-    | { type: "outdent-tab" }
-    | { type: "insert-hard-break" }
-    | { type: "split-paragraph" },
-): 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":
-    case "outdent-tab":
-      return "text.insert-tab";
-    case "insert-hard-break":
-      return "text.insert-hard-break";
-    case "split-paragraph":
-      return "paragraph.split";
-  }
-}
-
-function applyListAwareTextCommand(
-  context: NonNullable<ReturnType<typeof getStoryMutationContext>>,
-  command:
-    | { type: "insert-text"; text: string }
-    | { type: "delete-backward" }
-    | { type: "delete-forward" }
-    | { type: "insert-tab" }
-    | { type: "outdent-tab" }
-    | { type: "insert-hard-break" }
-    | { type: "split-paragraph" },
-): {
-  changed: boolean;
-  document: EditorSessionState["canonicalDocument"];
-  selection: InternalSelectionSnapshot;
-} | null {
-  const paragraphContext = resolveActiveParagraphContext(context.localSnapshot);
-  if (!paragraphContext?.paragraph.numbering) {
-    return null;
-  }
-
-  switch (command.type) {
-    case "insert-tab": {
-      const result = indentListItems(
-        context.localDocument,
-        [paragraphContext.paragraphIndex],
-        { timestamp: context.timestamp },
-      );
-      return createListMutationResult(result, context.localSnapshot.selection);
-    }
-    case "outdent-tab": {
-      const result = outdentListItems(
-        context.localDocument,
-        [paragraphContext.paragraphIndex],
-        { timestamp: context.timestamp },
-      );
-      return createListMutationResult(result, context.localSnapshot.selection);
-    }
-    case "delete-backward": {
-      if (!paragraphContext.atParagraphStart || !context.localSnapshot.selection.isCollapsed) {
-        return null;
-      }
-      const result = backspaceAtListStart(
-        context.localDocument,
-        paragraphContext.paragraphIndex,
-        { timestamp: context.timestamp },
-      );
-      return result.handled
-        ? createListMutationResult(result, context.localSnapshot.selection)
-        : null;
-    }
-    case "split-paragraph": {
-      if (!context.localSnapshot.selection.isCollapsed || !paragraphContext.isEmpty) {
-        return null;
-      }
-      const result = splitListParagraph(
-        context.localDocument,
-        paragraphContext.paragraphIndex,
-        true,
-        { timestamp: context.timestamp },
-      );
-      return result.action === "split"
-        ? null
-        : createListMutationResult(result, context.localSnapshot.selection);
-    }
-    default:
-      return null;
-  }
-}
-
-function createListMutationResult(
-  result: {
-    document: EditorSessionState["canonicalDocument"];
-    affectedParagraphIndexes: number[];
-  },
-  selection: RuntimeRenderSnapshot["selection"],
-): {
-  changed: boolean;
-  document: EditorSessionState["canonicalDocument"];
-  selection: InternalSelectionSnapshot;
-} {
-  return {
-    changed: result.affectedParagraphIndexes.length > 0,
-    document: result.document,
-    selection: toRuntimeSelectionSnapshot(selection),
-  };
-}
+const DISPATCH_CONTEXT: DispatchContext = {
+  getStoryMutationContext,
+  dispatchStoryMutationResult,
+  resolveActiveParagraphContext,
+  toRuntimeSelectionSnapshot,
+};
 
 function resolveActiveParagraphContext(
   snapshot: Pick<RuntimeRenderSnapshot, "surface" | "selection">,

package/src/ui/editor-runtime-boundary.ts

@@ -896,7 +896,9 @@ function createLoadingRuntimeBridge(input: {
     openComment: () => undefined,
     resolveComment: () => undefined,
     reopenComment: () => undefined,
-    addCommentReply: () => undefined,
+    addCommentReply: () => {
+      throw createLoadingBoundaryError(input.snapshot.documentId, "comment");
+    },
     editCommentBody: () => undefined,
     acceptChange: () => undefined,
     rejectChange: () => undefined,
@@ -1007,6 +1009,8 @@ function createLoadingRuntimeBridge(input: {
     editorStateChannel: createEditorStateChannel(),
     getPerfCountersSnapshot: () => ({}),
     resetPerfCounters: () => undefined,
+    setVisibleBlockRange: () => undefined,
+    requestViewportRefresh: () => undefined,
   };
 }
 

package/src/ui/runtime-shortcut-dispatch.ts

@@ -2,6 +2,7 @@ import type {
   StyleCatalogSnapshot,
   WorkflowBlockedCommandReason,
 } from "../api/public-types.ts";
+import { CAPABILITY_BY_ID } from "../runtime/editor-surface/capabilities.ts";
 
 export interface ShortcutKeyInput {
   key: string;
@@ -113,87 +114,35 @@ export function resolveShellShortcut(
     return { kind: "delegate", shortcut: "zoom-reset" };
   }
 
-  if (isPasteTextOnlyShortcut(input, key)) {
-    return {
-      kind: "block",
-      command: "pasteTextOnly",
-      reason: createUnsupportedShortcutReason(
-        "Plain-text paste is not supported in the mounted editor yet.",
-      ),
-    };
-  }
-
   if (isReplaceShortcut(input, key)) {
-    return {
-      kind: "block",
-      command: "replaceText",
-      reason: createUnsupportedShortcutReason(
-        "Replace shortcuts are not supported in the mounted editor yet.",
-      ),
-    };
+    return resolveBlockedCapability("replaceText");
   }
 
   if (
     isGoToShortcut(input, key) ||
     (key === "f5" && !input.shiftKey)
   ) {
-    return {
-      kind: "block",
-      command: "goTo",
-      reason: createUnsupportedShortcutReason(
-        "Go To shortcuts are not supported in the mounted editor yet.",
-      ),
-    };
+    return resolveBlockedCapability("goTo");
   }
 
   if (isModShiftShortcut(input, key, "e")) {
-    return {
-      kind: "block",
-      command: "toggleTrackChanges",
-      reason: createUnsupportedShortcutReason(
-        "Track changes authoring shortcuts are not supported in the mounted editor.",
-      ),
-    };
+    return resolveBlockedCapability("toggleTrackChanges");
   }
 
   if (key === "f7" && !input.shiftKey) {
-    return {
-      kind: "block",
-      command: "checkSpelling",
-      reason: createUnsupportedShortcutReason(
-        "Spelling shortcuts are not supported in the mounted editor.",
-      ),
-    };
+    return resolveBlockedCapability("checkSpelling");
   }
 
   if (key === "f7" && input.shiftKey) {
-    return {
-      kind: "block",
-      command: "openThesaurus",
-      reason: createUnsupportedShortcutReason(
-        "Thesaurus shortcuts are not supported in the mounted editor.",
-      ),
-    };
+    return resolveBlockedCapability("openThesaurus");
   }
 
   if (key === "f8") {
-    return {
-      kind: "block",
-      command: "extendSelection",
-      reason: createUnsupportedShortcutReason(
-        "Extend-selection shortcuts are not supported in the mounted editor.",
-      ),
-    };
+    return resolveBlockedCapability("extendSelection");
   }
 
   if (key === "f5" && input.shiftKey) {
-    return {
-      kind: "block",
-      command: "lastEdit",
-      reason: createUnsupportedShortcutReason(
-        "Last-edit shortcuts are not supported in the mounted editor.",
-      ),
-    };
+    return resolveBlockedCapability("lastEdit");
   }
 
   return { kind: "none" };
@@ -262,10 +211,27 @@ export function resolveHeadingShortcutStyleId(
   return null;
 }
 
-function createUnsupportedShortcutReason(message: string): WorkflowBlockedCommandReason {
+/**
+ * Look up a `blocked` capability by id and produce the matching
+ * `ShellShortcutResolution`. The capability's `blockReason` becomes
+ * the dispatcher's returned reason, so editing the user-facing
+ * message in `capabilities.ts` is enough to update every shell-layer
+ * block path — no dispatcher change needed. Throws if the id is not
+ * registered as a blocked capability; the C.1 anchor-check test
+ * guarantees every id this file references is present.
+ */
+function resolveBlockedCapability(id: string): ShellShortcutResolution {
+  const cap = CAPABILITY_BY_ID.get(id);
+  if (!cap || cap.kind !== "blocked" || !cap.blockReason) {
+    throw new Error(
+      `resolveShellShortcut: capability ${id} is not registered as a blocked entry. ` +
+        "See src/runtime/editor-surface/capabilities.ts.",
+    );
+  }
   return {
-    code: "unsupported_surface",
-    message,
+    kind: "block",
+    command: id,
+    reason: cap.blockReason as WorkflowBlockedCommandReason,
   };
 }
 
@@ -357,9 +323,3 @@ function isZoomOutShortcut(input: ShortcutKeyInput, key: string): boolean {
     (key === "-" || key === "_" || key === "subtract");
 }
 
-function isPasteTextOnlyShortcut(input: ShortcutKeyInput, key: string): boolean {
-  return key === "v" &&
-    Boolean(input.ctrlKey || input.metaKey) &&
-    !input.altKey &&
-    Boolean(input.shiftKey);
-}