@beyondwork/docx-react-component 1.0.19 → 1.0.20

package/src/ui/WordReviewEditor.tsx

@@ -7,23 +7,27 @@ import React, {
   useMemo,
   useRef,
   useState,
-  useSyncExternalStore,
 } from "react";
 
 import type {
   AutosaveState,
   CompatibilityReport,
+  DocumentNavigationSnapshot,
+  EditorAnchorProjection,
   EditorDatastoreAdapter,
   EditorHostAdapter,
   EditorSessionState,
   ExportResult,
   EditorError,
   EditorStoryTarget,
+  EditorViewStateSnapshot,
   EditorWarning,
   ExportDocxOptions,
+  FieldSnapshot,
   FormattingAlignment,
   FormattingStateSnapshot,
   HeaderFooterLinkPatch,
+  InteractionGuardSnapshot,
   InsertImageOptions,
   InsertTableOptions,
   PageLayoutSnapshot,
@@ -37,14 +41,21 @@ import type {
   SelectionSnapshot as PublicSelectionSnapshot,
   StyleCatalogSnapshot,
   SurfaceBlockSnapshot,
+  TocRefreshResult,
+  UpdateFieldsResult,
   ViewMode as EditorViewMode,
+  WorkflowBlockedCommandReason,
+  WorkflowScopeSnapshot,
   WordReviewEditorEvent,
   WordReviewEditorProps,
   WordReviewEditorRef,
   WorkspaceMode,
   ZoomLevel,
 } from "../api/public-types";
-import { editorSessionStateFromPersistedSnapshot } from "../api/session-state.ts";
+import {
+  editorSessionStateFromPersistedSnapshot,
+  persistedSnapshotFromEditorSessionState,
+} from "../api/session-state.ts";
 import {
   createDetachedAnchor,
   createNodeAnchor,
@@ -98,81 +109,66 @@ import {
   insertTable as insertTableInDocument,
   splitParagraph as splitParagraphInDocument,
 } from "../core/commands/text-commands.ts";
-import {
-  createCanonicalDocumentId,
-  type SelectionSnapshot as InternalSelectionSnapshot,
-} from "../core/state/editor-state.ts";
-import {
-  createDocumentRuntime,
-  type DocumentRuntime,
-} from "../runtime/document-runtime.ts";
+import { type SelectionSnapshot as InternalSelectionSnapshot } from "../core/state/editor-state.ts";
 import {
   getStoryBlocks,
   replaceStoryBlocks,
 } from "../runtime/story-targeting.ts";
-import { loadDocxEditorSession } from "../io/docx-session.ts";
 import {
   decodePersistedSourcePackageBytes,
   hasValidPersistedSourcePackageDigest,
 } from "../io/source-package-provenance.ts";
+import { readOpcPackage } from "../io/opc/package-reader.ts";
 import { deriveCapabilities } from "../runtime/session-capabilities";
 import { searchDocument } from "../runtime/document-search.ts";
 import {
-  TwProseMirrorSurface,
+  createEditorViewStateSnapshot,
+  createViewState,
+} from "../runtime/view-state.ts";
+import {
   type TwProseMirrorSurfaceRef,
 } from "../ui-tailwind/editor-surface/tw-prosemirror-surface";
-import { TwReviewWorkspace } from "../ui-tailwind/tw-review-workspace";
+import type { MediaPreviewDescriptor } from "../ui-tailwind/editor-surface/pm-state-from-snapshot";
+import {
+  incrementInvalidationCounter,
+  recordPerfSample,
+} from "../ui-tailwind/editor-surface/perf-probe.ts";
 import type { ReviewRailTab } from "../ui-tailwind/review/tw-review-rail";
+import {
+  selectMetaSlice,
+  selectReviewSlice,
+  selectStatusSlice,
+  selectSurfaceSlice,
+  selectToolbarSlice,
+  selectViewSlice,
+  shallowEqualRecord,
+  useRuntimeSnapshotSlice,
+  useRuntimeValue,
+} from "./runtime-snapshot-selectors.ts";
 import type { MarkupDisplay } from "./headless/comment-decoration-model";
 import type {
   SelectionToolbarAnchor,
   SelectionToolbarModel,
 } from "./headless/selection-toolbar-model";
+import { type EditorCommandBag, useCommandBag } from "./editor-command-bag.ts";
+import {
+  type WordReviewEditorRuntime,
+  persistAndExport as persistAndExportFromBoundary,
+  persistSession as persistSessionFromBoundary,
+  rejectExportWhileLoading as rejectExportWhileLoadingFromBoundary,
+  useEditorRuntimeBoundary,
+} from "./editor-runtime-boundary.ts";
 import {
   downloadExportResult,
   withExportDelivery,
 } from "./browser-export";
+import { EditorShellView } from "./editor-shell-view.tsx";
+import { EditorSurfaceController } from "./editor-surface-controller.tsx";
 
-interface ResolvedSource {
-  source: "docx" | "session" | "snapshot";
-  sourceLabel?: string;
-  initialDocx?: Uint8Array | ArrayBuffer;
-  initialSessionState?: EditorSessionState;
-  initialSnapshot?: PersistedEditorSnapshot;
-}
-
-interface CreateRuntimeArgs {
-  documentId: string;
-  readOnly: boolean;
-  source: ResolvedSource;
-  initialViewState?: {
-    workspaceMode?: WorkspaceMode;
-    zoomLevel?: ZoomLevel;
-  };
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  currentUserId?: string;
-}
-
-interface RuntimeLifecycleHandlers {
-  onEvent?: (event: WordReviewEditorEvent) => void;
-  onWarning?: (warning: EditorWarning) => void;
-  onError?: (error: EditorError) => void;
-}
-
-interface WordReviewEditorRuntime extends DocumentRuntime {
-  getFatalError?(): EditorError | undefined;
-  dispose?(): void;
-}
-
-type PackageBackedDocxSession = ReturnType<typeof loadDocxEditorSession>;
-
-interface SnapshotExportBarrier {
-  reason:
-    | "missing_source_package_provenance"
-    | "invalid_source_package_provenance";
-  message: string;
-}
+export {
+  __createFallbackRuntime,
+  __resolveWordReviewEditorSource,
+} from "./editor-runtime-boundary.ts";
 
 const VISUALLY_HIDDEN_STYLES: React.CSSProperties = {
   position: "absolute",
@@ -186,6 +182,15 @@ const VISUALLY_HIDDEN_STYLES: React.CSSProperties = {
   border: 0,
 };
 
+const BROWSER_SAFE_PREVIEW_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/gif",
+  "image/webp",
+  "image/bmp",
+]);
+
 const ACCESSIBLE_REGION_ORDER = [
   "toolbar",
   "document",
@@ -392,13 +397,28 @@ export function __createWordReviewEditorRefBridge(
       runtime.closeStory();
     },
     getPageLayoutSnapshot: () => {
-      return runtime.getPageLayoutSnapshot();
+      return clonePublicValue(runtime.getPageLayoutSnapshot());
     },
     getDocumentNavigationSnapshot: () => {
-      return runtime.getDocumentNavigationSnapshot();
+      return clonePublicValue(runtime.getDocumentNavigationSnapshot());
+    },
+    getFieldSnapshot: () => {
+      return clonePublicValue(runtime.getFieldSnapshot());
+    },
+    updateFields: (options) => {
+      return runtime.updateFields(options);
+    },
+    updateTableOfContents: (options) => {
+      return runtime.updateTableOfContents(options);
     },
     getViewState: () => {
-      return runtime.getViewState();
+      return clonePublicValue(runtime.getViewState());
+    },
+    setDocumentMode: (mode) => {
+      runtime.setDocumentMode(mode);
+    },
+    getProtectionSnapshot: () => {
+      return clonePublicValue(runtime.getProtectionSnapshot());
     },
     setWorkspaceMode: (mode) => {
       runtime.setWorkspaceMode(mode);
@@ -427,195 +447,28 @@ export function __createWordReviewEditorRefBridge(
     setImageFrame: (mediaId, offsets) => {
       applyRuntimeImageReposition(runtime, mediaId, offsets);
     },
-  };
-}
-
-export async function __resolveWordReviewEditorSource(
-  props: Pick<
-    WordReviewEditorProps,
-    | "documentId"
-    | "hostAdapter"
-    | "datastore"
-    | "externalDocSource"
-    | "initialDocx"
-    | "initialSessionState"
-    | "initialSnapshot"
-    | "initialSourceLabel"
-    | "loadRevision"
-    | "loadSourcePolicy"
-  >,
-): Promise<ResolvedSource> {
-  const explicitInitialCount =
-    Number(Boolean(props.initialDocx)) +
-    Number(Boolean(props.initialSessionState)) +
-    Number(Boolean(props.initialSnapshot));
-  if (explicitInitialCount > 1) {
-    throw new Error(
-      "Provide exactly one of initialDocx, initialSessionState, or initialSnapshot.",
-    );
-  }
-
-  if (props.externalDocSource) {
-    if (props.externalDocSource.kind === "docx") {
-      return {
-        source: "docx",
-        initialDocx: props.externalDocSource.bytes,
-        sourceLabel: props.externalDocSource.sourceLabel,
-      };
-    }
-
-    if (props.externalDocSource.kind === "session") {
-      return {
-        source: "session",
-        initialSessionState: props.externalDocSource.sessionState,
-        sourceLabel:
-          props.externalDocSource.sourceLabel ??
-          props.externalDocSource.sessionState.sourcePackage?.sourceLabel,
-      };
-    }
-
-    return {
-      source: "snapshot",
-      initialSnapshot: props.externalDocSource.snapshot,
-      sourceLabel: props.externalDocSource.sourceLabel,
-    };
-  }
-
-  if (props.initialSessionState) {
-    return {
-      source: "session",
-      initialSessionState: props.initialSessionState,
-      sourceLabel:
-        props.initialSourceLabel ??
-        props.initialSessionState.sourcePackage?.sourceLabel,
-    };
-  }
-
-  if (props.initialSnapshot) {
-    return {
-      source: "snapshot",
-      initialSnapshot: props.initialSnapshot,
-      sourceLabel: props.initialSourceLabel,
-    };
-  }
-
-  if (props.initialDocx) {
-    return {
-      source: "docx",
-      initialDocx: props.initialDocx,
-      sourceLabel: props.initialSourceLabel,
-    };
-  }
-
-  const loader = props.hostAdapter?.load ?? props.datastore?.load;
-  if (!loader) {
-    throw new Error(
-      `WordReviewEditor ${props.documentId} needs initialDocx, initialSessionState, initialSnapshot, or a host/datastore load source.`,
-    );
-  }
-
-  const loadResult = await loader({
-    documentId: props.documentId,
-    loadRevision: props.loadRevision,
-    loadSourcePolicy: props.loadSourcePolicy,
-  });
-
-  if (!loadResult.source) {
-    throw new Error(
-      `Host or datastore loader did not return a loadable source for ${props.documentId}.`,
-    );
-  }
-
-  if (loadResult.source.kind === "docx") {
-    return {
-      source: "docx",
-      initialDocx: loadResult.source.bytes,
-      sourceLabel: loadResult.source.sourceLabel,
-    };
-  }
-
-  if (loadResult.source.kind === "session") {
-    return {
-      source: "session",
-      initialSessionState: loadResult.source.sessionState,
-      sourceLabel:
-        loadResult.source.sourceLabel ??
-        loadResult.source.sessionState.sourcePackage?.sourceLabel,
-    };
-  }
-
-  return {
-    source: "snapshot",
-    initialSnapshot: loadResult.source.snapshot,
-    sourceLabel: loadResult.source.sourceLabel,
-  };
-}
-
-export function __createFallbackRuntime(args: CreateRuntimeArgs): WordReviewEditorRuntime {
-  return createRuntime(args);
-}
-
-function createRuntime(
-  args: CreateRuntimeArgs,
-  handlers: RuntimeLifecycleHandlers = {},
-): WordReviewEditorRuntime {
-  const docxSession = args.source.initialDocx
-    ? loadDocxEditorSession({
-        documentId: args.documentId,
-        sourceLabel: args.source.sourceLabel,
-        bytes: args.source.initialDocx,
-        editorBuild: "dev",
-      })
-    : undefined;
-  const snapshotExportResolution = !args.source.initialDocx
-    ? resolvePackageBackedExportSession(args)
-    : undefined;
-  const initialSessionState =
-    args.source.initialSessionState ??
-    docxSession?.initialSessionState ??
-    (args.source.initialSnapshot
-      ? editorSessionStateFromPersistedSnapshot(args.source.initialSnapshot)
-      : editorSessionStateFromPersistedSnapshot(
-          createFallbackPersistedSnapshot(
-            args.documentId,
-            args.source.sourceLabel ?? "Generated shell snapshot",
-          ),
-        ));
-  const runtimeSessionState = snapshotExportResolution?.barrier
-    ? applySessionExportBarrier(initialSessionState, snapshotExportResolution.barrier)
-    : initialSessionState;
-
-  return createDocumentRuntime({
-    documentId: args.documentId,
-    initialSessionState: runtimeSessionState,
-    sourceKind: args.source.source,
-    sourceLabel: args.source.sourceLabel,
-    initialViewState: args.initialViewState,
-    readOnly: args.readOnly || docxSession?.readOnly,
-    editorBuild: runtimeSessionState.editorBuild,
-    fatalError: docxSession?.fatalError,
-    exportDocx: async (sessionState, options) => {
-      if (docxSession) {
-        return docxSession.exportDocx(sessionState, options);
-      }
-
-      if (snapshotExportResolution?.session) {
-        return snapshotExportResolution.session.exportDocx(sessionState, options);
-      }
-
-      throw createSnapshotExportBlockedError(
-        args.documentId,
-        snapshotExportResolution?.barrier ?? {
-          reason: "missing_source_package_provenance",
-          message:
-            "DOCX export is blocked because this session does not carry embedded source package provenance.",
-        },
-      );
+    setWorkflowOverlay: (overlay) => {
+      runtime.setWorkflowOverlay(clonePublicValue(overlay));
     },
-    onWarning: handlers.onWarning,
-    onError: handlers.onError,
-    defaultAuthorId: args.currentUserId,
-  });
+    clearWorkflowOverlay: () => {
+      runtime.clearWorkflowOverlay();
+    },
+    getWorkflowScopeSnapshot: () => {
+      return clonePublicValue(runtime.getWorkflowScopeSnapshot());
+    },
+    getInteractionGuardSnapshot: () => {
+      return clonePublicValue(runtime.getInteractionGuardSnapshot());
+    },
+    getWorkflowMarkupSnapshot: () => {
+      return clonePublicValue(runtime.getWorkflowMarkupSnapshot());
+    },
+    getWorkflowCandidateRanges: (options) => {
+      return clonePublicValue(runtime.getWorkflowCandidateRanges(options));
+    },
+    replaceWorkflowMarkupText: (markupId, text) => {
+      runtime.replaceWorkflowMarkupText(markupId, text);
+    },
+  };
 }
 
 export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditorProps>(
@@ -633,7 +486,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       initialSessionState,
       initialSnapshot,
       initialSourceLabel,
-      markupDisplay = "simple",
+      markupDisplay,
       onError,
       onEvent,
       onWarning,
@@ -642,261 +495,161 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       showReviewPanel = true,
     } = props;
 
-    const [runtime, setRuntime] = useState<WordReviewEditorRuntime | null>(null);
-    const [loadError, setLoadError] = useState<EditorError | null>(null);
     const [activeRailTab, setActiveRailTab] = useState<ReviewRailTab>("comments");
     const [showTrackedChanges, setShowTrackedChanges] = useState(false);
     const [activeRevisionId, setActiveRevisionId] = useState<string | undefined>();
     const [selectionToolbarAnchor, setSelectionToolbarAnchor] = useState<SelectionToolbarAnchor | null>(null);
     const [selectionToolbarDismissedKey, setSelectionToolbarDismissedKey] = useState<string | null>(null);
     const [selectionToolbarFocusWithin, setSelectionToolbarFocusWithin] = useState(false);
-    const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
     const surfaceRef = useRef<TwProseMirrorSurfaceRef | null>(null);
     const selectionToolbarElementRef = useRef<HTMLDivElement | null>(null);
     const shellRef = useRef<HTMLDivElement | null>(null);
     const lastSelectionToolbarKeyRef = useRef<string | null>(null);
     const lastAnnouncedErrorIdRef = useRef<string | null>(null);
-    const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-    const lastSavedRevisionTokenRef = useRef<string | null>(null);
-    const hostAdapterRef = useRef(hostAdapter);
-    const datastoreRef = useRef(datastore);
-    const onEventRef = useRef(onEvent);
-    const onWarningRef = useRef(onWarning);
-    const onErrorRef = useRef(onError);
-    const runtimeViewStateSeedRef = useRef<{
-      workspaceMode: WorkspaceMode;
-      zoomLevel: ZoomLevel;
-    }>({
-      workspaceMode: "canvas",
-      zoomLevel: 100,
-    });
-    const initialSourceRef = useRef<{
-      documentId: string;
-      initialDocx?: Uint8Array | ArrayBuffer;
-      initialSessionState?: EditorSessionState;
-      initialSnapshot?: PersistedEditorSnapshot;
-      initialSourceLabel?: string;
-    } | null>(null);
-
-    if (!initialSourceRef.current || initialSourceRef.current.documentId !== documentId) {
-      initialSourceRef.current = {
-        documentId,
-        initialDocx,
-        initialSessionState,
-        initialSnapshot,
-        initialSourceLabel,
-      };
-    }
-
-    const stableInitialSource = initialSourceRef.current;
-    const sourceReloadKey = externalDocSource
-      ? `external:${externalDocSource.kind}:${externalDocumentRevision ?? "static"}`
-      : stableInitialSource?.initialSessionState
-        ? "initial-session"
-      : stableInitialSource?.initialSnapshot
-        ? "initial-snapshot"
-        : stableInitialSource?.initialDocx
-          ? "initial-docx"
-          : hostAdapter
-            ? `host-adapter:${loadRevision ?? "static"}`
-            : `datastore:${loadRevision ?? "static"}`;
-
-    useEffect(() => {
-      hostAdapterRef.current = hostAdapter;
-      datastoreRef.current = datastore;
-      onEventRef.current = onEvent;
-      onWarningRef.current = onWarning;
-      onErrorRef.current = onError;
-    }, [datastore, hostAdapter, onError, onEvent, onWarning]);
-
-    useEffect(() => {
-      let cancelled = false;
-
-      async function loadRuntime(): Promise<void> {
-        setLoadError(null);
-
-        try {
-          const source = await __resolveWordReviewEditorSource({
-            documentId,
-            hostAdapter: hostAdapterRef.current,
-            datastore: datastoreRef.current,
-            externalDocSource,
-            initialDocx: stableInitialSource?.initialDocx,
-            initialSessionState: stableInitialSource?.initialSessionState,
-            initialSnapshot: stableInitialSource?.initialSnapshot,
-            initialSourceLabel: stableInitialSource?.initialSourceLabel,
-            loadRevision,
-            loadSourcePolicy,
-          });
-
-          if (cancelled) {
-            return;
-          }
-
-          runtimeRef.current?.dispose?.();
-          const nextRuntime = createRuntime(
-            {
-              documentId,
-              readOnly,
-              source,
-              initialViewState: runtimeViewStateSeedRef.current,
-              hostAdapter: hostAdapterRef.current,
-              datastore: datastoreRef.current,
-              currentUserId: currentUser.userId,
-            },
-            {
-              onWarning: onWarningRef.current,
-              onError: onErrorRef.current,
-            },
-          );
-          emitEditorEvent({
-            hostAdapter: hostAdapterRef.current,
-            datastore: datastoreRef.current,
-            onEvent: onEventRef.current,
-            event: createReadyEvent(nextRuntime, source.source),
-          });
-          runtimeRef.current = nextRuntime;
-          setRuntime(nextRuntime);
-        } catch (error) {
-          if (cancelled) {
-            return;
-          }
-
-          const normalized = normalizeEditorError(error);
-          setLoadError(normalized);
-          onErrorRef.current?.(normalized);
-          emitEditorEvent({
-            hostAdapter: hostAdapterRef.current,
-            datastore: datastoreRef.current,
-            onEvent: onEventRef.current,
-            event: {
-              type: "error",
-              documentId,
-              error: normalized,
-            },
-          });
-        }
-      }
-
-      void loadRuntime();
-
-      return () => {
-        cancelled = true;
-      };
-    }, [
-      documentId,
-      readOnly,
-      sourceReloadKey,
-    ]);
-
-    useEffect(() => {
-      if (!runtime?.subscribeToEvents) {
-        return;
-      }
-
-      return runtime.subscribeToEvents((event) => {
-        if (event.type === "export_completed" || event.type === "ready") {
-          return;
-        }
-        emitEditorEvent({
-          hostAdapter: hostAdapterRef.current,
-          datastore: datastoreRef.current,
-          onEvent: onEventRef.current,
-          event,
-        });
-      });
-    }, [runtime]);
-
-    useEffect(() => {
-      return () => {
-        if (autosaveTimerRef.current) {
-          clearTimeout(autosaveTimerRef.current);
-          autosaveTimerRef.current = null;
-        }
-        runtimeRef.current?.dispose?.();
-        runtimeRef.current = null;
-      };
-    }, []);
-
-    const optimisticRuntime = useMemo(
-      () =>
-        __createFallbackRuntime({
-          documentId,
-          readOnly,
-          currentUserId: currentUser.userId,
-          initialViewState: runtimeViewStateSeedRef.current,
-          source: {
-            source:
-              initialSessionState
-                ? "session"
-                : "snapshot",
-            initialSessionState:
-              initialSessionState ??
-              (initialSnapshot
-                ? editorSessionStateFromPersistedSnapshot(initialSnapshot)
-                : undefined),
-            initialSnapshot:
-              initialSnapshot ?? createFallbackPersistedSnapshot(documentId, initialSourceLabel),
-            sourceLabel: guessSourceLabel(
-              initialSourceLabel,
-              initialSessionState,
-              initialSnapshot,
-              externalDocSource,
-            ),
-          },
-          hostAdapter: hostAdapterRef.current,
-          datastore: datastoreRef.current,
-        }),
-      [
-        currentUser.userId,
-        documentId,
-        initialSessionState,
-        initialSnapshot,
-        initialSourceLabel,
-        readOnly,
-        hostAdapter,
-        externalDocSource?.kind,
-        externalDocSource?.sourceLabel,
-      ],
+    const {
+      runtime,
+      loadError,
+      activeRuntime,
+      fallbackSnapshot,
+      loadingSessionState,
+      loadingViewState,
+      loadingNavigation,
+      hostAdapterRef,
+      datastoreRef,
+      onEventRef,
+      onWarningRef,
+      onErrorRef,
+      autosaveTimerRef,
+      lastSavedRevisionTokenRef,
+      runtimeViewStateSeedRef,
+    } = useEditorRuntimeBoundary(props);
+    const metaSlice = useRuntimeSnapshotSlice(
+      runtime,
+      fallbackSnapshot,
+      selectMetaSlice,
+      shallowEqualRecord,
     );
-
-    const fallbackSnapshot = useMemo(
-      () =>
-        loadError
-          ? createErrorSnapshot(documentId, loadError)
-          : createLoadingSnapshot(
-              documentId,
-              readOnly,
-              guessSourceLabel(
-                initialSourceLabel,
-                initialSessionState,
-                initialSnapshot,
-                externalDocSource,
-              ),
-            ),
+    const toolbarSlice = useRuntimeSnapshotSlice(
+      runtime,
+      fallbackSnapshot,
+      selectToolbarSlice,
+      shallowEqualRecord,
+    );
+    const surfaceSlice = useRuntimeSnapshotSlice(
+      runtime,
+      fallbackSnapshot,
+      selectSurfaceSlice,
+      shallowEqualRecord,
+    );
+    const reviewSlice = useRuntimeSnapshotSlice(
+      runtime,
+      fallbackSnapshot,
+      selectReviewSlice,
+      shallowEqualRecord,
+    );
+    const viewSlice = useRuntimeSnapshotSlice(
+      runtime,
+      fallbackSnapshot,
+      selectViewSlice,
+      shallowEqualRecord,
+    );
+    const statusSlice = useRuntimeSnapshotSlice(
+      runtime,
+      fallbackSnapshot,
+      selectStatusSlice,
+      shallowEqualRecord,
+    );
+    const snapshot = useMemo(
+      () => ({
+        documentId: metaSlice.documentId,
+        sessionId: metaSlice.sessionId,
+        sourceLabel: metaSlice.sourceLabel,
+        revisionToken: surfaceSlice.revisionToken,
+        isReady: toolbarSlice.isReady,
+        isDirty: statusSlice.isDirty,
+        readOnly: toolbarSlice.readOnly,
+        documentMode: viewSlice.documentMode,
+        selection: surfaceSlice.selection,
+        activeStory: viewSlice.activeStory,
+        pageLayout: viewSlice.pageLayout,
+        documentStats: statusSlice.documentStats,
+        comments: reviewSlice.comments,
+        trackedChanges: reviewSlice.trackedChanges,
+        compatibility: reviewSlice.compatibility,
+        warnings: statusSlice.warnings,
+        fatalError: statusSlice.fatalError,
+        commandState: toolbarSlice.commandState,
+        surface: surfaceSlice.surface,
+        protectionSnapshot: statusSlice.protectionSnapshot,
+      }),
       [
-        documentId,
-        externalDocSource,
-        initialSessionState,
-        initialSnapshot,
-        initialSourceLabel,
-        loadError,
-        readOnly,
+        metaSlice.documentId,
+        metaSlice.sessionId,
+        metaSlice.sourceLabel,
+        surfaceSlice.revisionToken,
+        surfaceSlice.selection,
+        surfaceSlice.surface,
+        toolbarSlice.isReady,
+        toolbarSlice.readOnly,
+        toolbarSlice.commandState,
+        statusSlice.isDirty,
+        statusSlice.documentStats,
+        statusSlice.warnings,
+        statusSlice.fatalError,
+        statusSlice.protectionSnapshot,
+        reviewSlice.comments,
+        reviewSlice.trackedChanges,
+        reviewSlice.compatibility,
+        viewSlice.documentMode,
+        viewSlice.activeStory,
+        viewSlice.pageLayout,
       ],
     );
-
-    const snapshot = useSyncExternalStore(
-      (listener) => runtime?.subscribe(listener) ?? (() => undefined),
-      () => runtime?.getRenderSnapshot() ?? fallbackSnapshot,
-      () => runtime?.getRenderSnapshot() ?? fallbackSnapshot,
+    const viewState = useRuntimeValue(
+      runtime
+        ? {
+            subscribe: (listener) => runtime.subscribe(listener),
+            getValue: () => runtime.getViewState(),
+          }
+        : null,
+      loadingViewState,
     );
-
-    const activeRuntime = runtime ?? optimisticRuntime;
-    const viewState = activeRuntime.getViewState();
     const isPageWorkspace = viewState.workspaceMode === "page";
-    const liveMarkupDisplay: MarkupDisplay = isPageWorkspace ? "all" : "clean";
-    const canonicalDocument = activeRuntime.getSessionState().canonicalDocument;
-    const documentNavigation = activeRuntime.getDocumentNavigationSnapshot();
+    const liveMarkupDisplay = __resolveLiveMarkupDisplay(markupDisplay, isPageWorkspace);
+    const documentNavigation = useRuntimeValue(
+      runtime
+        ? {
+            subscribe: (listener) => runtime.subscribe(listener),
+            getValue: () => runtime.getDocumentNavigationSnapshot(),
+          }
+        : null,
+      loadingNavigation,
+    );
+    const workflowScopeSnapshot = useRuntimeValue(
+      runtime
+        ? {
+            subscribe: (listener) => runtime.subscribe(listener),
+            getValue: () => runtime.getWorkflowScopeSnapshot(),
+          }
+        : null,
+      null,
+      workflowScopeSnapshotsEqual,
+    );
+    const interactionGuardSnapshot = useRuntimeValue(
+      runtime
+        ? {
+            subscribe: (listener) => runtime.subscribe(listener),
+            getValue: () => runtime.getInteractionGuardSnapshot(),
+          }
+        : null,
+      { blockedReasons: [] } satisfies InteractionGuardSnapshot,
+      interactionGuardSnapshotsEqual,
+    );
+    const sessionState = useMemo(
+      () => (runtime ? runtime.getSessionState() : loadingSessionState),
+      [loadingSessionState, runtime, snapshot.revisionToken],
+    );
+    const canonicalDocument = sessionState.canonicalDocument;
     const effectiveViewMode = deriveEditorViewMode(snapshot.readOnly, reviewMode);
 
     useEffect(() => {
@@ -910,6 +663,11 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       };
     }, [viewState.workspaceMode, viewState.zoomLevel]);
 
+    useEffect(() => {
+      recordPerfSample("shell.render");
+      incrementInvalidationCounter("shell.rerenders");
+    }, [snapshot.revisionToken, snapshot.selection, viewState, documentNavigation]);
+
     useImperativeHandle(
       ref,
       () => ({
@@ -939,7 +697,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         rejectAllChanges: () => activeRuntime.rejectAllChanges(),
         exportDocx: (options) =>
           runtime
-            ? persistAndExport({
+            ? persistAndExportFromBoundary({
                 hostAdapter: hostAdapterRef.current,
                 datastore: datastoreRef.current,
                 documentId,
@@ -950,7 +708,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
                 lastSavedRevisionTokenRef,
                 autosaveTimerRef,
               })
-            : rejectExportWhileLoading({
+            : rejectExportWhileLoadingFromBoundary({
                 documentId,
                 hostAdapter: hostAdapterRef.current,
                 datastore: datastoreRef.current,
@@ -1149,13 +907,28 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           activeRuntime.closeStory();
         },
         getPageLayoutSnapshot: () => {
-          return activeRuntime.getPageLayoutSnapshot();
+          return clonePublicValue(activeRuntime.getPageLayoutSnapshot());
         },
         getDocumentNavigationSnapshot: () => {
-          return activeRuntime.getDocumentNavigationSnapshot();
+          return clonePublicValue(activeRuntime.getDocumentNavigationSnapshot());
+        },
+        getFieldSnapshot: () => {
+          return clonePublicValue(activeRuntime.getFieldSnapshot());
+        },
+        updateFields: (options) => {
+          return activeRuntime.updateFields(options);
+        },
+        updateTableOfContents: (options) => {
+          return activeRuntime.updateTableOfContents(options);
         },
         getViewState: () => {
-          return activeRuntime.getViewState();
+          return clonePublicValue(activeRuntime.getViewState());
+        },
+        setDocumentMode: (mode) => {
+          activeRuntime.setDocumentMode(mode);
+        },
+        getProtectionSnapshot: () => {
+          return clonePublicValue(activeRuntime.getProtectionSnapshot());
         },
         setWorkspaceMode: (mode) => {
           activeRuntime.setWorkspaceMode(mode);
@@ -1184,6 +957,27 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         setImageFrame: (mediaId, offsets) => {
           applyRuntimeImageReposition(activeRuntime, mediaId, offsets);
         },
+        setWorkflowOverlay: (overlay) => {
+          activeRuntime.setWorkflowOverlay(clonePublicValue(overlay));
+        },
+        clearWorkflowOverlay: () => {
+          activeRuntime.clearWorkflowOverlay();
+        },
+        getWorkflowScopeSnapshot: () => {
+          return clonePublicValue(activeRuntime.getWorkflowScopeSnapshot());
+        },
+        getInteractionGuardSnapshot: () => {
+          return clonePublicValue(activeRuntime.getInteractionGuardSnapshot());
+        },
+        getWorkflowMarkupSnapshot: () => {
+          return clonePublicValue(activeRuntime.getWorkflowMarkupSnapshot());
+        },
+        getWorkflowCandidateRanges: (options) => {
+          return clonePublicValue(activeRuntime.getWorkflowCandidateRanges(options));
+        },
+        replaceWorkflowMarkupText: (markupId, text) => {
+          activeRuntime.replaceWorkflowMarkupText(markupId, text);
+        },
       }),
       [activeRuntime, currentUser.userId, documentId, runtime],
     );
@@ -1213,7 +1007,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
 
       const debounceMs = props.autosave?.debounceMs ?? 800;
       if (debounceMs <= 0) {
-        void persistSession({
+        void persistSessionFromBoundary({
           hostAdapter: hostAdapterRef.current,
           datastore: datastoreRef.current,
           documentId,
@@ -1227,7 +1021,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       }
 
       autosaveTimerRef.current = setTimeout(() => {
-        void persistSession({
+        void persistSessionFromBoundary({
           hostAdapter: hostAdapterRef.current,
           datastore: datastoreRef.current,
           documentId,
@@ -1301,7 +1095,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
 
     function exportCurrentDocument(): void {
       void (runtime
-        ? persistAndExport({
+        ? persistAndExportFromBoundary({
             hostAdapter: hostAdapterRef.current,
             datastore: datastoreRef.current,
             documentId,
@@ -1311,7 +1105,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
             lastSavedRevisionTokenRef,
             autosaveTimerRef,
           })
-        : rejectExportWhileLoading({
+        : rejectExportWhileLoadingFromBoundary({
             documentId,
             hostAdapter: hostAdapterRef.current,
             datastore: datastoreRef.current,
@@ -1320,20 +1114,89 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           }));
     }
 
-    const derivedCapabilities = deriveCapabilities(snapshot, reviewMode);
+    const derivedCapabilities = deriveCapabilities(
+      snapshot,
+      reviewMode,
+      workflowScopeSnapshot,
+    );
     const capabilities = showReviewPanel
       ? derivedCapabilities
       : { ...derivedCapabilities, reviewRailVisible: false };
     const formattingState = getFormattingStateFromRenderSnapshot(snapshot);
     const styleCatalog = useMemo(
-      () => getRuntimeStyleCatalog(activeRuntime),
-      [activeRuntime, snapshot.revisionToken],
+      () => getRuntimeStyleCatalog(canonicalDocument.styles),
+      [canonicalDocument.styles],
     );
     const diagnosticsModeMessage = getDiagnosticsModeMessage(loadError ?? snapshot.fatalError);
     const addCommentDisabledReason =
       !capabilities.canAddComment && !snapshot.selection.isCollapsed
         ? "Select text within one paragraph to add a DOCX comment."
         : undefined;
+    const activeImageContext = useMemo(
+      () =>
+        buildActiveImageContext({
+          canonicalDocument,
+          selection: snapshot.selection,
+          storyTarget: viewState.activeStory,
+          surface: snapshot.surface,
+        }),
+      [canonicalDocument, snapshot.selection, snapshot.surface, viewState.activeStory],
+    );
+    const sourcePackage = sessionState.sourcePackage;
+    const mediaPreviewCatalogKey = Object.values(canonicalDocument.media.items)
+      .map((item) =>
+        [
+          item.mediaId,
+          item.packagePartName,
+          item.contentType ?? "",
+          item.widthEmu ?? "",
+          item.heightEmu ?? "",
+        ].join(":"),
+      )
+      .sort()
+      .join("|");
+    const mediaPreviews = useMemo(() => {
+      if (!sourcePackage) {
+        return {} as Record<string, MediaPreviewDescriptor>;
+      }
+      try {
+        const bytes = decodePersistedSourcePackageBytes(sourcePackage);
+        if (!hasValidPersistedSourcePackageDigest(sourcePackage, bytes)) {
+          return {} as Record<string, MediaPreviewDescriptor>;
+        }
+        const opc = readOpcPackage(bytes);
+        const previews: Record<string, MediaPreviewDescriptor> = {};
+        for (const item of Object.values(canonicalDocument.media.items)) {
+          const contentType = item.contentType?.toLowerCase();
+          const part = opc.parts.get(item.packagePartName);
+          if (
+            !part?.bytes ||
+            !contentType ||
+            !BROWSER_SAFE_PREVIEW_TYPES.has(contentType)
+          ) {
+            continue;
+          }
+          previews[item.mediaId] = {
+            src: createImageDataUrl(contentType, part.bytes),
+            ...(item.widthEmu !== undefined ? { widthEmu: item.widthEmu } : {}),
+            ...(item.heightEmu !== undefined ? { heightEmu: item.heightEmu } : {}),
+          };
+        }
+        return previews;
+      } catch {
+        return {} as Record<string, MediaPreviewDescriptor>;
+      }
+    }, [mediaPreviewCatalogKey, sourcePackage?.sha256Hex]);
+    const activeObjectContext = useMemo(
+      () =>
+        viewState.activeObjectFrame && viewState.activeObjectFrame.kind !== "image"
+          ? {
+            kind: viewState.activeObjectFrame.kind,
+            display: viewState.activeObjectFrame.display,
+          }
+          : null,
+      [viewState.activeObjectFrame],
+    );
     const selectionToolbar = buildSelectionToolbarModel({
       snapshot,
       viewState,
@@ -1609,131 +1472,202 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       },
     };
 
+    const commands = useCommandBag<EditorCommandBag>({
+      ...reviewCallbacks,
+      onWorkspaceModeChange: (mode) => activeRuntime.setWorkspaceMode(mode),
+      onZoomChange: (level) => activeRuntime.setZoom(level),
+      onActiveRailTabChange: setActiveRailTab,
+      onShowTrackedChangesChange: setShowTrackedChanges,
+      onToggleBold: () =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "bold" }),
+      onToggleItalic: () =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "italic" }),
+      onToggleUnderline: () =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "underline" }),
+      onSetSelectionTextColor: (color) =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "set-text-color", color }),
+      onSetSelectionHighlightColor: (color) =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "set-highlight-color", color }),
+      onToggleStrikethrough: () =>
+        applyRuntimeFormattingOperation(activeRuntime, {
+          type: "toggle",
+          mark: "strikethrough",
+        }),
+      onToggleSuperscript: () =>
+        applyRuntimeFormattingOperation(activeRuntime, {
+          type: "toggle",
+          mark: "superscript",
+        }),
+      onToggleSubscript: () =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "subscript" }),
+      onSetFontFamily: (fontFamily) =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "set-font-family", fontFamily }),
+      onSetFontSize: (fontSize) =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "set-font-size", size: fontSize }),
+      onSetTextColor: (color) =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "set-text-color", color }),
+      onSetHighlightColor: (color) =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "set-highlight-color", color }),
+      onSetAlignment: (alignment) =>
+        applyRuntimeFormattingOperation(activeRuntime, { type: "set-alignment", alignment }),
+      onSetParagraphStyle: (styleId) => applyRuntimeParagraphStyle(activeRuntime, styleId),
+      onOutdent: () => applyRuntimeFormattingOperation(activeRuntime, { type: "outdent" }),
+      onIndent: () => applyRuntimeFormattingOperation(activeRuntime, { type: "indent" }),
+      onInsertPageBreak: () => applyRuntimeInsertPageBreak(activeRuntime),
+      onInsertTable: () => applyRuntimeInsertTable(activeRuntime, { rows: 3, columns: 3 }),
+      onInsertSectionBreak: (type) => applyRuntimeInsertSectionBreak(activeRuntime, type),
+      onInsertImage: (options) => applyRuntimeInsertImage(activeRuntime, options),
+      onSetTableStyle: (styleId) => applyRuntimeTableStyle(activeRuntime, styleId),
+      onAddRowBefore: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "add-row-before",
+        }),
+      onAddRowAfter: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "add-row-after",
+        }),
+      onAddColumnBefore: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "add-column-before",
+        }),
+      onAddColumnAfter: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "add-column-after",
+        }),
+      onDeleteRow: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "delete-row",
+        }),
+      onDeleteColumn: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "delete-column",
+        }),
+      onDeleteTable: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "delete-table",
+        }),
+      onMergeCells: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "merge-cells",
+        }),
+      onSplitCell: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "split-cell",
+        }),
+      onSetCellBackground: (color) =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current ?? null, {
+          type: "set-cell-background",
+          color,
+        }),
+      onSetImageLayout: (mediaId, dimensions) =>
+        applyRuntimeImageResize(activeRuntime, mediaId, dimensions),
+      onSetImageFrame: (mediaId, offsets) =>
+        applyRuntimeImageReposition(activeRuntime, mediaId, offsets),
+      onOpenHeaderStory: () =>
+        openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "header"),
+      onOpenFooterStory: () =>
+        openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "footer"),
+      onDeleteSectionBreak: (sectionIndex) =>
+        applyRuntimeDeleteSectionBreak(activeRuntime, sectionIndex),
+      onUpdateSectionLayout: (sectionIndex, patch) =>
+        applyRuntimeUpdateSectionLayout(activeRuntime, sectionIndex, patch),
+      onSetSectionPageNumbering: (sectionIndex, patch) =>
+        applyRuntimeSetSectionPageNumbering(activeRuntime, sectionIndex, patch),
+      onSetHeaderFooterLink: (sectionIndex, patch) =>
+        applyRuntimeSetHeaderFooterLink(activeRuntime, sectionIndex, patch),
+      onSetParagraphIndentation: (indentation) =>
+        applyRuntimeParagraphIndentation(activeRuntime, indentation),
+      onSetParagraphTabStops: (tabStops) =>
+        applyRuntimeParagraphTabStops(activeRuntime, tabStops),
+      onRestartNumbering: () =>
+        applyRuntimeNumberingFlow(activeRuntime, { type: "restart" }),
+      onContinueNumbering: () =>
+        applyRuntimeNumberingFlow(activeRuntime, { type: "continue" }),
+      onNavigateHeading: (headingId) => {
+        const heading = documentNavigation.headings.find(
+          (entry) => entry.headingId === headingId,
+        );
+        if (!heading) {
+          return;
+        }
+        applyRuntimeSelection(
+          activeRuntime,
+          createCollapsedPublicSelection(heading.offset),
+        );
+      },
+    });
+
+    const documentElement = (
+      <EditorSurfaceController
+        ref={surfaceRef}
+        currentUser={currentUser}
+        snapshot={snapshot}
+        canonicalDocument={canonicalDocument}
+        documentNavigation={documentNavigation}
+        reviewMode={reviewMode}
+        markupDisplay={liveMarkupDisplay}
+        activeRevisionId={activeRevisionId}
+        showTrackedChanges={showTrackedChanges}
+        mediaPreviews={mediaPreviews}
+        isPageWorkspace={isPageWorkspace}
+        workflowScopes={workflowScopeSnapshot?.scopes}
+        onSelectionToolbarAnchorChange={handleSelectionToolbarAnchorChange}
+        {...editorCallbacks}
+        onCommentActivated={(commentId) => {
+          activeRuntime.openComment(commentId);
+          setActiveRailTab("comments");
+        }}
+        onRevisionActivated={(revisionId) => {
+          setActiveRevisionId(revisionId);
+          setActiveRailTab("changes");
+        }}
+      />
+    );
+
     return (
-      <div
-        ref={shellRef}
-        role="region"
-        aria-label={`Word review editor for ${snapshot.sourceLabel ?? documentId}`}
-        aria-describedby={`${accessibilityInstructionsId} ${accessibilityStatusId}${
-          diagnosticsModeMessage ? ` ${accessibilityAlertId}` : ""
-        }`}
-        className="relative h-full"
-        onKeyDownCapture={handleShellKeyDownCapture}
-      >
-        <p id={accessibilityInstructionsId} style={VISUALLY_HIDDEN_STYLES}>
-          Press F6 to move focus between the toolbar, document surface, review rail, and status bar.
-        </p>
-        <div
-          id={accessibilityStatusId}
-          role="status"
-          aria-live="polite"
-          aria-atomic="true"
-          style={VISUALLY_HIDDEN_STYLES}
-        >
-          {buildAccessibilityStatusMessage(snapshot, loadError ?? undefined)}
-        </div>
-        {diagnosticsModeMessage ? (
-          <div
-            id={accessibilityAlertId}
-            data-wre-alert="true"
-            role="alert"
-            aria-live="assertive"
-            aria-atomic="true"
-            tabIndex={-1}
-            className="border-b border-danger/30 bg-danger/5 px-4 py-3 text-sm text-danger"
-          >
-            {diagnosticsModeMessage}
-          </div>
-        ) : null}
-        <TwReviewWorkspace
-          snapshot={snapshot}
-          viewState={viewState}
-          currentUserId={currentUser.userId}
-          capabilities={capabilities}
-          documentNavigation={documentNavigation}
-          reviewMode={reviewMode}
-          workspaceMode={viewState.workspaceMode}
-          zoomLevel={viewState.zoomLevel}
-          formattingState={formattingState}
-          styleCatalog={styleCatalog}
-          activeRailTab={activeRailTab}
-          activeCommentId={snapshot.comments.activeCommentId}
-          activeRevisionId={activeRevisionId}
-          showTrackedChanges={showTrackedChanges}
-          selectionToolbar={shouldRenderSelectionToolbar ? selectionToolbar : null}
-          selectionToolbarAnchor={shouldRenderSelectionToolbar ? selectionToolbarAnchor : null}
-          onAddCommentFromSelection={addSelectionToolbarComment}
-          onDismissSelectionToolbar={() => dismissSelectionToolbar("chrome-action")}
-          onSelectionToolbarFocusCapture={handleSelectionToolbarFocusCapture}
-          onSelectionToolbarBlurCapture={handleSelectionToolbarBlurCapture}
-          selectionToolbarRef={selectionToolbarElementRef}
-          onWorkspaceModeChange={(mode) => activeRuntime.setWorkspaceMode(mode)}
-          onZoomChange={(level) => activeRuntime.setZoom(level)}
-          onActiveRailTabChange={setActiveRailTab}
-          onShowTrackedChangesChange={setShowTrackedChanges}
-          onToggleBold={() =>
-            applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "bold" })}
-          onToggleItalic={() =>
-            applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "italic" })}
-          onToggleUnderline={() =>
-            applyRuntimeFormattingOperation(activeRuntime, { type: "toggle", mark: "underline" })}
-          onSetParagraphStyle={(styleId) =>
-            applyRuntimeParagraphStyle(activeRuntime, styleId)}
-          onOutdent={() =>
-            applyRuntimeFormattingOperation(activeRuntime, { type: "outdent" })}
-          onIndent={() =>
-            applyRuntimeFormattingOperation(activeRuntime, { type: "indent" })}
-          onOpenHeaderStory={() =>
-            openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "header")}
-          onOpenFooterStory={() =>
-            openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "footer")}
-          onSetParagraphIndentation={(indentation) =>
-            applyRuntimeParagraphIndentation(activeRuntime, indentation)
-          }
-          onSetParagraphTabStops={(tabStops) =>
-            applyRuntimeParagraphTabStops(activeRuntime, tabStops)
-          }
-          onRestartNumbering={() => applyRuntimeNumberingFlow(activeRuntime, { type: "restart" })}
-          onContinueNumbering={() => applyRuntimeNumberingFlow(activeRuntime, { type: "continue" })}
-          onNavigateHeading={(headingId) => {
-            const heading = documentNavigation.headings.find(
-              (entry) => entry.headingId === headingId,
-            );
-            if (!heading) {
-              return;
-            }
-            applyRuntimeSelection(
-              activeRuntime,
-              createCollapsedPublicSelection(heading.offset),
-            );
-          }}
-          {...reviewCallbacks}
-          document={
-            <TwProseMirrorSurface
-              ref={surfaceRef}
-              currentUser={currentUser}
-              snapshot={snapshot}
-              canonicalDocument={canonicalDocument}
-              documentNavigation={documentNavigation}
-              reviewMode={reviewMode}
-              markupDisplay={liveMarkupDisplay}
-              activeRevisionId={activeRevisionId}
-              showTrackedChanges={showTrackedChanges}
-              isPageWorkspace={isPageWorkspace}
-              onSelectionToolbarAnchorChange={handleSelectionToolbarAnchorChange}
-              {...editorCallbacks}
-              onCommentActivated={(commentId) => {
-                activeRuntime.openComment(commentId);
-                setActiveRailTab("comments");
-              }}
-              onRevisionActivated={(revisionId) => {
-                setActiveRevisionId(revisionId);
-                setActiveRailTab("changes");
-              }}
-            />
-          }
-        />
-      </div>
+      <EditorShellView
+        shellRef={shellRef}
+        documentId={documentId}
+        snapshot={snapshot}
+        loadError={loadError}
+        diagnosticsModeMessage={diagnosticsModeMessage}
+        accessibilityInstructionsId={accessibilityInstructionsId}
+        accessibilityStatusId={accessibilityStatusId}
+        accessibilityAlertId={accessibilityAlertId}
+        accessibilityStatusMessage={buildAccessibilityStatusMessage(
+          snapshot,
+          loadError ?? undefined,
+        )}
+        visuallyHiddenStyles={VISUALLY_HIDDEN_STYLES}
+        onShellKeyDownCapture={handleShellKeyDownCapture}
+        viewState={viewState}
+        markupDisplay={liveMarkupDisplay}
+        currentUserId={currentUser.userId}
+        capabilities={capabilities}
+        documentNavigation={documentNavigation}
+        reviewMode={reviewMode}
+        workspaceMode={viewState.workspaceMode}
+        zoomLevel={viewState.zoomLevel}
+        formattingState={formattingState}
+        styleCatalog={styleCatalog}
+        activeRailTab={activeRailTab}
+        activeCommentId={snapshot.comments.activeCommentId}
+        activeRevisionId={activeRevisionId}
+        showTrackedChanges={showTrackedChanges}
+        workflowScopeSnapshot={workflowScopeSnapshot}
+        interactionGuardSnapshot={interactionGuardSnapshot}
+        selectionToolbar={shouldRenderSelectionToolbar ? selectionToolbar : null}
+        selectionToolbarAnchor={shouldRenderSelectionToolbar ? selectionToolbarAnchor : null}
+        onAddCommentFromSelection={addSelectionToolbarComment}
+        onDismissSelectionToolbar={() => dismissSelectionToolbar("chrome-action")}
+        onSelectionToolbarFocusCapture={handleSelectionToolbarFocusCapture}
+        onSelectionToolbarBlurCapture={handleSelectionToolbarBlurCapture}
+        selectionToolbarRef={selectionToolbarElementRef}
+        activeImageContext={activeImageContext}
+        activeObjectContext={activeObjectContext}
+        commands={commands}
+        document={documentElement}
+      />
     );
   },
 );
@@ -1772,9 +1706,14 @@ function applyRuntimeFormattingOperation(
 }
 
 function getRuntimeStyleCatalog(
-  runtime: WordReviewEditorRuntime,
+  input:
+    | WordReviewEditorRuntime
+    | EditorSessionState["canonicalDocument"]["styles"],
 ): StyleCatalogSnapshot {
-  const styles = runtime.getSessionState().canonicalDocument.styles;
+  const styles =
+    "getSessionState" in input
+      ? input.getSessionState().canonicalDocument.styles
+      : input;
   const mapRecord = <
     T extends {
       styleId: string;
@@ -2233,24 +2172,28 @@ function applyRuntimeImageReposition(
   mediaId: string,
   offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number },
 ): void {
-  const snapshot = runtime.getRenderSnapshot();
-  if (!canApplyRuntimeMutation(snapshot)) {
+  const context = getStoryMutationContext(runtime);
+  if (!context) {
     return;
   }
 
   try {
-    const sessionState = runtime.getSessionState();
     const result = repositionFloatingImageInDocument(
-      sessionState.canonicalDocument,
+      context.localDocument,
       mediaId,
       offsets,
+      context.timestamp,
+    );
+    dispatchStoryMutationResult(
+      runtime,
+      context,
+      {
+        changed: true,
+        document: result.document,
+        selection: toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+      },
+      context.timestamp,
     );
-    runtime.dispatch({
-      type: "document.replace",
-      document: result.document,
-      selection: toRuntimeSelectionSnapshot(snapshot.selection),
-      origin: { source: "api", timestamp: new Date().toISOString() },
-    });
   } catch {
     return;
   }
@@ -2758,6 +2701,13 @@ function normalizeRequestedSelection(
   );
 }
 
+export function __resolveLiveMarkupDisplay(
+  requested: MarkupDisplay | undefined,
+  isPageWorkspace: boolean,
+): MarkupDisplay {
+  return requested ?? (isPageWorkspace ? "all" : "clean");
+}
+
 function createCollapsedPublicSelection(
   position: number,
   storyTarget?: EditorStoryTarget,
@@ -3008,60 +2958,6 @@ function guessSourceLabel(
   );
 }
 
-function createLoadingSnapshot(
-  documentId: string,
-  readOnly: boolean,
-  sourceLabel?: string,
-): RuntimeRenderSnapshot {
-  return {
-    documentId,
-    sessionId: `${documentId}-loading`,
-    sourceLabel,
-    revisionToken: `${documentId}:loading`,
-    isReady: false,
-    isDirty: false,
-    readOnly,
-    selection: collapsedSelection(),
-    activeStory: { kind: "main" },
-    documentStats: {
-      storyLength: 0,
-      commentCount: 0,
-      revisionCount: 0,
-      opaqueFragmentCount: 0,
-    },
-    comments: {
-      openCommentIds: [],
-      resolvedCommentIds: [],
-      detachedCommentIds: [],
-      totalCount: 0,
-      threads: [],
-    },
-    trackedChanges: {
-      pendingChangeIds: [],
-      acceptedChangeIds: [],
-      rejectedChangeIds: [],
-      detachedChangeIds: [],
-      actionableChangeIds: [],
-      preserveOnlyChangeIds: [],
-      totalCount: 0,
-      revisions: [],
-    },
-    compatibility: {
-      blockExport: false,
-      blockExportReasons: [],
-      warningCount: 0,
-      errorCount: 0,
-      featureEntries: [],
-    },
-    warnings: [],
-    commandState: {
-      canUndo: false,
-      canRedo: false,
-      readOnly,
-    },
-  };
-}
-
 function deriveEditorViewMode(
   readOnly: boolean,
   reviewMode: WordReviewEditorProps["reviewMode"] = "review",
@@ -3072,636 +2968,6 @@ function deriveEditorViewMode(
   return reviewMode === "editing" ? "editing" : "review";
 }
 
-function createErrorSnapshot(documentId: string, error: EditorError): RuntimeRenderSnapshot {
-  return {
-    ...createLoadingSnapshot(documentId, true),
-    isReady: true,
-    sessionId: `${documentId}-error`,
-    revisionToken: `${documentId}:error`,
-    compatibility: {
-      blockExport: true,
-      blockExportReasons: [error.message],
-      warningCount: 0,
-      errorCount: 1,
-      featureEntries: [],
-    },
-    fatalError: error,
-  };
-}
-
-async function persistAndExport(input: {
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  documentId: string;
-  runtime: WordReviewEditorRuntime;
-  onError?: (error: EditorError) => void;
-  onEvent?: (event: WordReviewEditorEvent) => void;
-  options?: ExportDocxOptions;
-  lastSavedRevisionTokenRef: React.MutableRefObject<string | null>;
-  autosaveTimerRef: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
-}): Promise<ExportResult> {
-  if (input.autosaveTimerRef.current) {
-    clearTimeout(input.autosaveTimerRef.current);
-    input.autosaveTimerRef.current = null;
-  }
-
-  await persistSession({
-    hostAdapter: input.hostAdapter,
-    datastore: input.datastore,
-    documentId: input.documentId,
-    runtime: input.runtime,
-    isAutosave: false,
-    onError: input.onError,
-    onEvent: input.onEvent,
-    lastSavedRevisionTokenRef: input.lastSavedRevisionTokenRef,
-  });
-
-  let result: ExportResult;
-  try {
-    result = await input.runtime.exportDocx(input.options);
-  } catch (error) {
-    const normalized = normalizeExportError(error, input.documentId, input.options);
-    input.onError?.(normalized);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "error",
-        documentId: input.documentId,
-        error: normalized,
-      },
-    });
-    throw normalized;
-  }
-
-  const saveExport = input.hostAdapter?.saveExport ?? input.datastore?.saveExport;
-  const saveExportSource = input.hostAdapter?.saveExport ? "host" : "datastore";
-  if (!saveExport) {
-    result = downloadExportResult(result);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "export_completed",
-        documentId: input.documentId,
-        result,
-      },
-    });
-    return result;
-  }
-
-  try {
-    const saveResult = await saveExport({
-      documentId: input.documentId,
-      result,
-    });
-    result = withExportDelivery(result, {
-      mode: "persisted-by-host",
-      savedAt: saveResult.savedAt,
-    });
-  } catch (error) {
-    const normalized = normalizeStorageError(error, {
-      message: "Export persisted bytes could not be stored.",
-      source: saveExportSource,
-      details: {
-        operation: "saveExport",
-      },
-    });
-    input.onError?.(normalized);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "error",
-        documentId: input.documentId,
-        error: normalized,
-      },
-    });
-    result = withExportDelivery(result, {
-      mode: "exported-bytes-only",
-    });
-  }
-
-  emitEditorEvent({
-    hostAdapter: input.hostAdapter,
-    datastore: input.datastore,
-    onEvent: input.onEvent,
-    event: {
-      type: "export_completed",
-      documentId: input.documentId,
-      result,
-    },
-  });
-
-  return result;
-}
-
-function rejectExportWhileLoading(input: {
-  documentId: string;
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  onError?: (error: EditorError) => void;
-  onEvent?: (event: WordReviewEditorEvent) => void;
-}): Promise<never> {
-  const error: EditorError = {
-    errorId: "word-review-editor-loading-export",
-    code: "internal_invariant",
-    message: "WordReviewEditor is still loading and cannot export yet.",
-    isFatal: false,
-    source: "runtime",
-  };
-  input.onError?.(error);
-  emitEditorEvent({
-    hostAdapter: input.hostAdapter,
-    datastore: input.datastore,
-    onEvent: input.onEvent,
-    event: {
-      type: "error",
-      documentId: input.documentId,
-      error,
-    },
-  });
-  return Promise.reject(error);
-}
-
-async function persistSession(input: {
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  documentId: string;
-  runtime: WordReviewEditorRuntime;
-  isAutosave: boolean;
-  onError?: (error: EditorError) => void;
-  onEvent?: (event: WordReviewEditorEvent) => void;
-  lastSavedRevisionTokenRef: React.MutableRefObject<string | null>;
-}): Promise<void> {
-  const saveSession = input.hostAdapter?.saveSession;
-  const saveSnapshot = input.datastore?.saveSnapshot;
-  if (!saveSession && !saveSnapshot) {
-    return;
-  }
-
-  const sessionState = input.runtime.getSessionState();
-  const snapshot = input.runtime.getPersistedSnapshot();
-  const revisionToken = input.runtime.getRenderSnapshot().revisionToken;
-
-  if (input.isAutosave) {
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "autosave_state",
-        documentId: input.documentId,
-        state: {
-          status: "saving",
-        } satisfies AutosaveState,
-      },
-    });
-  }
-
-  try {
-    const result = saveSession
-      ? await saveSession({
-          documentId: input.documentId,
-          sessionState,
-          isAutosave: input.isAutosave,
-        })
-      : await saveSnapshot!({
-          documentId: input.documentId,
-          snapshot,
-          isAutosave: input.isAutosave,
-        });
-    input.lastSavedRevisionTokenRef.current = revisionToken;
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: saveSession
-        ? {
-            type: "session_saved",
-            documentId: input.documentId,
-            sessionState: input.runtime.getSessionState(),
-            savedAt: result.savedAt,
-            isAutosave: input.isAutosave,
-          }
-        : {
-            type: "snapshot_saved",
-            documentId: input.documentId,
-            snapshot: {
-              ...snapshot,
-              savedAt: result.savedAt,
-            },
-            isAutosave: input.isAutosave,
-          },
-    });
-    if (input.isAutosave) {
-      emitEditorEvent({
-        hostAdapter: input.hostAdapter,
-        datastore: input.datastore,
-        onEvent: input.onEvent,
-        event: {
-          type: "autosave_state",
-          documentId: input.documentId,
-          state: {
-            status: "saved",
-            savedAt: result.savedAt,
-          } satisfies AutosaveState,
-        },
-      });
-    }
-  } catch (error) {
-    const normalized = normalizeStorageError(error, {
-      message: input.isAutosave
-        ? saveSession
-          ? "Autosave failed while storing the editor session."
-          : "Autosave failed while storing the editor snapshot."
-        : saveSession
-          ? "Session save failed while preparing the export checkpoint."
-          : "Snapshot save failed while preparing the export checkpoint.",
-      source: saveSession ? "host" : "datastore",
-      details: {
-        operation: saveSession ? "saveSession" : "saveSnapshot",
-        isAutosave: input.isAutosave,
-      },
-    });
-    input.onError?.(normalized);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "error",
-        documentId: input.documentId,
-        error: normalized,
-      },
-    });
-    if (input.isAutosave) {
-      emitEditorEvent({
-        hostAdapter: input.hostAdapter,
-        datastore: input.datastore,
-        onEvent: input.onEvent,
-        event: {
-          type: "autosave_state",
-          documentId: input.documentId,
-          state: {
-            status: "error",
-            error: normalized,
-          } satisfies AutosaveState,
-        },
-      });
-    }
-    if (!input.isAutosave) {
-      throw normalized;
-    }
-  }
-}
-
-function emitEditorEvent(input: {
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  onEvent?: (event: WordReviewEditorEvent) => void;
-  event: WordReviewEditorEvent;
-}): void {
-  input.onEvent?.(input.event);
-  const logEvent = input.hostAdapter?.logEvent ?? input.datastore?.logEvent;
-  logEvent?.({
-    type: input.event.type,
-    documentId: input.event.documentId,
-    detail: summarizeEventDetail(input.event),
-  });
-}
-
-function summarizeEventDetail(
-  event: WordReviewEditorEvent,
-): Record<string, unknown> | undefined {
-  switch (event.type) {
-    case "dirty_changed":
-      return { isDirty: event.isDirty };
-    case "comment_added":
-      return { commentId: event.commentId };
-    case "comment_resolved":
-      return { commentId: event.commentId };
-    case "change_accepted":
-    case "change_rejected":
-      return { changeId: event.changeId };
-    case "warning_added":
-      return { warningId: event.warning.warningId, code: event.warning.code };
-    case "warning_cleared":
-      return { warningId: event.warningId, code: event.code };
-    case "error":
-      return { errorId: event.error.errorId, code: event.error.code };
-    case "autosave_state":
-      return { status: event.state.status };
-    case "snapshot_saved":
-      return { isAutosave: event.isAutosave, savedAt: event.snapshot.savedAt };
-    case "session_saved":
-      return { isAutosave: event.isAutosave, savedAt: event.savedAt };
-    case "export_completed":
-      return {
-        fileName: event.result.fileName,
-        deliveryMode: event.result.delivery?.mode,
-        savedAt: event.result.delivery?.savedAt,
-      };
-    case "story_changed":
-      return { activeStory: event.activeStory };
-    case "selection_changed":
-      return {
-        anchor: event.selection.anchor,
-        head: event.selection.head,
-      };
-    case "ready":
-      return {
-        source: event.source,
-        blockExport: event.compatibility.blockExport,
-      };
-  }
-}
-
-function createReadyEvent(
-  runtime: Pick<WordReviewEditorRuntime, "getCompatibilityReport" | "getRenderSnapshot">,
-  source: "docx" | "session" | "snapshot",
-): Extract<WordReviewEditorEvent, { type: "ready" }> {
-  const snapshot = runtime.getRenderSnapshot();
-  return {
-    type: "ready",
-    documentId: snapshot.documentId,
-    sessionId: snapshot.sessionId,
-    source,
-    stats: snapshot.documentStats,
-    compatibility: runtime.getCompatibilityReport(),
-    comments: snapshot.comments,
-    trackedChanges: snapshot.trackedChanges,
-  };
-}
-
-function normalizeStorageError(
-  error: unknown,
-  fallback: {
-    message: string;
-    source: "host" | "datastore";
-    details?: Record<string, unknown>;
-  },
-): EditorError {
-  if (
-    typeof error === "object" &&
-    error !== null &&
-    "errorId" in error &&
-    "code" in error &&
-    "message" in error
-  ) {
-    return error as EditorError;
-  }
-
-  return {
-    errorId:
-      fallback.source === "host"
-        ? "word-review-editor-host"
-        : "word-review-editor-datastore",
-    code: "datastore_failed",
-    message: error instanceof Error ? error.message : fallback.message,
-    isFatal: false,
-    source: fallback.source === "host" ? "host" : "datastore",
-    details: fallback.details,
-  };
-}
-
-function createFallbackSnapshot(args: CreateRuntimeArgs): RuntimeRenderSnapshot {
-  const initialSessionState =
-    args.source.initialSessionState ??
-    (args.source.initialSnapshot
-      ? editorSessionStateFromPersistedSnapshot(args.source.initialSnapshot)
-      : undefined);
-  const warnings = initialSessionState?.warningLog ?? [];
-  const compatibility = initialSessionState?.compatibility ?? emptyCompatibilityReport();
-
-  return {
-    ...createLoadingSnapshot(args.documentId, args.readOnly, args.source.sourceLabel),
-    sessionId: `${args.documentId}-session`,
-    revisionToken: `${args.documentId}:0`,
-    isReady: true,
-    documentStats: {
-      storyLength: estimateStoryLength(initialSessionState ?? args.source.initialSnapshot),
-      commentCount: 0,
-      revisionCount: 0,
-      opaqueFragmentCount: 0,
-    },
-    compatibility: {
-      blockExport: compatibility.blockExport,
-      blockExportReasons: [],
-      warningCount: compatibility.warnings.length,
-      errorCount: compatibility.errors.length,
-      featureEntries: compatibility.featureEntries,
-    },
-    warnings,
-  };
-}
-
-function createFallbackPersistedSnapshot(
-  documentId: string,
-  label = "Generated shell snapshot",
-): PersistedEditorSnapshot {
-  const docId = createCanonicalDocumentId(documentId);
-  return {
-    snapshotVersion: "persisted-editor-snapshot/2",
-    schemaVersion: "cds/1.0.0",
-    documentId,
-    docId,
-    createdAt: "1970-01-01T00:00:00.000Z",
-    updatedAt: "1970-01-01T00:00:00.000Z",
-    savedAt: "1970-01-01T00:00:00.000Z",
-    editorBuild: label,
-    canonicalDocument: {
-      schemaVersion: "cds/1.0.0",
-      docId,
-      createdAt: "1970-01-01T00:00:00.000Z",
-      updatedAt: "1970-01-01T00:00:00.000Z",
-      metadata: {
-        customProperties: {},
-      },
-      styles: {
-        paragraphs: {},
-        characters: {},
-        tables: {},
-      },
-      numbering: {
-        abstractDefinitions: {},
-        instances: {},
-      },
-      media: {
-        items: {},
-      },
-      content: {
-        type: "doc",
-        children: [{ type: "paragraph", children: [] }],
-      },
-      review: {
-        comments: {},
-        revisions: {},
-      },
-      preservation: {
-        opaqueFragments: {},
-        packageParts: {},
-      },
-      diagnostics: {
-        warnings: [],
-        errors: [],
-      },
-    },
-    compatibility: emptyCompatibilityReport(),
-    warningLog: [],
-  };
-}
-
-function emptyCompatibilityReport(): CompatibilityReport {
-  return {
-    reportVersion: "compatibility-report/1",
-    generatedAt: "1970-01-01T00:00:00.000Z",
-    blockExport: false,
-    featureEntries: [],
-    warnings: [],
-    errors: [],
-  };
-}
-
-function resolvePackageBackedExportSession(args: CreateRuntimeArgs): {
-  session?: PackageBackedDocxSession;
-  barrier?: SnapshotExportBarrier;
-} {
-  const sourcePackage =
-    args.source.initialSessionState?.sourcePackage ??
-    args.source.initialSnapshot?.sourcePackage;
-  if (!sourcePackage) {
-    return {
-      barrier: {
-        reason: "missing_source_package_provenance",
-        message:
-          "DOCX export is blocked because this session was loaded without embedded source package provenance.",
-      },
-    };
-  }
-
-  try {
-    const bytes = decodePersistedSourcePackageBytes(sourcePackage);
-    if (!hasValidPersistedSourcePackageDigest(sourcePackage, bytes)) {
-      return {
-        barrier: {
-          reason: "invalid_source_package_provenance",
-          message:
-            "DOCX export is blocked because the embedded source package provenance failed its integrity check.",
-        },
-      };
-    }
-
-    const session = loadDocxEditorSession({
-      documentId: args.documentId,
-      sourceLabel: sourcePackage.sourceLabel ?? args.source.sourceLabel,
-      bytes,
-      editorBuild:
-        args.source.initialSessionState?.editorBuild ??
-        args.source.initialSnapshot?.editorBuild ??
-        "dev",
-    });
-    if (session.readOnly || session.fatalError) {
-      return {
-        barrier: {
-          reason: "invalid_source_package_provenance",
-          message:
-            "DOCX export is blocked because the embedded source package provenance is no longer loadable as a valid package-backed session.",
-        },
-      };
-    }
-
-    return { session };
-  } catch {
-    return {
-      barrier: {
-        reason: "invalid_source_package_provenance",
-        message:
-          "DOCX export is blocked because the embedded source package provenance could not be decoded into a package-backed session.",
-      },
-    };
-  }
-}
-
-function applySessionExportBarrier(
-  sessionState: EditorSessionState,
-  barrier: SnapshotExportBarrier,
-): EditorSessionState {
-  const featureEntryId = `feature:source-package-provenance:${barrier.reason}`;
-  const featureEntries = sessionState.compatibility.featureEntries.some(
-    (entry) => entry.featureEntryId === featureEntryId,
-  )
-    ? sessionState.compatibility.featureEntries
-    : [
-        ...sessionState.compatibility.featureEntries,
-        {
-          featureEntryId,
-          featureKey: "source-package-provenance",
-          featureClass: "unsupported-fatal" as const,
-          message: barrier.message,
-          details: {
-            reason: barrier.reason,
-          },
-        },
-      ];
-
-  return {
-    ...sessionState,
-    compatibility: {
-      ...sessionState.compatibility,
-      blockExport: true,
-      featureEntries,
-    },
-  };
-}
-
-function createSnapshotExportBlockedError(
-  documentId: string,
-  barrier: SnapshotExportBarrier,
-): EditorError {
-  return {
-    errorId: `${documentId}:export:${barrier.reason}`,
-    code: "export_failed",
-    message: barrier.message,
-    isFatal: false,
-    source: "export",
-    details: {
-      reason: barrier.reason,
-    },
-  };
-}
-
-function normalizeExportError(
-  error: unknown,
-  documentId: string,
-  options?: ExportDocxOptions,
-): EditorError {
-  if (
-    typeof error === "object" &&
-    error !== null &&
-    "errorId" in error &&
-    "code" in error &&
-    "message" in error
-  ) {
-    return error as EditorError;
-  }
-
-  return {
-    errorId: `${documentId}:export:failed`,
-    code: "export_failed",
-    message:
-      error instanceof Error ? error.message : "DOCX export failed for an unknown reason.",
-    isFatal: false,
-    source: "export",
-    details: {
-      requestedOptions: options ?? {},
-    },
-  };
-}
-
 function toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot) {
   return {
     anchor: selection.anchor,
@@ -3825,6 +3091,102 @@ function selectionToolbarAnchorsEqual(
   );
 }
 
+function workflowScopeSnapshotsEqual(
+  left: WorkflowScopeSnapshot | null,
+  right: WorkflowScopeSnapshot | null,
+): boolean {
+  if (left === right) {
+    return true;
+  }
+  if (!left || !right) {
+    return false;
+  }
+  return (
+    left.overlayPresent === right.overlayPresent &&
+    left.activeWorkItemId === right.activeWorkItemId &&
+    left.activeWorkItem === right.activeWorkItem &&
+    left.scopes === right.scopes &&
+    left.candidates === right.candidates &&
+    workflowBlockedReasonsEqual(left.blockedReasons, right.blockedReasons)
+  );
+}
+
+function interactionGuardSnapshotsEqual(
+  left: InteractionGuardSnapshot,
+  right: InteractionGuardSnapshot,
+): boolean {
+  if (left === right) {
+    return true;
+  }
+  return workflowBlockedReasonsEqual(left.blockedReasons, right.blockedReasons);
+}
+
+function workflowBlockedReasonsEqual(
+  left: readonly WorkflowBlockedCommandReason[],
+  right: readonly WorkflowBlockedCommandReason[],
+): boolean {
+  if (left === right) {
+    return true;
+  }
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    if (!workflowBlockedReasonEqual(left[index]!, right[index]!)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function workflowBlockedReasonEqual(
+  left: WorkflowBlockedCommandReason,
+  right: WorkflowBlockedCommandReason,
+): boolean {
+  return (
+    left.code === right.code &&
+    left.message === right.message &&
+    left.scopeId === right.scopeId &&
+    left.workItemId === right.workItemId &&
+    editorAnchorProjectionEqual(left.anchor, right.anchor) &&
+    storyTargetsEqual(left.storyTarget, right.storyTarget)
+  );
+}
+
+function editorAnchorProjectionEqual(
+  left: EditorAnchorProjection | undefined,
+  right: EditorAnchorProjection | undefined,
+): boolean {
+  if (left === right) {
+    return true;
+  }
+  if (!left || !right || left.kind !== right.kind) {
+    return false;
+  }
+
+  switch (left.kind) {
+    case "range":
+      return (
+        right.kind === "range" &&
+        left.from === right.from &&
+        left.to === right.to &&
+        left.assoc.start === right.assoc.start &&
+        left.assoc.end === right.assoc.end
+      );
+    case "node":
+      return right.kind === "node" && left.at === right.at && left.assoc === right.assoc;
+    case "detached":
+      return (
+        right.kind === "detached" &&
+        left.lastKnownRange.from === right.lastKnownRange.from &&
+        left.lastKnownRange.to === right.lastKnownRange.to &&
+        left.reason === right.reason
+      );
+  }
+
+  return false;
+}
+
 function createSelectionToolbarSelectionKey(
   selection: RuntimeRenderSnapshot["selection"],
   activeStory: EditorStoryTarget,
@@ -3948,3 +3310,176 @@ function createSelectionToolbarListBadge(
     label: viewState.activeListContext.isOrdered ? "Numbered list" : "Bulleted list",
   };
 }
+
+function buildActiveImageContext(args: {
+  canonicalDocument: PersistedEditorSnapshot["canonicalDocument"];
+  selection: RuntimeRenderSnapshot["selection"];
+  storyTarget: EditorStoryTarget;
+  surface?: RuntimeRenderSnapshot["surface"];
+}): {
+  mediaId: string;
+  display: "inline" | "floating";
+  widthEmu?: number;
+  heightEmu?: number;
+  horizontalOffsetEmu?: number;
+  verticalOffsetEmu?: number;
+} | null {
+  const imageSegment = findSelectedImageSegment(args.surface, args.selection);
+  if (!imageSegment) {
+    return null;
+  }
+
+  const storyBlocks = getStoryBlocks(args.canonicalDocument, args.storyTarget);
+  const imageNode = findImageNodeByMediaId(storyBlocks, imageSegment.mediaId);
+  const mediaItem = args.canonicalDocument.media.items[imageSegment.mediaId];
+
+  return {
+    mediaId: imageSegment.mediaId,
+    display: imageSegment.display === "floating" ? "floating" : "inline",
+    widthEmu: mediaItem?.widthEmu,
+    heightEmu: mediaItem?.heightEmu,
+    horizontalOffsetEmu: imageNode?.floating?.horizontalPosition?.offset,
+    verticalOffsetEmu: imageNode?.floating?.verticalPosition?.offset,
+  };
+}
+
+function findSelectedImageSegment(
+  surface: RuntimeRenderSnapshot["surface"] | undefined,
+  selection: RuntimeRenderSnapshot["selection"],
+): Extract<NonNullable<RuntimeRenderSnapshot["surface"]>["blocks"][number], { kind: "paragraph" }>["segments"][number] & {
+  kind: "image";
+} | null {
+  if (!surface) {
+    return null;
+  }
+
+  const position =
+    selection.activeRange.kind === "node" ? selection.activeRange.at : selection.head;
+
+  return findSelectedImageSegmentInBlocks(surface.blocks, position);
+}
+
+function findSelectedImageSegmentInBlocks(
+  blocks: readonly SurfaceBlockSnapshot[],
+  position: number,
+): Extract<NonNullable<RuntimeRenderSnapshot["surface"]>["blocks"][number], { kind: "paragraph" }>["segments"][number] & {
+  kind: "image";
+} | null {
+  for (const block of blocks) {
+    if (position < block.from || position > block.to) {
+      continue;
+    }
+
+    if (block.kind === "paragraph") {
+      const imageSegment = block.segments.find(
+        (segment) => segment.kind === "image" && position >= segment.from && position <= segment.to,
+      );
+      if (imageSegment && imageSegment.kind === "image") {
+        return imageSegment;
+      }
+      continue;
+    }
+
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const match = findSelectedImageSegmentInBlocks(cell.content, position);
+          if (match) {
+            return match;
+          }
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      const match = findSelectedImageSegmentInBlocks(block.children, position);
+      if (match) {
+        return match;
+      }
+    }
+  }
+
+  return null;
+}
+
+function findImageNodeByMediaId(blocks: readonly unknown[], mediaId: string): {
+  floating?: {
+    horizontalPosition?: { offset?: number };
+    verticalPosition?: { offset?: number };
+  };
+} | null {
+  for (const block of blocks) {
+    const match = findImageNodeInValue(block, mediaId);
+    if (match) {
+      return match;
+    }
+  }
+  return null;
+}
+
+function findImageNodeInValue(
+  value: unknown,
+  mediaId: string,
+): {
+  floating?: {
+    horizontalPosition?: { offset?: number };
+    verticalPosition?: { offset?: number };
+  };
+} | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const record = value as {
+    type?: string;
+    mediaId?: string;
+    children?: unknown[];
+    rows?: Array<{ cells?: Array<{ children?: unknown[] }> }>;
+    floating?: {
+      horizontalPosition?: { offset?: number };
+      verticalPosition?: { offset?: number };
+    };
+  };
+
+  if (record.type === "image" && record.mediaId === mediaId) {
+    return record;
+  }
+
+  if (Array.isArray(record.children)) {
+    for (const child of record.children) {
+      const match = findImageNodeInValue(child, mediaId);
+      if (match) {
+        return match;
+      }
+    }
+  }
+
+  if (Array.isArray(record.rows)) {
+    for (const row of record.rows) {
+      for (const cell of row.cells ?? []) {
+        for (const child of cell.children ?? []) {
+          const match = findImageNodeInValue(child, mediaId);
+          if (match) {
+            return match;
+          }
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+function createImageDataUrl(contentType: string, bytes: Uint8Array): string {
+  const base64 = bytesToBase64(bytes);
+  return `data:${contentType};base64,${base64}`;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    binary += String.fromCharCode(bytes[index] ?? 0);
+  }
+  return btoa(binary);
+}