@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -0,0 +1,1047 @@
+import React, {
+  forwardRef,
+  type FocusEventHandler,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+} from "react";
+import { EditorView } from "prosemirror-view";
+
+import type {
+  DocumentNavigationSnapshot,
+  EditorUser,
+  RuntimeRenderSnapshot,
+  SearchOptions,
+  SearchResultSnapshot,
+  SelectionSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowMetadataMarkup,
+  WorkflowScope,
+} from "../../api/public-types";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import { searchDocument } from "../../runtime/document-search.ts";
+import {
+  getTableSelectionDescriptor,
+  type TableSelectionDescriptor,
+} from "../../runtime/table-commands.ts";
+import {
+  createCommentDecorationModel,
+  type MarkupDisplay,
+} from "../../ui/headless/comment-decoration-model";
+import { createRevisionDecorationModel } from "../../ui/headless/revision-decoration-model";
+import {
+  createPMSelectionFromSnapshot,
+  createPMStateFromSnapshot,
+} from "./pm-state-from-snapshot";
+import type { ActiveSelectionToolModel } from "../../ui/headless/selection-tool-types";
+import {
+  createCommandBridgePlugins,
+  type CommandBridgeCallbacks,
+} from "./pm-command-bridge";
+import { buildDecorations } from "./pm-decorations";
+import { createContextualInteractionPlugin } from "./pm-contextual-ui";
+import {
+  finishPerfProbe,
+  incrementInvalidationCounter,
+  recordPerfSample,
+  startPerfProbe,
+} from "./perf-probe";
+import type { PositionMap } from "./pm-position-map";
+import {
+  clearSearch as clearSearchPlugin,
+  createSearchPlugin,
+  DEFAULT_SEARCH_HIGHLIGHT_COLOR,
+  performSearch,
+  searchPluginKey,
+} from "./search-plugin";
+import {
+  createSurfaceDecorationKey,
+  createSurfaceDocumentBuildKey,
+} from "./surface-build-keys";
+import { tableNodeViews } from "./tw-table-node-view";
+import type { SelectionToolbarAnchor } from "../../ui/headless/selection-toolbar-model";
+import type { MediaPreviewDescriptor } from "./pm-state-from-snapshot";
+
+/**
+ * Same props interface as the legacy TwEditorSurface — drop-in replacement.
+ */
+export interface TwProseMirrorSurfaceProps {
+  currentUser: EditorUser;
+  snapshot: RuntimeRenderSnapshot;
+  canonicalDocument: CanonicalDocumentEnvelope;
+  documentNavigation: DocumentNavigationSnapshot;
+  reviewMode: "editing" | "review";
+  markupDisplay: MarkupDisplay;
+  showUnsupportedObjectPreviews?: boolean;
+  activeRevisionId?: string;
+  activeSelectionToolKind?: ActiveSelectionToolModel["kind"] | null;
+  showTrackedChanges?: boolean;
+  /** When true, the surface renders inside the page workspace (vs canvas). */
+  isPageWorkspace?: boolean;
+  onFocus: FocusEventHandler<HTMLDivElement>;
+  onBlur: FocusEventHandler<HTMLDivElement>;
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  onInsertText?: (text: string) => void;
+  onDeleteBackward?: () => void;
+  onDeleteForward?: () => void;
+  onInsertTab?: () => void;
+  onOutdentTab?: () => void;
+  onInsertHardBreak?: () => void;
+  onSplitParagraph?: () => void;
+  onUndo?: () => void;
+  onRedo?: () => void;
+  onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  onCommentActivated?: (commentId: string) => void;
+  onRevisionActivated?: (revisionId: string) => void;
+  onSelectionToolbarAnchorChange?: (anchor: SelectionToolbarAnchor | null) => void;
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
+  workflowScopes?: readonly WorkflowScope[];
+  workflowCandidates?: readonly WorkflowCandidateRange[];
+  workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[];
+  activeWorkflowWorkItemId?: string | null;
+  activeWorkflowScopeIds?: readonly string[];
+  workflowMetadata?: readonly WorkflowMetadataMarkup[];
+}
+
+export interface TwProseMirrorSurfaceRef {
+  search(query: string, options?: SearchOptions): SearchResultSnapshot[];
+  clearSearch(): void;
+  getTableSelection(): TableSelectionDescriptor | null;
+}
+
+export const TwProseMirrorSurface = forwardRef<
+  TwProseMirrorSurfaceRef,
+  TwProseMirrorSurfaceProps
+>(function TwProseMirrorSurface(props, ref) {
+  const {
+    currentUser,
+    snapshot,
+    markupDisplay,
+    onFocus,
+    onBlur,
+  } = props;
+  const surface = snapshot.surface;
+  const mediaPreviewKey = useMemo(
+    () =>
+      Object.entries(props.mediaPreviews ?? {})
+        .sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
+        .map(
+          ([mediaId, preview]) =>
+            `${mediaId}:${preview.widthEmu ?? ""}:${preview.heightEmu ?? ""}:${preview.src}`,
+        )
+        .join("|"),
+    [props.mediaPreviews],
+  );
+
+  const canEdit = Boolean(
+    surface && snapshot.isReady && !snapshot.readOnly && !snapshot.fatalError,
+  );
+
+  const mountRef = useRef<HTMLDivElement>(null);
+  const viewRef = useRef<EditorView | null>(null);
+  const positionMapRef = useRef<PositionMap | null>(null);
+  const callbacksRef = useRef<CommandBridgeCallbacks | null>(null);
+  const activeSearchRef = useRef<{ query: string; options: SearchOptions } | null>(null);
+  const pendingTypingProbeRef = useRef<string | null>(null);
+  const pendingSelectionProbeRef = useRef<string | null>(null);
+  const documentBuildKeyRef = useRef<string | null>(null);
+  const decorationBuildKeyRef = useRef<string | null>(null);
+  const suppressSelectionEchoRef = useRef(false);
+  const selectionToolbarFrameRef = useRef<number | null>(null);
+  const lastSelectionToolbarMeasurementRef = useRef<{
+    key: string | null;
+    anchor: SelectionToolbarAnchor | null;
+  }>({
+    key: null,
+    anchor: null,
+  });
+
+  // Keep callbacks ref up to date (avoids stale closures in PM plugins)
+  callbacksRef.current = {
+    onInsertText: (text) => {
+      pendingTypingProbeRef.current = startPerfProbe("typing");
+      props.onInsertText?.(text);
+    },
+    onDeleteBackward: () => props.onDeleteBackward?.(),
+    onDeleteForward: () => props.onDeleteForward?.(),
+    onSplitParagraph: () => props.onSplitParagraph?.(),
+    onInsertHardBreak: () => props.onInsertHardBreak?.(),
+    onInsertTab: () => props.onInsertTab?.(),
+    onOutdentTab: () => props.onOutdentTab?.(),
+    onUndo: () => props.onUndo?.(),
+    onRedo: () => props.onRedo?.(),
+    onBlockedInput: (command, message) => {
+      props.onBlockedInput?.(command, message);
+    },
+    onSelectionChange: (sel) => {
+      pendingSelectionProbeRef.current = startPerfProbe("selection");
+      props.onSelectionChange?.(
+        snapshot.activeStory.kind === "main"
+          ? sel
+          : { ...sel, storyTarget: snapshot.activeStory },
+      );
+    },
+    getPositionMap: () => positionMapRef.current,
+    isSelectionSyncSuppressed: () => suppressSelectionEchoRef.current,
+  };
+
+  // Comment/revision decoration models
+  const commentModel = useMemo(
+    () => createCommentDecorationModel(snapshot.comments),
+    [snapshot.comments],
+  );
+  const showTrackedChanges = props.showTrackedChanges !== false;
+  // Always create the revision model — needed for deletion hiding in clean mode
+  // even when the tracked changes display toggle is off.
+  const revisionModel = useMemo(
+    () => createRevisionDecorationModel(snapshot.trackedChanges, props.activeRevisionId),
+    [snapshot.trackedChanges, props.activeRevisionId],
+  );
+  const documentBuildKey = useMemo(
+    () =>
+      createSurfaceDocumentBuildKey({
+        surface,
+        activeStory: snapshot.activeStory,
+        mediaPreviewKey,
+        showUnsupportedObjectPreviews: props.showUnsupportedObjectPreviews,
+      }),
+    [mediaPreviewKey, props.showUnsupportedObjectPreviews, snapshot.activeStory, surface],
+  );
+  const decorationBuildKey = useMemo(
+    () =>
+      createSurfaceDecorationKey({
+        markupDisplay,
+        showTrackedChanges,
+        canEdit,
+        activeCommentId: snapshot.comments.activeCommentId,
+        activeRevisionId: props.activeRevisionId,
+        workflowScopeSignature: createWorkflowScopeSignature(props.workflowScopes),
+        workflowCandidateSignature: createWorkflowCandidateSignature(props.workflowCandidates),
+        workflowBlockedSignature: createWorkflowBlockedSignature(props.workflowBlockedReasons),
+        workflowMetadataSignature: createWorkflowMetadataSignature(props.workflowMetadata),
+        activeWorkflowWorkItemId: props.activeWorkflowWorkItemId ?? null,
+        activeWorkflowScopeIds: props.activeWorkflowScopeIds ?? [],
+      }),
+    [
+      canEdit,
+      markupDisplay,
+      props.activeRevisionId,
+      props.workflowCandidates,
+      props.workflowBlockedReasons,
+      props.workflowMetadata,
+      props.activeWorkflowWorkItemId,
+      props.activeWorkflowScopeIds,
+      props.workflowScopes,
+      showTrackedChanges,
+      snapshot.comments.activeCommentId,
+    ],
+  );
+
+  // Create PM plugins (stable across renders — callbacks accessed via ref)
+  const plugins = useMemo(() => {
+    return [
+      ...createCommandBridgePlugins({
+        onInsertText: (text) => callbacksRef.current?.onInsertText(text),
+        onDeleteBackward: () => callbacksRef.current?.onDeleteBackward(),
+        onDeleteForward: () => callbacksRef.current?.onDeleteForward(),
+        onSplitParagraph: () => callbacksRef.current?.onSplitParagraph(),
+        onInsertHardBreak: () => callbacksRef.current?.onInsertHardBreak(),
+        onInsertTab: () => callbacksRef.current?.onInsertTab(),
+        onOutdentTab: () => callbacksRef.current?.onOutdentTab?.(),
+        onUndo: () => callbacksRef.current?.onUndo(),
+        onRedo: () => callbacksRef.current?.onRedo(),
+        onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
+        onSelectionChange: (sel) => callbacksRef.current?.onSelectionChange(sel),
+        getPositionMap: () => callbacksRef.current?.getPositionMap() ?? null,
+        isSelectionSyncSuppressed: () =>
+          callbacksRef.current?.isSelectionSyncSuppressed?.() ?? false,
+      }),
+      createContextualInteractionPlugin({
+        onCommentActivated: (commentId) => props.onCommentActivated?.(commentId),
+        onRevisionActivated: (revisionId) => props.onRevisionActivated?.(revisionId),
+      }),
+      createSearchPlugin(),
+    ];
+  }, [props.onCommentActivated, props.onRevisionActivated]);
+
+  const applyDecorationProps = useCallback(
+    (view: EditorView, positionMap: PositionMap): void => {
+      const decorations = buildDecorations(
+        view.state.doc,
+        positionMap,
+        commentModel,
+        revisionModel,
+        markupDisplay,
+        showTrackedChanges,
+        props.workflowScopes,
+        snapshot.activeStory,
+        props.workflowCandidates,
+        props.workflowBlockedReasons,
+        props.activeWorkflowWorkItemId,
+        props.activeWorkflowScopeIds,
+        props.workflowMetadata,
+      );
+      view.setProps({
+        editable: () => canEdit,
+        decorations: () => decorations,
+      });
+      decorationBuildKeyRef.current = decorationBuildKey;
+      recordPerfSample("pm.decorations");
+      incrementInvalidationCounter("pm.laneB.decorationUpdates");
+    },
+    [
+      canEdit,
+      commentModel,
+      decorationBuildKey,
+      markupDisplay,
+      props.activeWorkflowScopeIds,
+      props.activeWorkflowWorkItemId,
+      props.workflowBlockedReasons,
+      props.workflowMetadata,
+      props.workflowCandidates,
+      props.workflowScopes,
+      revisionModel,
+      showTrackedChanges,
+    ],
+  );
+
+  // Create or update the PM document only when the structural key changes.
+  useEffect(() => {
+    if (!mountRef.current || !surface) return;
+
+    if (viewRef.current && documentBuildKeyRef.current === documentBuildKey) {
+      return;
+    }
+
+    const { state, positionMap } = createPMStateFromSnapshot(
+      surface,
+      snapshot.selection,
+      plugins,
+      props.mediaPreviews,
+      props.showUnsupportedObjectPreviews,
+    );
+    positionMapRef.current = positionMap;
+    const decorations = buildDecorations(
+      state.doc,
+      positionMap,
+      commentModel,
+      revisionModel,
+      markupDisplay,
+      showTrackedChanges,
+      props.workflowScopes,
+      snapshot.activeStory,
+      props.workflowCandidates,
+      props.workflowBlockedReasons,
+      props.activeWorkflowWorkItemId,
+      props.activeWorkflowScopeIds,
+      props.workflowMetadata,
+    );
+    recordPerfSample("pm.rebuild");
+    incrementInvalidationCounter("pm.laneA.rebuilds");
+
+    if (!viewRef.current) {
+      // First time surface is available — create the EditorView
+      const view = new EditorView(mountRef.current, {
+        state,
+        nodeViews: tableNodeViews,
+        editable: () => canEdit,
+        decorations: () => decorations,
+        dispatchTransaction(tr) {
+          const newState = view.state.apply(tr);
+          view.updateState(newState);
+        },
+      });
+      viewRef.current = view;
+      recordPerfSample("pm.mount");
+    } else {
+      suppressSelectionEchoRef.current = true;
+      viewRef.current.updateState(state);
+      queueMicrotask(() => {
+        suppressSelectionEchoRef.current = false;
+      });
+    }
+    documentBuildKeyRef.current = documentBuildKey;
+    applyDecorationProps(viewRef.current, positionMap);
+
+    if (activeSearchRef.current) {
+      applySearch(
+        activeSearchRef.current.query,
+        activeSearchRef.current.options,
+      );
+    }
+    if (pendingTypingProbeRef.current) {
+      finishPerfProbe(pendingTypingProbeRef.current);
+      pendingTypingProbeRef.current = null;
+    }
+  }, [
+    applyDecorationProps,
+    documentBuildKey,
+    surface,
+    snapshot.selection,
+    plugins,
+    props.mediaPreviews,
+  ]);
+
+  // Update decorations and editability without rebuilding the PM document.
+  useEffect(() => {
+    const view = viewRef.current;
+    const positionMap = positionMapRef.current;
+    if (!view || !surface || !positionMap) {
+      return;
+    }
+
+    if (decorationBuildKeyRef.current === decorationBuildKey) {
+      return;
+    }
+
+    applyDecorationProps(view, positionMap);
+  }, [applyDecorationProps, decorationBuildKey, surface]);
+
+  useEffect(() => {
+    if (!activeSearchRef.current || !surface) {
+      return;
+    }
+    applySearch(activeSearchRef.current.query, activeSearchRef.current.options);
+  }, [
+    markupDisplay,
+    props.canonicalDocument,
+    props.documentNavigation,
+    snapshot.activeStory,
+    snapshot.trackedChanges,
+    surface,
+  ]);
+
+  useEffect(() => {
+    const view = viewRef.current;
+    const positionMap = positionMapRef.current;
+    if (!view || !surface || !positionMap) {
+      return;
+    }
+
+    const nextSelection = createPMSelectionFromSnapshot(
+      view.state.doc,
+      positionMap,
+      snapshot.selection,
+    );
+    if (view.state.selection.eq(nextSelection)) {
+      return;
+    }
+
+    suppressSelectionEchoRef.current = true;
+    view.dispatch(view.state.tr.setSelection(nextSelection));
+    recordPerfSample("selection.sync");
+    queueMicrotask(() => {
+      suppressSelectionEchoRef.current = false;
+    });
+  }, [snapshot.selection, surface]);
+
+  useEffect(() => {
+    if (!pendingSelectionProbeRef.current) {
+      return;
+    }
+    finishPerfProbe(pendingSelectionProbeRef.current);
+    pendingSelectionProbeRef.current = null;
+  }, [snapshot.selection]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      const win = mountRef.current?.ownerDocument.defaultView;
+      if (selectionToolbarFrameRef.current !== null && win) {
+        win.cancelAnimationFrame(selectionToolbarFrameRef.current);
+        selectionToolbarFrameRef.current = null;
+      }
+      viewRef.current?.destroy();
+      viewRef.current = null;
+    };
+  }, []);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      search: (query, options = {}) => {
+        const normalizedQuery = query.trim();
+        if (!normalizedQuery) {
+          activeSearchRef.current = null;
+          clearLiveSearch();
+          return [];
+        }
+
+        activeSearchRef.current = { query: normalizedQuery, options };
+        return applySearch(normalizedQuery, options);
+      },
+      clearSearch: () => {
+        activeSearchRef.current = null;
+        clearLiveSearch();
+      },
+      getTableSelection: () => {
+        const view = viewRef.current;
+        if (!view) {
+          return null;
+        }
+        return getTableSelectionDescriptor(view.state);
+      },
+    }),
+    [
+      markupDisplay,
+      props.canonicalDocument,
+      props.documentNavigation,
+      snapshot.activeStory,
+      snapshot.selection,
+      snapshot.surface,
+      snapshot.trackedChanges,
+    ],
+  );
+
+  function applySearch(query: string, options: SearchOptions): SearchResultSnapshot[] {
+    const view = viewRef.current;
+    const hiddenDeletionRanges =
+      markupDisplay === "clean"
+        ? snapshot.trackedChanges.revisions
+            .filter(
+              (
+                revision,
+              ): revision is typeof revision & {
+                anchor: Extract<typeof revision.anchor, { kind: "range" }>;
+              } =>
+                revision.kind === "deletion" &&
+                revision.status === "active" &&
+                revision.anchor.kind === "range",
+            )
+            .map((revision) => ({
+              from: revision.anchor.from,
+              to: revision.anchor.to,
+            }))
+        : [];
+    if (view) {
+      const rawResults = performSearch(view.state, query, options)
+        .filter((result) => {
+          if (hiddenDeletionRanges.length === 0) {
+            return true;
+          }
+          const positionMap = positionMapRef.current;
+          if (!positionMap) {
+            return true;
+          }
+          const runtimeFrom = positionMap.pmToRuntime(result.from);
+          const runtimeTo = positionMap.pmToRuntime(result.to);
+          return !hiddenDeletionRanges.some(
+            (range) => runtimeFrom < range.to && runtimeTo > range.from,
+          );
+        })
+        .slice(0, options.limit ?? Number.POSITIVE_INFINITY);
+      view.dispatch(
+        view.state.tr.setMeta(searchPluginKey, {
+          results: rawResults,
+          highlightColor: DEFAULT_SEARCH_HIGHLIGHT_COLOR,
+        }),
+      );
+    }
+
+    return filterHiddenDeletionSearchResults(
+      searchDocument(
+        props.canonicalDocument,
+        snapshot.selection,
+        snapshot.activeStory,
+        props.documentNavigation,
+        query,
+        options,
+      ),
+      hiddenDeletionRanges,
+    );
+  }
+
+  function filterHiddenDeletionSearchResults(
+    results: SearchResultSnapshot[],
+    hiddenRanges: Array<{ from: number; to: number }>,
+  ): SearchResultSnapshot[] {
+    if (hiddenRanges.length === 0) {
+      return results;
+    }
+    return results.filter((result) => {
+      const anchor = result.anchor;
+      if (anchor.kind !== "range") {
+        return true;
+      }
+      return !hiddenRanges.some(
+        (range) => anchor.from < range.to && anchor.to > range.from,
+      );
+    });
+  }
+
+  function clearLiveSearch(): void {
+    const view = viewRef.current;
+    if (!view) {
+      return;
+    }
+
+    clearSearchPlugin(view.state, (tr) => {
+      view.dispatch(tr);
+    });
+  }
+
+  const fontClass =
+    markupDisplay === "clean"
+      ? "font-[family-name:var(--font-legal-sans)]"
+      : "font-[family-name:var(--font-legal-serif)]";
+
+  // Story focus indicator — runtime-backed, not DOM-only
+  const storyKind = snapshot.activeStory.kind;
+  const storyFocusAttr = storyKind !== "main" ? storyKind : undefined;
+
+  // Table focus cue — add subtle ring when selection head is inside a table block
+  const tableFocusClass = (() => {
+    if (!surface || !snapshot.selection) return "";
+    const head = snapshot.selection.head;
+    const inTable = surface.blocks.some(
+      (b) => b.kind === "table" && head >= b.from && head <= b.to,
+    );
+    return inTable ? "prosemirror-table-focus" : "";
+  })();
+
+  const workspaceLabel = props.isPageWorkspace ? "Document page" : "Document canvas";
+
+  const selectionToolbarMeasurementKey = useMemo(
+    () =>
+      buildSelectionToolbarMeasurementKey(
+        snapshot.selection,
+        snapshot.activeStory,
+        props.activeSelectionToolKind,
+      ),
+    [props.activeSelectionToolKind, snapshot.activeStory, snapshot.selection],
+  );
+
+  const emitSelectionToolbarAnchor = useCallback((): void => {
+    const callback = props.onSelectionToolbarAnchorChange;
+    if (!callback) {
+      return;
+    }
+
+    const nextAnchor = measureSelectionToolbarAnchor();
+    const previous = lastSelectionToolbarMeasurementRef.current;
+    if (
+      previous.key === selectionToolbarMeasurementKey &&
+      selectionToolbarAnchorsEqual(previous.anchor, nextAnchor)
+    ) {
+      return;
+    }
+
+    lastSelectionToolbarMeasurementRef.current = {
+      key: selectionToolbarMeasurementKey,
+      anchor: nextAnchor,
+    };
+    callback(nextAnchor);
+  }, [
+    props.onSelectionToolbarAnchorChange,
+    selectionToolbarMeasurementKey,
+    snapshot.activeStory,
+    snapshot.selection,
+  ]);
+
+  const scheduleSelectionToolbarAnchorUpdate = useCallback((): void => {
+    const callback = props.onSelectionToolbarAnchorChange;
+    const mount = mountRef.current;
+    const win = mount?.ownerDocument.defaultView;
+    if (!callback || !win) {
+      emitSelectionToolbarAnchor();
+      return;
+    }
+
+    if (selectionToolbarFrameRef.current !== null) {
+      win.cancelAnimationFrame(selectionToolbarFrameRef.current);
+      selectionToolbarFrameRef.current = null;
+    }
+
+    selectionToolbarFrameRef.current = win.requestAnimationFrame(() => {
+      selectionToolbarFrameRef.current = null;
+      emitSelectionToolbarAnchor();
+    });
+  }, [emitSelectionToolbarAnchor, props.onSelectionToolbarAnchorChange]);
+
+  useEffect(() => {
+    scheduleSelectionToolbarAnchorUpdate();
+  }, [
+    props.activeSelectionToolKind,
+    scheduleSelectionToolbarAnchorUpdate,
+    snapshot.revisionToken,
+    snapshot.selection,
+    snapshot.surface,
+    props.isPageWorkspace,
+  ]);
+
+  useEffect(() => {
+    const mount = mountRef.current;
+    const callback = props.onSelectionToolbarAnchorChange;
+    if (!mount || !callback) {
+      return;
+    }
+
+    const updateAnchor = () => {
+      scheduleSelectionToolbarAnchorUpdate();
+    };
+    const scrollRoot = mount.closest<HTMLElement>("[data-wre-scroll-root='true']");
+    const win = mount.ownerDocument.defaultView;
+    const resizeObserver =
+      typeof ResizeObserver !== "undefined"
+        ? new ResizeObserver(() => {
+          updateAnchor();
+        })
+        : null;
+
+    updateAnchor();
+    scrollRoot?.addEventListener("scroll", updateAnchor, { passive: true });
+    win?.addEventListener("resize", updateAnchor);
+    resizeObserver?.observe(mount);
+    if (scrollRoot) {
+      resizeObserver?.observe(scrollRoot);
+    }
+
+    return () => {
+      scrollRoot?.removeEventListener("scroll", updateAnchor);
+      win?.removeEventListener("resize", updateAnchor);
+      resizeObserver?.disconnect();
+    };
+  }, [
+    props.activeSelectionToolKind,
+    props.onSelectionToolbarAnchorChange,
+    scheduleSelectionToolbarAnchorUpdate,
+    snapshot.revisionToken,
+    snapshot.selection,
+  ]);
+
+  useEffect(() => {
+    return () => {
+      lastSelectionToolbarMeasurementRef.current = {
+        key: null,
+        anchor: null,
+      };
+      props.onSelectionToolbarAnchorChange?.(null);
+    };
+  }, [props.onSelectionToolbarAnchorChange]);
+
+  return (
+    <section
+      aria-label={workspaceLabel}
+      className="min-w-0"
+      data-active-story={storyFocusAttr}
+      data-workspace={props.isPageWorkspace ? "page" : "canvas"}
+    >
+      {/* ProseMirror mount point — document content including headings is editable */}
+      {surface ? (
+        <div
+          ref={mountRef}
+          role="textbox"
+          tabIndex={0}
+          aria-multiline="true"
+          className={`px-12 py-10 ${fontClass} text-[15px] text-primary leading-relaxed prosemirror-surface outline-none ${tableFocusClass}`}
+          onFocus={(event) => {
+            onFocus(event);
+            if (event.target === event.currentTarget) {
+              viewRef.current?.focus();
+            }
+          }}
+          onBlur={onBlur as unknown as React.FocusEventHandler<HTMLDivElement>}
+          onKeyDown={(event) => {
+            if (event.target !== event.currentTarget) {
+              return;
+            }
+
+            switch (event.key) {
+              case "Backspace":
+                event.preventDefault();
+                props.onDeleteBackward?.();
+                return;
+              case "Delete":
+                event.preventDefault();
+                props.onDeleteForward?.();
+                return;
+              case "Enter":
+                event.preventDefault();
+                if (event.shiftKey) {
+                  props.onInsertHardBreak?.();
+                } else {
+                  props.onSplitParagraph?.();
+                }
+                return;
+              case "Tab":
+                event.preventDefault();
+                if (event.shiftKey) {
+                  props.onOutdentTab?.();
+                } else {
+                  props.onInsertTab?.();
+                }
+                return;
+              default:
+                return;
+            }
+          }}
+          aria-label="Document surface"
+          data-wre-document-surface="true"
+          data-story-focus={storyFocusAttr}
+        />
+      ) : (
+        <div className="px-12 pb-10">
+          <p className="text-sm text-secondary leading-relaxed">
+            Loading the review surface...
+          </p>
+        </div>
+      )}
+
+      {snapshot.fatalError ? (
+        <div className="px-12 pb-10">
+          <p className="text-sm text-danger">
+            Fatal runtime error: {snapshot.fatalError.message}
+          </p>
+        </div>
+      ) : null}
+    </section>
+  );
+
+  function measureSelectionToolbarAnchor(): SelectionToolbarAnchor | null {
+    const callback = props.onSelectionToolbarAnchorChange;
+    const view = viewRef.current;
+    const mount = mountRef.current;
+    const positionMap = positionMapRef.current;
+    const range = snapshot.selection.activeRange;
+
+    if (!callback || !view || !mount || !positionMap || range.kind === "detached") {
+      return null;
+    }
+
+    const rootRect = mount.getBoundingClientRect();
+    if (rootRect.width <= 0 || rootRect.height <= 0) {
+      return null;
+    }
+
+    try {
+      if (!snapshot.selection.isCollapsed && range.kind === "range") {
+        const pmFrom = positionMap.runtimeToPm(range.from);
+        const pmTo = positionMap.runtimeToPm(range.to);
+        return createSelectionToolbarAnchor(rootRect, view.coordsAtPos(pmFrom), view.coordsAtPos(pmTo));
+      }
+
+      if (
+        range.kind === "node" ||
+        (
+          snapshot.selection.isCollapsed &&
+          range.kind === "range" &&
+          (
+            props.activeSelectionToolKind === "comment-thread" ||
+            props.activeSelectionToolKind === "structure-context"
+          )
+        )
+      ) {
+        const runtimePosition = range.kind === "node" ? range.at : range.from;
+        const pmAt = positionMap.runtimeToPm(runtimePosition);
+        return createSelectionToolbarAnchor(
+          rootRect,
+          view.coordsAtPos(pmAt, -1),
+          view.coordsAtPos(pmAt, 1),
+        );
+      }
+
+      return null;
+    } catch {
+      return null;
+    }
+  }
+});
+
+function createWorkflowScopeSignature(scopes: readonly WorkflowScope[] | undefined): string {
+  if (!scopes || scopes.length === 0) {
+    return "";
+  }
+  return scopes.map((scope) =>
+    [
+      scope.scopeId,
+      scope.mode,
+      scope.workItemId ?? "",
+      serializeAnchorSignature(scope.anchor),
+      serializeStoryTargetSignature(scope.storyTarget),
+    ].join(":")
+  ).join("|");
+}
+
+function createWorkflowCandidateSignature(
+  candidates: readonly WorkflowCandidateRange[] | undefined,
+): string {
+  if (!candidates || candidates.length === 0) {
+    return "";
+  }
+  return candidates.map((candidate) =>
+    [
+      candidate.candidateId,
+      serializeAnchorSignature(candidate.anchor),
+      serializeStoryTargetSignature(candidate.storyTarget),
+      candidate.source ?? "",
+    ].join(":")
+  ).join("|");
+}
+
+function createWorkflowBlockedSignature(
+  blockedReasons: readonly WorkflowBlockedCommandReason[] | undefined,
+): string {
+  if (!blockedReasons || blockedReasons.length === 0) {
+    return "";
+  }
+  return blockedReasons.map((reason) =>
+    [
+      reason.code,
+      reason.scopeId ?? "",
+      reason.workItemId ?? "",
+      serializeAnchorSignature(reason.anchor),
+      serializeStoryTargetSignature(reason.storyTarget),
+    ].join(":")
+  ).join("|");
+}
+
+function createWorkflowMetadataSignature(
+  metadata: readonly WorkflowMetadataMarkup[] | undefined,
+): string {
+  if (!metadata || metadata.length === 0) {
+    return "";
+  }
+  return metadata.map((entry) =>
+    [
+      entry.entryId,
+      entry.metadataId,
+      entry.color ?? "",
+      entry.persistence,
+      serializeAnchorSignature(entry.anchor),
+      serializeStoryTargetSignature(entry.storyTarget),
+      JSON.stringify(entry.value ?? {}),
+    ].join(":")
+  ).join("|");
+}
+
+function serializeAnchorSignature(
+  anchor:
+    | WorkflowScope["anchor"]
+    | WorkflowCandidateRange["anchor"]
+    | WorkflowBlockedCommandReason["anchor"]
+    | WorkflowMetadataMarkup["anchor"]
+    | undefined,
+): string {
+  if (!anchor) {
+    return "";
+  }
+  switch (anchor.kind) {
+    case "range":
+      return `range:${anchor.from}:${anchor.to}:${anchor.assoc.start}:${anchor.assoc.end}`;
+    case "node":
+      return `node:${anchor.at}:${anchor.assoc}`;
+    case "detached":
+      return `detached:${anchor.lastKnownRange.from}:${anchor.lastKnownRange.to}:${anchor.reason}`;
+  }
+}
+
+function serializeStoryTargetSignature(
+  storyTarget:
+    | WorkflowScope["storyTarget"]
+    | WorkflowCandidateRange["storyTarget"]
+    | WorkflowBlockedCommandReason["storyTarget"]
+    | WorkflowMetadataMarkup["storyTarget"],
+): string {
+  if (!storyTarget) {
+    return "";
+  }
+  switch (storyTarget.kind) {
+    case "main":
+      return "main";
+    case "header":
+    case "footer":
+      return `${storyTarget.kind}:${storyTarget.relationshipId}:${storyTarget.variant}:${storyTarget.sectionIndex ?? ""}`;
+    case "footnote":
+    case "endnote":
+      return `${storyTarget.kind}:${storyTarget.noteId}`;
+  }
+}
+
+function buildSelectionToolbarMeasurementKey(
+  selection: SelectionSnapshot,
+  activeStory: RuntimeRenderSnapshot["activeStory"],
+  activeSelectionToolKind?: ActiveSelectionToolModel["kind"] | null,
+): string | null {
+  if (!activeSelectionToolKind || selection.activeRange.kind === "detached") {
+    return null;
+  }
+
+  return JSON.stringify({
+    story: activeStory,
+    tool: activeSelectionToolKind,
+    ...(selection.activeRange.kind === "node"
+      ? { nodeAt: selection.activeRange.at }
+      : {
+          from: selection.activeRange.from,
+          to: selection.activeRange.to,
+          collapsed: selection.isCollapsed,
+        }),
+  });
+}
+
+function createSelectionToolbarAnchor(
+  rootRect: DOMRect,
+  ...rects: Array<Pick<DOMRect, "left" | "right" | "top" | "bottom">>
+): SelectionToolbarAnchor | null {
+  const validRects = rects.filter((rect) =>
+    Number.isFinite(rect.left) &&
+    Number.isFinite(rect.right) &&
+    Number.isFinite(rect.top) &&
+    Number.isFinite(rect.bottom),
+  );
+  if (validRects.length === 0) {
+    return null;
+  }
+
+  let left = Math.max(rootRect.left, Math.min(...validRects.map((rect) => Math.min(rect.left, rect.right))));
+  let right = Math.min(rootRect.right, Math.max(...validRects.map((rect) => Math.max(rect.left, rect.right))));
+  let top = Math.max(rootRect.top, Math.min(...validRects.map((rect) => Math.min(rect.top, rect.bottom))));
+  let bottom = Math.min(rootRect.bottom, Math.max(...validRects.map((rect) => Math.max(rect.top, rect.bottom))));
+
+  if (right <= left) {
+    const centerX = Math.min(rootRect.right, Math.max(rootRect.left, (left + right) / 2 || left));
+    left = Math.max(rootRect.left, centerX - 1);
+    right = Math.min(rootRect.right, centerX + 1);
+  }
+  if (bottom <= top) {
+    const centerY = Math.min(rootRect.bottom, Math.max(rootRect.top, (top + bottom) / 2 || top));
+    top = Math.max(rootRect.top, centerY - 1);
+    bottom = Math.min(rootRect.bottom, centerY + 1);
+  }
+
+  if (
+    !Number.isFinite(left) ||
+    !Number.isFinite(right) ||
+    !Number.isFinite(top) ||
+    !Number.isFinite(bottom) ||
+    right <= left ||
+    bottom <= top ||
+    bottom < rootRect.top ||
+    top > rootRect.bottom
+  ) {
+    return null;
+  }
+
+  return { left, right, top, bottom };
+}
+
+function selectionToolbarAnchorsEqual(
+  left: SelectionToolbarAnchor | null,
+  right: SelectionToolbarAnchor | null,
+): boolean {
+  if (left === right) {
+    return true;
+  }
+  if (!left || !right) {
+    return false;
+  }
+  return (
+    left.left === right.left &&
+    left.right === right.right &&
+    left.top === right.top &&
+    left.bottom === right.bottom
+  );
+}