@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -1,8 +1,5 @@
 import React, {
   type CSSProperties,
-  type FocusEventHandler,
-  type ReactNode,
-  type Ref,
   useCallback,
   useEffect,
   useMemo,
@@ -11,41 +8,8 @@ import React, {
 } from "react";
 
 import * as Tooltip from "@radix-ui/react-tooltip";
-import { ChevronLeft, ChevronRight, List } from "lucide-react";
+import { ChevronRight } from "lucide-react";
 
-import type {
-  ActiveListContext,
-  CommentSidebarThreadSnapshot,
-  DocumentNavigationSnapshot,
-  EditorAnchorProjection,
-  EditorStoryTarget,
-  EditorViewStateSnapshot,
-  FormattingStateSnapshot,
-  FormattingAlignment,
-  HeaderFooterLinkPatch,
-  InteractionGuardSnapshot,
-  InsertImageOptions,
-  RuntimeContextAnalyticsSnapshot,
-  RuntimeRenderSnapshot,
-  ReviewQueueSnapshot,
-  SectionPageNumberingPatch,
-  SectionBreakType,
-  StyleCatalogSnapshot,
-  SurfaceBlockSnapshot,
-  TrackedChangeEntrySnapshot,
-  WordReviewEditorChromeOptions,
-  WordReviewEditorChromePreset,
-  WordReviewEditorChromeVisibility,
-  WorkflowScopeSnapshot,
-  WorkspaceMode,
-  ZoomLevel,
-} from "../api/public-types";
-import { createCanvasBackend } from "../runtime/layout/index.ts";
-import { DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP } from "../runtime/page-layout-estimation.ts";
-import {
-  incrementInvalidationCounter,
-  recordPerfSample,
-} from "./editor-surface/perf-probe.ts";
 import {
   useVisibleBlockRange,
   useVisiblePageIndexRange,
@@ -57,384 +21,110 @@ import {
 } from "./editor-surface/scroll-anchor.ts";
 import { TwPageBlockView } from "./editor-surface/tw-page-block-view.tsx";
 import { computeLineMarkersIfEnabled } from "./page-chrome-model.ts";
-import type { SessionCapabilities } from "../runtime/session-capabilities";
-import type {
-  ActiveSelectionToolModel,
-  SelectionToolAnchor,
-} from "../ui/headless/selection-tool-types";
-import type { MarkupDisplay } from "../ui/headless/comment-decoration-model";
-import {
-  resolveScopedChromePolicy,
-  shouldRenderSelectionToolKind,
-} from "../ui/headless/scoped-chrome-policy";
+import { shouldRenderSelectionToolKind } from "../ui/headless/scoped-chrome-policy";
 import type { EditorCommandBag } from "../ui/editor-command-bag.ts";
 import { preserveEditorSelectionMouseDown } from "../ui/headless/preserve-editor-selection";
 import { TwAlertBanner } from "./chrome/tw-alert-banner";
-import { TwModeDock } from "./chrome/tw-mode-dock";
 import { TwLayoutPanel } from "./chrome/tw-layout-panel";
 import { TwPageRuler } from "./chrome/tw-page-ruler";
-import {
-  getInitialReviewRailOpen,
-  isNarrowChromeViewport,
-  resolveResponsiveChromeState,
-} from "./chrome/responsive-chrome";
 import { ChromePresetToolbar } from "./chrome/chrome-preset-toolbar";
 import {
   resolveChromePreset,
   resolveChromePresetOptions,
   resolveChromeVisibilityForPreset,
-} from "./chrome/chrome-preset-model";
+} from "../api/v3/ui/chrome-preset-model";
 import { TwSelectionToolHost } from "./chrome/tw-selection-tool-host";
-import { resolveSelectionAnchor } from "./chrome/tw-selection-anchor-resolver";
-import { resolveSelectionToolPlacement } from "./chrome/tw-selection-tool-placement";
-import { TwReviewRail, type ReviewRailTab } from "./review/tw-review-rail";
+import { type ReviewRailTab } from "./review/tw-review-rail";
+import {
+  TwReviewWorkspaceRail,
+  type TwReviewWorkspaceRailMode,
+} from "./review-workspace/tw-review-workspace-rail.tsx";
 import { TwStatusBar } from "./status/tw-status-bar";
-import { type ToolbarInteractionPolicy } from "./toolbar/tw-toolbar";
+import {
+  TwShellHeader,
+  type ShellHeaderMode,
+  type ShellHeaderModeOption,
+} from "./toolbar/tw-shell-header";
+import { TwContextBand } from "./chrome/tw-context-band";
+import { TwRoleActionRegion } from "./toolbar/tw-role-action-region";
+import { LocalSurfaceArbiterContext } from "./chrome/local-surface-arbiter";
+import { TwWorkspaceChromeHost } from "./chrome/tw-workspace-chrome-host";
 import { TwChromeOverlay, TwPageStackOverlayLayer } from "./chrome-overlay";
 import { TwFloatingImageLayer } from "./page-stack/tw-floating-image-layer.tsx";
-import type { MediaPreviewDescriptor } from "./editor-surface/pm-state-from-snapshot.ts";
-import {
-  cycleScopeIndex,
-  shouldHandleScopeNavKey,
-} from "./chrome-overlay/scope-keyboard-cycle";
-
-export type ReviewWorkspaceChromeVisibility = WordReviewEditorChromeVisibility;
+import { shouldHidePageBorderForSelection } from "./review-workspace/paragraph-layout.ts";
+import { useSelectionToolbarPlacement } from "./review-workspace/use-selection-toolbar-placement.ts";
+import { useShellSelectionAnchorBridge } from "./review-workspace/use-shell-selection-anchor-bridge.ts";
+import { useChromePolicy } from "./review-workspace/use-chrome-policy.ts";
+import { useStatusBarPageFacts } from "./review-workspace/use-status-bar-page-facts.ts";
+import { useGrabbedSegmentOffsets } from "./review-workspace/use-grabbed-segment-offsets.ts";
+import { useDerivedViewState } from "./review-workspace/use-derived-view-state.ts";
+import { useReviewRailState } from "./review-workspace/use-review-rail-state.ts";
+import { useWorkspaceSideEffects } from "./review-workspace/use-workspace-side-effects.ts";
+import { useViewportDimensions } from "./review-workspace/use-viewport-dimensions.ts";
+import { useScopeCardState } from "./review-workspace/use-scope-card-state.ts";
+import { usePageMarkers } from "./review-workspace/use-page-markers.ts";
+import { useDiagnosticsSignal } from "./review-workspace/use-diagnostics-signal.ts";
+import { useWorkspaceComposition } from "./review-workspace/use-workspace-composition.ts";
+import { useWorkspaceArbiter } from "./review-workspace/use-workspace-arbiter.ts";
+import { useLayoutFacetRenderSignal } from "./review-workspace/use-layout-facet-render-signal.ts";
+import { useScrollRootCapture } from "./review-workspace/use-scroll-root-capture.ts";
+import { usePmSurfaceCapture } from "./review-workspace/use-pm-surface-capture.ts";
+import { TwReviewWorkspaceNavigator } from "./review-workspace/tw-review-workspace-navigator.tsx";
+import { TwReviewWorkspacePageToolbar } from "./review-workspace/tw-review-workspace-page-toolbar.tsx";
+
+export {
+  FRAME_PX_PER_TWIP_AT_96DPI,
+  MIN_BAND_HEIGHT_PX,
+  buildPageShellMetrics,
+  resolveZoomMultiplier,
+  type PageShellMetrics,
+} from "./review-workspace/page-shell-metrics.ts";
+
+import type { TwReviewWorkspaceProps } from "./review-workspace/types.ts";
+import { useUiApi } from "./ui-api-context.tsx";
+import { useUiShellChannels } from "./ui-shell-channels-context.tsx";
+export type {
+  ReviewWorkspaceChromeVisibility,
+  TwReviewWorkspaceProps,
+} from "./review-workspace/types.ts";
+
+import type { EditorRole } from "../api/public-types.ts";
+
+// Default shell-header modes for the workspace's default composition.
+// Designsystem §6.1 prescribes a 4-mode switcher (edit / review / workflow
+// / more).  "more" is kept in the layout for parity but marked disabled
+// until its handler is defined by refactor/11 Slice 7 + refactor/10
+// Slice 5 (Phase Q debug UX).  Hosts that want a fully-wired 4-mode set
+// supply their own `shellHeader` prop.
+const DEFAULT_WORKSPACE_SHELL_MODES: readonly ShellHeaderModeOption[] = [
+  { id: "edit", label: "Edit" },
+  { id: "review", label: "Review" },
+  { id: "workflow", label: "Workflow" },
+  { id: "more", label: "More", disabled: true },
+];
+
+function editorRoleToShellMode(role: EditorRole): ShellHeaderMode {
+  switch (role) {
+    case "editor":
+      return "edit";
+    case "review":
+      return "review";
+    case "workflow":
+      return "workflow";
+  }
+}
 
-export interface TwReviewWorkspaceProps {
-  snapshot: RuntimeRenderSnapshot;
-  viewState: EditorViewStateSnapshot;
-  markupDisplay: MarkupDisplay;
-  currentUserId?: string;
-  capabilities?: SessionCapabilities;
-  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
-  reviewMode?: "editing" | "review";
-  /**
-   * Runtime-owned layout facet.  Optional so existing tests + host apps
-   * continue to mount the workspace without installing a facet.  When
-   * supplied, the ChromeOverlay plane (scope rail, workflow dock, etc.)
-   * renders over the document column.
-   */
-  layoutFacet?: import("../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
-  /**
-   * Optional shell header mounted above the formatting toolbar.  Pass a
-   * pre-assembled `<TwShellHeader />` with brand / mode switcher /
-   * primaryAction, or any other ReactNode.  Hosts that do not supply this
-   * get the legacy layout.
-   */
-  shellHeader?: ReactNode;
-  /**
-   * Optional host-provided Workflow-tab override for the review rail.
-   * When unset the rail renders the built-in `TwWorkflowTab` sourced from
-   * `layoutFacet.getAllScopeRailSegments()`.
-   */
-  reviewRailWorkflowTab?: ReactNode;
-  reviewRailWorkflowCount?: number;
-  reviewRailWorkflowScopesTitle?: string;
-  reviewRailIntelligenceEyebrow?: string;
-  /** Opt in to the editorial DOCUMENT INTELLIGENCE header + underline tab chip. */
-  reviewRailIntelligenceHeader?: boolean;
-  /** Optional SEARCH / HELP utility footer at the bottom of the rail. */
-  reviewRailFooter?: {
-    onSearch?: () => void;
-    helpHref?: string;
-    searchLabel?: string;
-    helpLabel?: string;
-  };
-  /**
-   * @deprecated — Lane 6b §6b.U4 (designsystem §6.26).
-   *
-   * The floating bottom-center mode dock is retained for back-compat but is
-   * off by default.  Its functionality is covered by TwShellHeader mode tabs
-   * + TwRoleActionRegion.  To render it, hosts must supply BOTH `modeDock`
-   * data and `experimental.showModeDock = true`.
-   */
-  modeDock?: {
-    label: string;
-    icon?: ReactNode;
-    actions?: readonly import("./chrome/tw-mode-dock").TwModeDockAction[];
-  };
-  /**
-   * Experimental feature flags.  Anything here is subject to change or
-   * removal without a major-version bump.  Do not depend on these in
-   * production consumers.
-   */
-  experimental?: {
-    /**
-     * Re-enable the deprecated TwModeDock floating bottom dock.  Defaults to
-     * `false` — the shell header + role action region supersede this surface
-     * per designsystem §6.26.
-     */
-    showModeDock?: boolean;
-  };
-  document: ReactNode;
-  workspaceMode: WorkspaceMode;
-  zoomLevel?: ZoomLevel;
-  formattingState?: FormattingStateSnapshot;
-  activeListContext?: ActiveListContext | null;
-  styleCatalog?: StyleCatalogSnapshot;
-  activeRailTab: ReviewRailTab;
-  activeCommentId?: string;
-  activeRevisionId?: string;
-  showTrackedChanges: boolean;
-  workflowScopeSnapshot?: WorkflowScopeSnapshot | null;
-  interactionGuardSnapshot?: InteractionGuardSnapshot;
-  chromePreset?: WordReviewEditorChromePreset;
-  chromeOptions?: Partial<WordReviewEditorChromeOptions>;
-  /** P9g — live collab session for the `"collab"` chrome preset's top nav. */
-  collabSession?: import("../runtime/collab-session.ts").CollabSession;
-  collabTransportStatus?: import("../api/awareness-identity-types.ts").TransportStatus;
-  collabActorId?: string;
-  collabSendBaseline?: {
-    originDocumentId: string;
-    originPayloadId: string;
-    originContentHash: string;
-    payloadXml: string;
-  };
-  reviewQueue?: ReviewQueueSnapshot;
-  documentContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
-  selectionContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
-  currentScopeContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
-  commands: EditorCommandBag;
-  onActivateFloatingImage?: (payload: {
-    mediaId: string;
-    from: number;
-    to: number;
-    storyTarget: EditorStoryTarget;
-  }) => void;
-  /** N6 — release the grabbed image/shape. Wired to `runtime.deselectObject()` by the host. */
-  onDeselectObject?: () => void;
-  activeSelectionTool?: ActiveSelectionToolModel | null;
-  selectionToolAnchor?: SelectionToolAnchor | null;
-  documentNavigation?: DocumentNavigationSnapshot;
-  /**
-   * R2.3: chrome-pin change handler.  When supplied, selection tools
-   * expose their detach affordance and persist pin state through to
-   * runtime ViewState (via the host's `setChromePin` action).  When
-   * omitted, the detach handle is suppressed — the tool behaves as
-   * a non-pinnable anchored panel (pre-R2 behavior for most kinds).
-   */
-  onChromePinChange?: (
-    surface: import("../api/public-types").ChromePinSurface,
-    pin: import("../api/public-types").PinState | null,
-  ) => void;
-  onWorkspaceModeChange?: (value: WorkspaceMode) => void;
-  onZoomChange?: (level: ZoomLevel) => void;
-  onActiveRailTabChange?: (value: ReviewRailTab) => void;
-  onShowTrackedChangesChange?: (show: boolean) => void;
-  onUndo?: () => void;
-  onRedo?: () => void;
-  onSetParagraphStyle?: (styleId: string) => void;
-  onToggleBold?: () => void;
-  onToggleItalic?: () => void;
-  onToggleUnderline?: () => void;
-  onSetSelectionTextColor?: (color: string) => void;
-  onSetSelectionHighlightColor?: (color: string | null) => void;
-  onToggleStrikethrough?: () => void;
-  onToggleSuperscript?: () => void;
-  onToggleSubscript?: () => void;
-  onSetFontFamily?: (fontFamily: string) => void;
-  onSetFontSize?: (fontSize: number) => void;
-  onSetTextColor?: (color: string) => void;
-  onSetHighlightColor?: (color: string | null) => void;
-  onSetAlignment?: (alignment: FormattingAlignment) => void;
-  onToggleBulletedList?: () => void;
-  onToggleNumberedList?: () => void;
-  onOutdent?: () => void;
-  onIndent?: () => void;
-  onAddComment?: () => void;
-  onInsertPageBreak?: () => void;
-  onInsertTable?: () => void;
-  onInsertSectionBreak?: (type: SectionBreakType) => void;
-  onInsertImage?: (options: InsertImageOptions) => void;
-  onSetTableStyle?: (styleId: string) => void;
-  onAddRowBefore?: () => void;
-  onAddRowAfter?: () => void;
-  onAddColumnBefore?: () => void;
-  onAddColumnAfter?: () => void;
-  onDeleteRow?: () => void;
-  onDeleteColumn?: () => void;
-  onDeleteTable?: () => void;
-  onMergeCells?: () => void;
-  onSplitCell?: () => void;
-  onSetCellBackground?: (color: string) => void;
-  onSetImageLayout?: (
-    mediaId: string,
-    dimensions: { widthEmu: number; heightEmu: number },
-  ) => void;
-  onSetImageFrame?: (
-    mediaId: string,
-    offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number },
-  ) => void;
-  onDeleteSectionBreak?: (sectionIndex: number) => void;
-  onUpdateSectionLayout?: (
-    sectionIndex: number,
-    patch: {
-      pageSize?: { width?: number; height?: number; orientation?: "portrait" | "landscape" };
-      pageMargins?: {
-        top?: number;
-        right?: number;
-        bottom?: number;
-        left?: number;
-        header?: number;
-        footer?: number;
-        gutter?: number;
-      };
-      columns?: {
-        count?: number;
-        space?: number;
-        equalWidth?: boolean;
-        columns?: Array<{ width: number; space?: number }>;
-        separator?: boolean;
-      };
-      titlePage?: boolean;
-      sectionType?: SectionBreakType;
-    },
-  ) => void;
-  onSetSectionPageNumbering?: (
-    sectionIndex: number,
-    patch: SectionPageNumberingPatch | null,
-  ) => void;
-  onSetHeaderFooterLink?: (
-    sectionIndex: number,
-    patch: HeaderFooterLinkPatch,
-  ) => void;
-  onAddCommentFromSelection?: () => void;
-  onExport?: () => void;
-  onDismissSelectionToolbar?: () => void;
-  onAcceptSuggestion?: () => void;
-  onRejectSuggestion?: () => void;
-  onEditSuggestion?: () => void;
-  onAddCommentFromSuggestion?: () => void;
-  onSelectionToolbarFocusCapture?: FocusEventHandler<HTMLDivElement>;
-  onSelectionToolbarBlurCapture?: FocusEventHandler<HTMLDivElement>;
-  selectionToolbarRef?: Ref<HTMLDivElement>;
-  onOpenComment?: (thread: CommentSidebarThreadSnapshot) => void;
-  onResolveComment?: (commentId: string) => void;
-  onReopenComment?: (commentId: string) => void;
-  onAddReply?: (commentId: string, body: string) => void;
-  onEditBody?: (commentId: string, body: string) => void;
-  onOpenRevision?: (revision: TrackedChangeEntrySnapshot) => void;
-  onAcceptRevision?: (revisionId: string) => void;
-  onRejectRevision?: (revisionId: string) => void;
-  onAcceptAllChanges?: () => void;
-  onRejectAllChanges?: () => void;
-  onCloseStory?: () => void;
-  /**
-   * @deprecated P8.11 — the workspace no longer renders a workspace-level
-   * header band with an "Edit header" button; per-page header bands route
-   * clicks via `onOpenStory` / `runtime.openStory` directly.  The prop
-   * remains optional for one release so existing hosts continue to
-   * compile; supplying it emits a `console.warn` on mount.
-   */
-  onOpenHeaderStory?: () => void;
-  /**
-   * @deprecated P8.11 — see `onOpenHeaderStory`.  Footer variant of the
-   * same deprecation.
-   */
-  onOpenFooterStory?: () => void;
-  /**
-   * Open a header/footer story for a specific page.  Called when the user
-   * double-clicks a per-page header/footer band in the page-stack chrome.
-   * Must resolve the correct variant for that page's section and call
-   * `runtime.openStory()`.
-   */
-  onOpenHeaderStoryForPage?: (pageIndex: number) => void;
-  onOpenFooterStoryForPage?: (pageIndex: number) => void;
-  /**
-   * P8.11 — fired when a per-page chrome band (header / footer) is
-   * clicked to promote it into the active editing surface.  Wire to
-   * `runtime.openStory(target)`; the chrome layer's portal mechanism
-   * then reparents the PM surface into the matching band's active slot.
-   */
-  onOpenStory?: (target: EditorStoryTarget) => void;
-  onSetParagraphIndentation?: (indentation: {
-    left?: number;
-    right?: number;
-    firstLine?: number;
-    hanging?: number;
-  }) => void;
-  onSetParagraphTabStops?: (tabStops: Array<{ pos: number; val?: string; leader?: string }>) => void;
-  onRestartNumbering?: () => void;
-  onContinueNumbering?: () => void;
-  // P6: new table ops
-  onToggleRowHeader?: () => void;
-  onToggleRowCantSplit?: () => void;
-  onDistributeColumnsEvenly?: () => void;
-  onSetTableAlignment?: (alignment: "left" | "center" | "right") => void;
-  onSetCellVerticalAlign?: (align: "top" | "center" | "bottom") => void;
-  /** P6: active table context for chrome overlay grips. */
-  tableContext?: import("../api/public-types").TableStructureContextSnapshot | null;
-  /** P6: column resize committed from overlay grip → set-column-width op. */
-  onSetColumnWidth?: (columnIndex: number, twips: number) => void;
-  /** P6: row resize committed from overlay grip → set-row-height op. */
-  onSetRowHeight?: (rowIndex: number, twips: number, rule: "auto" | "atLeast" | "exact") => void;
-  onListIndent?: () => void;
-  onListOutdent?: () => void;
-  onUpdateFields?: () => void;
-  onUpdateTableOfContents?: () => void;
-  onGoToPreviousReviewItem?: () => void;
-  onGoToNextReviewItem?: () => void;
-  onMarkSectionForReview?: () => void;
-  /** Optional: open sidebar to tracked-changes panel. When provided, the review role shows a sidebar-TC icon. */
-  onReviewSidebarTrackedChanges?: () => void;
-  /** Optional: open sidebar to comments panel. When provided, the review role shows a sidebar-comments icon. */
-  onReviewSidebarComments?: () => void;
-  onNavigateHeading?: (headingId: string) => void;
-  chromeVisibility?: Partial<ReviewWorkspaceChromeVisibility>;
-  /**
-   * Called when the shell-header mode tab changes or any chrome surface fires
-   * a role switch.  Wire to `runtime.setEditorRole(role)` so the workspace
-   * re-renders with the new per-role action set.
-   */
-  onEditorRoleChange?: (role: import("../api/public-types.ts").EditorRole) => void;
-  /**
-   * Scope card mode selector fired a mode change.  Wire to the host's
-   * existing overlay-apply path (or an equivalent CCEP workflow
-   * endpoint).  The card never mutates runtime state directly.
-   */
-  onScopeModeChangeRequested?: (payload: {
-    scopeId: string;
-    mode: import("../api/public-types.ts").WorkflowScopeMode;
-  }) => void;
-  /**
-   * Scope card issue row fired an action (resolve/waive/escalate/
-   * acknowledge).  Host updates the attached `IssueMetadataValue`
-   * state and re-pushes via `setWorkflowMetadataEntries`.
-   */
-  onScopeIssueActionRequested?: (payload: {
-    scopeId: string;
-    issueId: string;
-    action: import("../api/public-types.ts").ScopeIssueAction;
-  }) => void;
-  /**
-   * R3 — scope card suggestion-group accept button fired.  WordReview-
-   * Editor relays to `ref.acceptSuggestionGroup(groupId)` which fans
-   * out to individual `acceptChange` calls across the group members.
-   */
-  onScopeAcceptSuggestionGroup?: (payload: {
-    scopeId: string;
-    groupId: string;
-  }) => void;
-  /** R3 — scope card suggestion-group reject. */
-  onScopeRejectSuggestionGroup?: (payload: {
-    scopeId: string;
-    groupId: string;
-  }) => void;
-  /**
-   * K2 — scope card "Ask review agent" fired.  WordReviewEditor emits
-   * `agent-on-selection-requested` via WordReviewEditorEvent.
-   */
-  onScopeAskAgent?: (payload: {
-    scopeId: string;
-    anchor?: EditorAnchorProjection;
-  }) => void;
-  /**
-   * P3 — optional scope-tag editor slot rendered inside the scope
-   * card when `editorRole === "workflow"`.  Hosts pass a chip picker,
-   * free-text input, or whatever authoring surface they want.  Unset
-   * in editor/review roles.
-   */
-  scopeCardScopeTagEditor?: ReactNode;
+function shellModeToEditorRole(mode: ShellHeaderMode): EditorRole | null {
+  switch (mode) {
+    case "edit":
+      return "editor";
+    case "review":
+      return "review";
+    case "workflow":
+      return "workflow";
+    case "more":
+      return null;
+  }
 }
 
 export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
@@ -449,12 +139,8 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   // measure per-page rects and to reparent PM's DOM node across band
   // portals when `activeStory` changes.  See comment near the body slot
   // in the render tree below.
-  const bodySlotRef = useRef<HTMLDivElement | null>(null);
-  const scrollRootRef = useRef<HTMLDivElement | null>(null);
-  const [pmSurfaceElement, setPmSurfaceElement] =
-    useState<HTMLElement | null>(null);
-  const [pageStackScrollRoot, setPageStackScrollRoot] =
-    useState<HTMLElement | null>(null);
+  const { bodySlotRef, pmSurfaceElement } = usePmSurfaceCapture();
+  const { scrollRootRef, pageStackScrollRoot } = useScrollRootCapture();
   const caps = props.capabilities;
   const isPageWorkspace = props.workspaceMode === "page";
   const markupDisplay = props.markupDisplay;
@@ -462,93 +148,27 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   const [layoutToolsOpen, setLayoutToolsOpen] = useState(false);
 
   // Scope card state — tracks which scope's card is currently open so
-  // the ChromeOverlay's card layer renders the right one.  The card
-  // closes on click-outside, Escape, or a repeat click on its stripe.
-  const [activeScopeId, setActiveScopeId] = useState<string | null>(null);
-  const handleScopeStripeClick = useCallback(
-    (segment: { scopeId: string }) => {
-      setActiveScopeId((current) =>
-        current === segment.scopeId ? null : segment.scopeId,
-      );
-    },
-    [],
-  );
-  const handleScopeCardClose = useCallback(() => {
-    setActiveScopeId(null);
-  }, []);
-
-  // P3d: keyboard scope navigation.  J / K cycle the active scope in
-  // document order; Enter opens the first scope when none is active.
-  // `shouldHandleScopeNavKey` + `cycleScopeIndex` are extracted pure
-  // helpers so the logic is unit-testable without a workspace mount.
-  useEffect(() => {
-    const layoutFacet = props.layoutFacet;
-    if (!layoutFacet || typeof layoutFacet.getAllScopeCardModels !== "function") {
-      return undefined;
-    }
-    const onKey = (event: KeyboardEvent) => {
-      if (!shouldHandleScopeNavKey(event)) return;
-      const models = layoutFacet.getAllScopeCardModels();
-      if (models.length === 0) return;
-      const ids = models.map((model) => model.scopeId);
-      const key = event.key.toLowerCase();
-      if (key === "enter") {
-        if (!activeScopeId) {
-          setActiveScopeId(ids[0] ?? null);
-          event.preventDefault();
-        }
-        return;
-      }
-      const direction: 1 | -1 = key === "j" ? 1 : -1;
-      const next = cycleScopeIndex(activeScopeId, ids, direction);
-      setActiveScopeId(next);
-      event.preventDefault();
-    };
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [props.layoutFacet, activeScopeId]);
-  const onScopeModeChangeRequested = props.onScopeModeChangeRequested;
-  const handleScopeCardModeChange = useCallback(
-    (scopeId: string, mode: import("../api/public-types.ts").WorkflowScopeMode) => {
-      onScopeModeChangeRequested?.({ scopeId, mode });
-    },
-    [onScopeModeChangeRequested],
-  );
-  const onScopeIssueActionRequested = props.onScopeIssueActionRequested;
-  const handleScopeCardIssueAction = useCallback(
-    (
-      scopeId: string,
-      issueId: string,
-      action: import("../api/public-types.ts").ScopeIssueAction,
-    ) => {
-      onScopeIssueActionRequested?.({ scopeId, issueId, action });
-    },
-    [onScopeIssueActionRequested],
-  );
-  const onScopeAcceptSuggestionGroup = props.onScopeAcceptSuggestionGroup;
-  const handleScopeCardAcceptSuggestionGroup = useCallback(
-    (scopeId: string, groupId: string) => {
-      onScopeAcceptSuggestionGroup?.({ scopeId, groupId });
-    },
-    [onScopeAcceptSuggestionGroup],
-  );
-  const onScopeRejectSuggestionGroup = props.onScopeRejectSuggestionGroup;
-  const handleScopeCardRejectSuggestionGroup = useCallback(
-    (scopeId: string, groupId: string) => {
-      onScopeRejectSuggestionGroup?.({ scopeId, groupId });
-    },
-    [onScopeRejectSuggestionGroup],
-  );
-  const onScopeAskAgent = props.onScopeAskAgent;
-  const handleScopeCardAskAgent = useCallback(
-    (scopeId: string) => {
-      const cardModel = props.layoutFacet
-        ?.getAllScopeCardModels?.()
-        ?.find((m) => m.scopeId === scopeId);
-      onScopeAskAgent?.({ scopeId, anchor: cardModel?.anchor });
-    },
-    [onScopeAskAgent, props.layoutFacet],
-  );
+  // the ChromeOverlay's card layer renders the right one. Open/close
+  // rules + J/K keyboard navigation + all 5 scope-card callback
+  // handlers live in the hook.
+  const {
+    activeScopeId,
+    handleScopeStripeClick,
+    handleScopeCardClose,
+    handleScopeCardModeChange,
+    handleScopeCardIssueAction,
+    handleScopeCardAcceptSuggestionGroup,
+    handleScopeCardRejectSuggestionGroup,
+    handleScopeCardAskAgent,
+  } = useScopeCardState({
+    layoutFacet: props.layoutFacet,
+    workflowFacet: props.workflowFacet,
+    onScopeModeChangeRequested: props.onScopeModeChangeRequested,
+    onScopeIssueActionRequested: props.onScopeIssueActionRequested,
+    onScopeAcceptSuggestionGroup: props.onScopeAcceptSuggestionGroup,
+    onScopeRejectSuggestionGroup: props.onScopeRejectSuggestionGroup,
+    onScopeAskAgent: props.onScopeAskAgent,
+  });
   const zoomLevel = props.zoomLevel ?? 100;
   // Numeric zooms resolve immediately; "pageWidth" / "onePage" need the
   // page-frame dimensions to fit against — they're resolved below once
@@ -570,18 +190,36 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     chromeVisibility: props.chromeVisibility,
   });
   const reviewRailAvailable = chromeVisibility.reviewRail && (caps?.reviewRailVisible ?? true);
-  const [viewportWidth, setViewportWidth] = useState<number | undefined>(() => readViewportWidth());
-  const [viewportHeight, setViewportHeight] = useState<number | undefined>(() => readViewportHeight());
-  const [reviewRailOpen, setReviewRailOpen] = useState(() =>
-    getInitialReviewRailOpen({
-      viewportWidth: readViewportWidth(),
-      reviewRailAvailable,
-    }),
-  );
+  const { viewportWidth, viewportHeight } = useViewportDimensions();
+  const { reviewRailOpen, setReviewRailOpen } = useReviewRailState({
+    reviewRailAvailable,
+    viewportWidth,
+  });
   // Incremented on zoom_changed / render_frame_ready so the placement
   // useMemo below re-executes when the render kernel emits new rects.
-  const [renderFrameRevision, setRenderFrameRevision] = useState(0);
-  const responsiveChromeSignatureRef = useRef<string | null>(null);
+  const renderFrameRevision = useLayoutFacetRenderSignal(props.layoutFacet);
+
+  // refactor/10 chrome-contract Slice 2 (2026-04-23) — emit into the
+  // shell UI-API subscriber channels when the geometry/layout facet
+  // bumps its render-frame revision. Consumers of
+  // `ui.viewport.subscribe` / `ui.overlays.subscribe` get one event per
+  // layout invalidation. Coalescing is upstream (the layout facet
+  // itself bumps at most once per frame).
+  //
+  // Payload choices:
+  //   - viewport: current `ViewportState` snapshot. Consumer can diff
+  //     or re-read as they like.
+  //   - overlays: `{kind: "page", value: 0}` as a universal "geometry
+  //     changed, re-read any attached anchors" marker. Per-query
+  //     invalidation fan-out is a Phase Q follow-up — the geometry
+  //     facet does not yet expose per-kind invalidation events.
+  const uiApiForEmit = useUiApi();
+  const shellChannels = useUiShellChannels();
+  React.useEffect(() => {
+    if (!uiApiForEmit || !shellChannels) return;
+    shellChannels.viewport.emit(uiApiForEmit.viewport.get());
+    shellChannels.overlays.emit({ kind: "page", value: 0 });
+  }, [renderFrameRevision, uiApiForEmit, shellChannels]);
   const headings = props.documentNavigation?.headings ?? [];
   const headerVariant = snapshot.pageLayout?.headerVariants[0]?.variant ?? "default";
   const footerVariant = snapshot.pageLayout?.footerVariants[0]?.variant ?? "default";
@@ -590,98 +228,47 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
       ? viewState.selection.activeRange.at
       : viewState.selection.head;
   const shouldResolveActiveParagraphLayout =
-    isPageWorkspace &&
-    chromeVisibility.pageChrome &&
-    layoutToolsOpen;
-  const activeParagraphLayout = useMemo(
-    () =>
-      shouldResolveActiveParagraphLayout
-        ? resolveActiveParagraphLayout(snapshot.surface, selectionPosition)
-        : null,
-    [selectionPosition, shouldResolveActiveParagraphLayout, snapshot.surface],
-  );
-  const pageChromeModel = useMemo(
-    () =>
-      buildPageChromeModel(
-        snapshot.surface,
-        snapshot.pageLayout,
-        props.documentNavigation,
-        snapshot.activeStory,
-      ),
-    [props.documentNavigation, snapshot.activeStory, snapshot.pageLayout, snapshot.surface],
-  );
+    isPageWorkspace && chromeVisibility.pageChrome && layoutToolsOpen;
   const effectiveSelectionMode = props.interactionGuardSnapshot?.effectiveMode ?? "edit";
   const allowLocalChromeMutations = Boolean(caps?.canEdit) && effectiveSelectionMode === "edit";
-  const gatedSelectionTool = useMemo(() => {
-    if (!props.activeSelectionTool) {
-      return null;
-    }
-    if (props.activeSelectionTool.kind === "structure-context" && !chromeVisibility.contextToolbars) {
-      return null;
-    }
-    return props.activeSelectionTool;
-  }, [props.activeSelectionTool, chromeVisibility.contextToolbars]);
-  const pageShellMetrics = useMemo(
-    () => buildPageShellMetrics(snapshot.pageLayout),
-    [snapshot.pageLayout],
-  );
-  // P2.c — resolve "pageWidth" / "onePage" against the active section's
-  // real paper dimensions.  Numeric zooms pass through.  Falls back to
-  // `numericZoomScale` (1.0 for symbolic zooms when paper dims are
-  // unavailable, e.g., during initial load).
-  const zoomScale = useMemo(() => {
-    if (typeof zoomLevel === "number") return numericZoomScale;
-    return resolveZoomMultiplier(
-      zoomLevel,
-      pageShellMetrics.frameWidthPx ?? 0,
-      pageShellMetrics.frameHeightPx ?? 0,
-      viewportWidth,
-      viewportHeight,
-    );
-  }, [
+  const {
+    activeParagraphLayout,
+    pageChromeModel,
+    gatedSelectionTool,
+    pageShellMetrics,
+    zoomScale,
+    pageZoomBucket,
+  } = useDerivedViewState({
+    snapshot,
+    documentNavigation: props.documentNavigation,
+    activeSelectionTool: props.activeSelectionTool,
+    chromeVisibility,
+    selectionPosition,
+    shouldResolveActiveParagraphLayout,
     zoomLevel,
     numericZoomScale,
-    pageShellMetrics.frameWidthPx,
-    pageShellMetrics.frameHeightPx,
     viewportWidth,
     viewportHeight,
-  ]);
-  const pageZoomBucket =
-    !isPageWorkspace ? undefined : zoomScale < 1 ? "low" : zoomScale > 1 ? "high" : "base";
-  const selectionToolbarPlacement = useMemo(() => {
-    // Prefer render-frame anchors when the layout facet is available — this
-    // keeps the tool glued to kernel coordinates across zoom, scroll, and
-    // predicted-text reconciliation (R4).
-    if (props.layoutFacet && gatedSelectionTool) {
-      const anchorRect = resolveSelectionAnchor({
-        facet: props.layoutFacet,
-        selection: viewState.selection,
-        tool: gatedSelectionTool,
-      });
-      if (anchorRect && selectionToolbarRootRef.current) {
-        const containerRect = selectionToolbarRootRef.current.getBoundingClientRect();
-        const result = resolveSelectionToolPlacement({
-          anchor: anchorRect,
-          container: { widthPx: containerRect.width, heightPx: containerRect.height },
-        });
-        if (result) return result;
-      }
-    }
-    // Fall back to DOM rects for hosts that do not supply a layout facet.
-    return resolveSelectionToolbarPlacement(
-      props.selectionToolAnchor,
-      selectionToolbarRootRef.current,
-      zoomScale,
-    );
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [
-    props.layoutFacet,
-    props.selectionToolAnchor,
+    isPageWorkspace,
+  });
+  // DS-C1 — publish the current selection anchor so
+  // `ui.overlays.getAnchor({ kind: "selection" })` resolves to a real
+  // rect on the mounted path (designsystem.md §8.8.1 "Selection toolbar"
+  // row). No-op when no `OverlayAnchorBridgeProvider` is mounted.
+  useShellSelectionAnchorBridge({
+    geometryFacet: props.geometryFacet,
+    selection: viewState.selection,
+    gatedSelectionTool,
+    renderFrameRevision,
+  });
+  const selectionToolbarPlacement = useSelectionToolbarPlacement({
     gatedSelectionTool,
-    viewState.selection,
+    selection: viewState.selection,
+    selectionToolAnchor: props.selectionToolAnchor,
     zoomScale,
     renderFrameRevision,
-  ]);
+    selectionToolbarRootRef,
+  });
   const activePage = props.documentNavigation?.pages[props.documentNavigation.activePageIndex] ?? null;
   // P5b — status-bar facts derived from the layout facet so the
   // Page-N-of-M display + measurement-fidelity badge ("E" / "C" / "C+F")
@@ -689,48 +276,14 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   // above bumps `renderFrameRevision` on the same kinds; including it
   // in the dependency list re-runs this memo without a separate
   // subscription.
-  // N6 — resolve grabbed-object segment offsets from the surface so the
-  // selection overlay can query the anchor index without a full surface walk.
-  const grabbedSegmentOffsets = useMemo(() => {
-    const objectId = snapshot.grabbedObjectId ?? null;
-    if (!objectId || !snapshot.surface) return null;
-    for (const block of snapshot.surface.blocks) {
-      if (!("segments" in block)) continue;
-      for (const seg of (block as { segments?: unknown[] }).segments ?? []) {
-        const s = seg as { kind?: string; mediaId?: string; from?: number; to?: number };
-        if ((s.kind === "image" || s.kind === "shape") && s.mediaId === objectId && s.from != null) {
-          return { from: s.from, to: s.to ?? s.from + 1 };
-        }
-      }
-    }
-    return null;
-  }, [snapshot.grabbedObjectId, snapshot.surface]);
+  const grabbedSegmentOffsets = useGrabbedSegmentOffsets(snapshot);
 
-  const statusBarPageFacts = useMemo(() => {
-    const facet = props.layoutFacet;
-    if (!facet) {
-      return {
-        displayPageNumber: null as number | null,
-        pageCount: null as number | null,
-        measurementFidelity: undefined as
-          | import("../api/public-types.ts").PublicMeasurementFidelity
-          | undefined,
-      };
-    }
-    const head = selectionPosition;
-    const pageRef = facet.getPageForOffset(head, snapshot.activeStory);
-    const displayPageNumber =
-      pageRef !== null && typeof pageRef.pageIndex === "number"
-        ? facet.getDisplayPageNumber(pageRef.pageIndex) ?? pageRef.pageIndex + 1
-        : null;
-    const pageCount = facet.getPageCount();
-    return {
-      displayPageNumber,
-      pageCount,
-      measurementFidelity: facet.getMeasurementFidelity(),
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [props.layoutFacet, selectionPosition, snapshot.activeStory, renderFrameRevision]);
+  const statusBarPageFacts = useStatusBarPageFacts({
+    layoutFacet: props.layoutFacet,
+    selectionPosition,
+    activeStory: snapshot.activeStory,
+    renderFrameRevision,
+  });
   // P8.11 — `headerBandLabel` / `footerBandLabel` retired along with the
   // workspace-level bands.  Per-page bands in `TwPageStackChromeLayer`
   // render the actual header / footer story blocks via
@@ -743,377 +296,250 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     snapshot.readOnly ||
     snapshot.activeStory.kind !== "main" ||
     effectiveSelectionMode !== "edit";
-  const responsiveChrome = useMemo(
-    () =>
-      resolveResponsiveChromeState({
-        viewportWidth,
-        reviewRailAvailable,
-        reviewRailOpen,
-      }),
-    [reviewRailAvailable, reviewRailOpen, viewportWidth],
-  );
   const hasSidebarPanelAccess = Boolean(
     props.onReviewSidebarTrackedChanges || props.onReviewSidebarComments,
   );
-  const scopedChromePolicy = useMemo(
-    () =>
-      resolveScopedChromePolicy({
-        preset: chromePreset,
-        compactMode: responsiveChrome.isNarrow,
-        capabilities: caps,
-        interactionGuardSnapshot: props.interactionGuardSnapshot,
-        workflowScopeSnapshot: props.workflowScopeSnapshot,
-        activeListContext: props.activeListContext,
-        role: viewState.editorRole,
-        hasSidebarPanelAccess,
-      }),
-    [
-      caps,
+  const { responsiveChrome, scopedChromePolicy, toolbarInteractionPolicy } =
+    useChromePolicy({
+      viewportWidth,
+      reviewRailAvailable,
+      reviewRailOpen,
       chromePreset,
+      caps,
+      interactionGuardSnapshot: props.interactionGuardSnapshot,
+      workflowScopeSnapshot: props.workflowScopeSnapshot,
+      activeListContext: props.activeListContext,
+      role: viewState.editorRole,
       hasSidebarPanelAccess,
-      props.activeListContext,
-      props.interactionGuardSnapshot,
-      props.workflowScopeSnapshot,
-      responsiveChrome.isNarrow,
-      viewState.editorRole,
-    ],
-  );
-  const toolbarInteractionPolicy: ToolbarInteractionPolicy | undefined = caps
-    ? {
-        mode: effectiveSelectionMode,
-        canFormatText: caps.canEdit && effectiveSelectionMode === "edit",
-        canInsertStructural: caps.canEdit && effectiveSelectionMode === "edit",
-        canAddComment:
-          caps.canAddComment &&
-          effectiveSelectionMode !== "view" &&
-          effectiveSelectionMode !== "blocked",
-      }
-    : undefined;
-
-  useEffect(() => {
-    recordPerfSample("workspace.chrome");
-    incrementInvalidationCounter("workspace.chrome.recomputes");
-  }, [activeParagraphLayout, pageChromeModel, pageShellMetrics]);
-
-  useEffect(() => {
-    if (isPageWorkspace && snapshot.activeStory.kind !== "main") {
-      setLayoutToolsOpen(true);
-    }
-  }, [isPageWorkspace, snapshot.activeStory.kind]);
-
-  // P8.11 — capture the scroll-root DOM element on mount so the chrome
-  // overlay's `TwPageStackChromeLayer` can measure per-page rects and
-  // observe DOM mutations.  `scrollRootRef` is attached to the existing
-  // `[data-wre-scroll-root]` container; rely on a mount effect rather
-  // than a ref callback so render-time state stays cheap.
-  useEffect(() => {
-    if (scrollRootRef.current !== pageStackScrollRoot) {
-      setPageStackScrollRoot(scrollRootRef.current);
-    }
-    // A `useEffect` re-runs after every render; the comparison guard
-    // keeps `setPageStackScrollRoot` from firing every commit.  The
-    // scroll-root identity only changes when the component re-mounts.
-  });
-
-  // P8.11 — capture the PM surface DOM element.  The ProseMirror surface
-  // mounts inside `bodySlotRef` on its own schedule (the PM constructor
-  // runs inside the `TwProseMirrorSurface` child component).  A
-  // `MutationObserver` scoped to the body slot's `childList` picks up
-  // the PM root on first commit; once captured, the chrome layer owns
-  // reparent state (including portal-slot promotion), so we skip
-  // further updates unless PM is actually disconnected from the
-  // document (e.g. session/document swap tearing PM down).
-  useEffect(() => {
-    const slot = bodySlotRef.current;
-    if (!slot) return undefined;
-
-    // If we already hold a live reference, the chrome layer may have
-    // portaled PM into a per-page band — PM has left `bodySlotRef` but
-    // is still connected to the document.  We keep the reference until
-    // the node is fully disconnected.
-    if (pmSurfaceElement && pmSurfaceElement.isConnected) {
-      return undefined;
-    }
-
-    const readPm = (): HTMLElement | null =>
-      slot.querySelector<HTMLElement>(".ProseMirror");
-
-    const current = readPm();
-    if (current !== pmSurfaceElement) {
-      setPmSurfaceElement(current);
-    }
-    const runtime = slot.ownerDocument?.defaultView as
-      | (Window & { MutationObserver?: typeof MutationObserver })
-      | null;
-    if (!runtime?.MutationObserver) return undefined;
-    const observer = new runtime.MutationObserver(() => {
-      const next = readPm();
-      if (next !== null && next !== pmSurfaceElement) {
-        setPmSurfaceElement(next);
-      }
+      effectiveSelectionMode,
     });
-    // `childList: true, subtree: false` — we only care when children of
-    // the body slot change (e.g. PM is added for the first time).
-    // Subtree mutations (PM's own edits) are not our concern and would
-    // fire on every keystroke.
-    observer.observe(slot, { childList: true, subtree: false });
-    return () => observer.disconnect();
-  }, [pmSurfaceElement]);
-
-  // P8.11 — deprecation shim for the legacy `onOpenHeaderStory` /
-  // `onOpenFooterStory` props.  Per-page chrome bands route clicks via
-  // `onOpenStory` + `runtime.openStory` directly; the workspace-level
-  // bands that consumed these callbacks are gone.  Kept optional for one
-  // release so existing hosts compile; a mount-time `console.warn` nudges
-  // them toward `onOpenStory`.
-  useEffect(() => {
-    if (props.onOpenHeaderStory) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        "[docx-react-component] `onOpenHeaderStory` is deprecated. Per-page header bands route clicks via runtime.openStory directly. (P8)",
-      );
-    }
-    if (props.onOpenFooterStory) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        "[docx-react-component] `onOpenFooterStory` is deprecated. Per-page footer bands route clicks via runtime.openStory directly. (P8)",
-      );
-    }
-    // Mount-once: we only want to nudge hosts at startup, not per render.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
 
-  useEffect(() => {
-    if (typeof window === "undefined") {
-      return;
-    }
-
-    const updateViewport = () => {
-      setViewportWidth(readViewportWidth());
-      setViewportHeight(readViewportHeight());
-    };
-
-    updateViewport();
-    window.addEventListener("resize", updateViewport);
-    return () => {
-      window.removeEventListener("resize", updateViewport);
-    };
-  }, []);
+  // L7 Phase 2 Task 2.2.4a — viewport-scroll wiring. Page marker
+  // collection, selection-backed visible block/page ranges, and the
+  // facet push all live in the hook.
+  const { visibleBlockRange, visiblePageIndexRange } = usePageMarkers({
+    pageStackScrollRoot,
+    snapshot,
+    layoutFacet: props.layoutFacet,
+  });
 
-  // Subscribe to layout facet events so chrome re-projects whenever the
-  // engine produces new pagination state, fields dirty, or measurement
-  // fidelity changes.  P5b broadened this beyond the original P3.b set
-  // ("zoom_changed" / "render_frame_ready") so the status-bar Page-N-of-M
-  // and fidelity badge transition in real time; the hardening commit
-  // added "measurement_backend_ready" so the canvas backend swap also
-  // refreshes the badge.  P14.b adds "layout_committed" — a single
-  // coalesced event per applyPatch — so consumers that only care
-  // about "the engine just finished a build" can react once instead
-  // of N times.
-  useEffect(() => {
-    if (!props.layoutFacet) return;
-    let pendingBump = false;
-    let cancelled = false;
-    const scheduleBump = () => {
-      if (pendingBump || cancelled) return;
-      pendingBump = true;
-      queueMicrotask(() => {
-        pendingBump = false;
-        if (cancelled) return;
-        setRenderFrameRevision((n) => n + 1);
-      });
-    };
-    const unsub = props.layoutFacet.subscribe((event) => {
-      switch (event.kind) {
-        case "zoom_changed":
-        case "render_frame_ready":
-        case "layout_recomputed":
-        case "incremental_relayout":
-        case "page_count_changed":
-        case "page_field_dirtied":
-        case "measurement_backend_ready":
-        case "layout_committed":
-          scheduleBump();
-          break;
-        default:
-          break;
-      }
+  const { dismissSelectionToolbar, runWithSelectionToolbarDismiss } =
+    useWorkspaceSideEffects({
+      layoutFacet: props.layoutFacet,
+      activeParagraphLayout,
+      pageChromeModel,
+      pageShellMetrics,
+      isPageWorkspace,
+      activeStoryKind: snapshot.activeStory.kind,
+      setLayoutToolsOpen,
+      showDrawerReviewRail: responsiveChrome.showDrawerReviewRail,
+      setReviewRailOpen,
+      onOpenHeaderStory: props.onOpenHeaderStory,
+      onOpenFooterStory: props.onOpenFooterStory,
+      onDismissSelectionToolbar: props.onDismissSelectionToolbar,
     });
-    return () => {
-      cancelled = true;
-      unsub();
-    };
-  }, [props.layoutFacet]);
 
-  useEffect(() => {
-    const responsiveSignature = `${reviewRailAvailable ? "1" : "0"}:${isNarrowChromeViewport(viewportWidth) ? "n" : "d"}`;
-    if (responsiveChromeSignatureRef.current === responsiveSignature) {
-      return;
-    }
-
-    responsiveChromeSignatureRef.current = responsiveSignature;
-    setReviewRailOpen(
-      getInitialReviewRailOpen({
-        viewportWidth,
-        reviewRailAvailable,
-      }),
+  // Audit §2.4 — the shell header is ALWAYS present in default composition.
+  // When the host does not supply a pre-assembled shell node, fall back to
+  // a default TwShellHeader wired to the workspace's editor-role state so
+  // the mode tabs actually change the active role instead of being
+  // decorative.  The "more" tab is included for layout parity with §6.1
+  // but disabled until its handler is defined (Phase Q debug UX / Slice 7).
+  // Host-supplied shells continue to win (back-compat).
+  const defaultShellModes: readonly ShellHeaderModeOption[] =
+    DEFAULT_WORKSPACE_SHELL_MODES;
+  const defaultShellActiveMode: ShellHeaderMode = editorRoleToShellMode(
+    viewState.editorRole,
+  );
+  const renderedShell =
+    props.shellHeader !== undefined ? (
+      props.shellHeader
+    ) : (
+      <TwShellHeader
+        modes={defaultShellModes}
+        activeMode={defaultShellActiveMode}
+        onModeChange={(mode) => {
+          const nextRole = shellModeToEditorRole(mode);
+          if (nextRole !== null && nextRole !== viewState.editorRole) {
+            props.onEditorRoleChange?.(nextRole);
+          }
+        }}
+      />
     );
-  }, [reviewRailAvailable, viewportWidth]);
-
-  // L7 Phase 2 Task 2.2.4a — viewport-scroll wiring.
-  // Collect DOM elements with `[data-page-frame]` from the PM surface so the
-  // IntersectionObserver inside `useVisibleBlockRange` can determine which
-  // pages are currently visible.  The MutationObserver refreshes the set when
-  // the PM surface re-renders (e.g. a document load changes the page count).
-  const [pageMarkers, setPageMarkers] = useState<readonly HTMLElement[]>([]);
 
-  useEffect(() => {
-    const root = pageStackScrollRoot;
-    if (!root) {
-      setPageMarkers([]);
-      return undefined;
-    }
-    const refresh = () => {
-      const found = Array.from(root.querySelectorAll<HTMLElement>("[data-page-frame]"));
-      // The boundary widgets between pages N and N+1 carry `data-page-frame`
-      // for the *next* page (pages 1 … N).  Page 0 has no widget before it,
-      // so we synthesize an in-memory element that carries page-0's attributes.
-      // This element is NOT in the DOM — the IntersectionObserver won't fire
-      // on it — but the hook's useMemo uses it to look up block indices when
-      // the overscan expansion includes page 0 (which happens whenever any of
-      // pages 1-2 are visible with overscan ≥ 1).
-      const hasPage0 = found.some(
-        (el) => el.getAttribute("data-page-frame") === "0",
-      );
-      if (!hasPage0 && found.length > 0) {
-        // Derive page-0 block range from the snapshot surface: page 0 starts
-        // at block 0 and ends just before the first block that belongs to page 1.
-        // The boundary widget's `data-page-first-block-index` for page 1 tells
-        // us where page 0 ends.
-        const page1Marker = found.find(
-          (el) => el.getAttribute("data-page-frame") === "1",
-        );
-        const page1First = page1Marker
-          ? Number(page1Marker.getAttribute("data-page-first-block-index") ?? "")
-          : NaN;
-        const page0Last = Number.isFinite(page1First) && page1First > 0
-          ? page1First - 1
-          : -1;  // page 0 empty or unknown; synthetic marker contributes nothing.
-        const ownerDoc = found[0]!.ownerDocument;
-        const synth = ownerDoc.createElement("span");
-        synth.setAttribute("data-page-frame", "0");
-        synth.setAttribute("data-page-first-block-index", "0");
-        synth.setAttribute("data-page-last-block-index", String(Math.max(0, page0Last)));
-        setPageMarkers([synth, ...found]);
-      } else {
-        setPageMarkers(found);
-      }
-    };
-    refresh();
-    // Observe PM surface mutations for page-count changes (new doc load, etc).
-    const view = root.ownerDocument?.defaultView;
-    if (!view?.MutationObserver) return undefined;
-    const mo = new view.MutationObserver(refresh);
-    mo.observe(root, { childList: true, subtree: true });
-    return () => mo.disconnect();
-    // Re-run when the scroll root changes OR when a new snapshot lands
-    // (which may have a different page count and new widgets in the PM DOM).
-    // NOTE: snapshot.surface is intentionally excluded — its reference changes on
-    // every requestViewportRefresh(), which would add two extra render passes per
-    // scroll event.  The page-0 fallback uses -1 when page1First is unknown,
-    // which is correct (no page-0 blocks → synthetic marker contributes nothing).
-  }, [pageStackScrollRoot, snapshot.revisionToken]);
-
-  // Derive the surface block index for the current selection head so the
-  // hook can extend the visible range to always include the selection.
-  const selectionBlockIndex = useMemo(() => {
-    const sel = snapshot.selection;
-    const blocks = snapshot.surface?.blocks;
-    if (!sel || !blocks) return null;
-    for (let i = 0; i < blocks.length; i++) {
-      const block = blocks[i]!;  // from/to are required on all SurfaceBlockSnapshot variants
-      const blockFrom = block.from;
-      const blockTo = block.to;
-      if (sel.head >= blockFrom && sel.head <= blockTo) return i;
-    }
-    return null;
-  }, [snapshot.selection, snapshot.surface]);
-
-  const visibleBlockRange = useVisibleBlockRange({
-    pageMarkers,
-    overscanPages: 2,
-    selectionBlockIndex,
-    totalBlockCount: snapshot.surface?.blocks.length ?? 0,
+  // Audit §2.5 — context band mounts as a composition-level sibling of
+  // the toolbar so the workspace row becomes
+  //   [toolbar left cluster] · [context band] · [toolbar right cluster]
+  // and the band can render mode-owned content (Phase B.3 additive mount;
+  // Phase D migrates role-action contents into the band and retires the
+  // legacy inline role region inside TwToolbar).
+  //
+  // `resolveChromeComposition` is pure but each call allocates new Sets +
+  // arrays.  `TwReviewWorkspace` re-renders on every PM transaction (the
+  // inverted-truth architecture calls `view.updateState()` wholesale) so
+  // we `useMemo` to keep downstream React.memo consumers stable across
+  // commits — perf invariant #4.  `readOnly` is intentionally omitted:
+  // TwReviewWorkspaceProps doesn't expose it and the composition seam is
+  // independent of read-only posture today; Phase E will thread it
+  // through the interactionGuardSnapshot wiring once the rail owns the
+  // full posture composition.
+  const diagnosticsSignal = useDiagnosticsSignal({
+    snapshot,
+    caps,
+    preserveOnlyCount,
+    blockedReasonsCount: blockedReasons.length,
   });
+  const healthIssueCount = diagnosticsSignal.count;
 
-  // L7 Phase 2.8 — viewport cull for `TwPageStackChromeLayer`. Returns
-  // `null` while the IntersectionObserver hasn't reported yet; the chrome
-  // layer treats null as "render every page" so first paint is
-  // unaffected. Once the observer fires, the chrome layer only mounts
-  // bands for pages inside `[start, end)` plus overscan, eliminating the
-  // measured 412 ms Layout + 229 ms Pre-paint cost on 138-pp extra-large.
-  const visiblePageIndexRange = useVisiblePageIndexRange({
-    pageMarkers,
-    overscanPages: 2,
+  const composition = useWorkspaceComposition({
+    chromePreset,
+    chromeOptions: props.chromeOptions,
+    reviewMode: props.reviewMode,
+    role: viewState.editorRole,
+    markupDisplay: props.markupDisplay,
+    diagnosticsSignal,
   });
+  const showHealthRailTab = composition.rail.visibleTabs.has("health");
 
-  // Push the visible range into the layout facet (which delegates to the
-  // runtime's viewport-culling machinery).  Depend on `[start, end]` values
-  // (not the range object) so identity-preserving updates are a no-op.
-  useEffect(() => {
-    if (!props.layoutFacet) return;
-    props.layoutFacet.setVisibleBlockRange(visibleBlockRange);
-    props.layoutFacet.requestViewportRefresh();
-  }, [props.layoutFacet, visibleBlockRange.start, visibleBlockRange.end]);
-
-  const dismissSelectionToolbar = useCallback(() => {
-    props.onDismissSelectionToolbar?.();
-  }, [props.onDismissSelectionToolbar]);
-
-  const runWithSelectionToolbarDismiss = useCallback(
-    (action?: () => void) => () => {
-      dismissSelectionToolbar();
-      action?.();
-    },
-    [dismissSelectionToolbar],
-  );
-
-  useEffect(() => {
-    if (!responsiveChrome.showDrawerReviewRail || typeof window === "undefined") {
-      return;
-    }
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== "Escape") {
-        return;
-      }
-
-      setReviewRailOpen(false);
-    };
-
-    window.addEventListener("keydown", handleKeyDown);
-    return () => {
-      window.removeEventListener("keydown", handleKeyDown);
-    };
-  }, [responsiveChrome.showDrawerReviewRail]);
-
-  useEffect(() => {
-    if (!props.layoutFacet) return;
-    const facet = props.layoutFacet;
-    const fontSet = document.fonts;
-    if (!fontSet?.ready) {
-      facet.swapMeasurementProvider(createCanvasBackend());
-      return;
-    }
-    void fontSet.ready.then(() => {
-      facet.swapMeasurementProvider(createCanvasBackend());
-    });
-  }, [props.layoutFacet]);
+  const arbiter = useWorkspaceArbiter();
 
   return (
+    <LocalSurfaceArbiterContext.Provider value={arbiter}>
     <Tooltip.Provider delayDuration={400}>
       <div className="flex h-full flex-col bg-canvas text-primary">
-        {props.shellHeader}
+        {renderedShell}
+        {/*
+         * The context band is a workspace-layer surface (DESIGN-EDITOR.md
+         * §4.2) and therefore gated on the toolbar-layer visibility flag
+         * — the `selection` chrome preset suppresses both toolbar and
+         * band so minimal embeds stay chrome-free.  If a future preset
+         * wants the band without the formatting toolbar, introduce a
+         * dedicated `chromeVisibility.contextBand` flag rather than
+         * decoupling this branch.
+         */}
+        {/*
+         * Chrome Closure Pass · Task 1 (designsystem.md §6.3) — the
+         * role-action region used to render inline in the toolbar's
+         * center subregion. It now lives inside `TwContextBand` so the
+         * workspace row reads
+         *   [shell header] · [TwContextBand carrying role actions] · [TwToolbar (formatting only)]
+         * matching §8.8.1's "Workspace context row / mode-owned band"
+         * row. Callbacks below mirror what was previously threaded
+         * through `ChromePresetToolbar` to `TwRoleActionRegion`; the
+         * toolbar still receives `role` for `isChromeItemOwnedByRoleRegion`
+         * deferral but no longer renders the region itself.
+         */}
+        {chromeVisibility.toolbar ? (
+          <TwContextBand mode={composition.mode}>
+            {viewState.editorRole ? (
+              <TwRoleActionRegion
+                role={viewState.editorRole}
+                policy={scopedChromePolicy}
+                compactMode={responsiveChrome.isNarrow}
+                reviewQueue={props.reviewQueue}
+                markupDisplay={markupDisplay}
+                canAddComment={
+                  toolbarInteractionPolicy?.canAddComment ??
+                  (caps ? caps.canAddComment : false)
+                }
+                showTrackedChanges={props.showTrackedChanges}
+                capabilities={caps}
+                onAddComment={
+                  props.onAddComment
+                    ? runWithSelectionToolbarDismiss(props.onAddComment)
+                    : undefined
+                }
+                onShowTrackedChangesChange={(show) => {
+                  dismissSelectionToolbar();
+                  props.onShowTrackedChangesChange(show);
+                }}
+                onReviewSidebarTrackedChanges={
+                  props.onReviewSidebarTrackedChanges
+                    ? runWithSelectionToolbarDismiss(props.onReviewSidebarTrackedChanges)
+                    : undefined
+                }
+                onReviewSidebarComments={
+                  props.onReviewSidebarComments
+                    ? runWithSelectionToolbarDismiss(props.onReviewSidebarComments)
+                    : undefined
+                }
+                onMarkScopePosture={
+                  props.onMarkSectionForReview
+                    ? runWithSelectionToolbarDismiss(props.onMarkSectionForReview)
+                    : undefined
+                }
+                onReviewPrev={
+                  props.onGoToPreviousReviewItem
+                    ? runWithSelectionToolbarDismiss(props.onGoToPreviousReviewItem)
+                    : undefined
+                }
+                onReviewNext={
+                  props.onGoToNextReviewItem
+                    ? runWithSelectionToolbarDismiss(props.onGoToNextReviewItem)
+                    : undefined
+                }
+                onReviewAccept={(() => {
+                  const active = props.reviewQueue?.items[props.reviewQueue.activeIndex];
+                  if (active?.kind !== "change" || !props.onAcceptRevision) {
+                    return undefined;
+                  }
+                  const revisionId = active.itemId;
+                  return () => {
+                    dismissSelectionToolbar();
+                    props.onAcceptRevision?.(revisionId);
+                  };
+                })()}
+                onReviewReject={(() => {
+                  const active = props.reviewQueue?.items[props.reviewQueue.activeIndex];
+                  if (active?.kind !== "change" || !props.onRejectRevision) {
+                    return undefined;
+                  }
+                  const revisionId = active.itemId;
+                  return () => {
+                    dismissSelectionToolbar();
+                    props.onRejectRevision?.(revisionId);
+                  };
+                })()}
+                onReviewAcceptAll={
+                  props.onAcceptAllChanges
+                    ? runWithSelectionToolbarDismiss(props.onAcceptAllChanges)
+                    : undefined
+                }
+                onReviewRejectAll={
+                  props.onRejectAllChanges
+                    ? runWithSelectionToolbarDismiss(props.onRejectAllChanges)
+                    : undefined
+                }
+              />
+            ) : null}
+          </TwContextBand>
+        ) : null}
+        {/*
+         * Phase C.γ.3 — mount the workspace chrome host when the
+         * integrator has wired an editor-action bag.  Omitting the
+         * bag preserves pre-C behavior.  Renders portals + a global
+         * palette listener; adds no DOM on the edit path.
+         */}
+        {props.editorActionHost ? (
+          <TwWorkspaceChromeHost
+            mode={composition.mode}
+            editorActionHost={props.editorActionHost}
+            {...(props.chromeControllerRef
+              ? { controllerRef: props.chromeControllerRef }
+              : {})}
+            {...(props.commandPaletteDisabled !== undefined
+              ? { paletteDisabled: props.commandPaletteDisabled }
+              : {})}
+            // Chrome Closure Pass · Task 3 — thread the live table
+            // context into the chrome host so the right-click menu
+            // augments target-kinds with the matching tier.
+            tableContext={props.tableContext ?? null}
+            onOpenRailTab={(tab) => {
+              setReviewRailOpen(true);
+              props.onActiveRailTabChange?.(tab);
+            }}
+          />
+        ) : null}
         {chromeVisibility.toolbar ? (
           <div className="px-3 pt-3">
             <ChromePresetToolbar
@@ -1140,6 +566,10 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
               interactionPolicy={toolbarInteractionPolicy}
               scopedChromePolicy={scopedChromePolicy}
               compactMode={responsiveChrome.isNarrow}
+              onOpenHealthRail={() => {
+                setReviewRailOpen(true);
+                props.onActiveRailTabChange?.("health");
+              }}
               workspaceMode={props.workspaceMode}
               zoomLevel={props.zoomLevel}
               formattingState={props.formattingState}
@@ -1305,99 +735,23 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
           snapshot={snapshot}
           preserveOnlyCount={preserveOnlyCount}
           workflowBlockedReasons={blockedReasons}
+          onShowDetail={() => {
+            setReviewRailOpen(true);
+            props.onActiveRailTabChange?.("health");
+          }}
         /> : null}
 
         <div className="relative flex flex-1 min-h-0">
-          {/* Collapsible document navigator — page mode only */}
-          {isPageWorkspace && chromeVisibility.pageChrome ? (
-            <aside
-              aria-label="Document navigator"
-              className={`shrink-0 border-r border-border bg-surface transition-[width] duration-200 ${
-                navOpen ? "w-48" : "w-0"
-              } overflow-hidden`}
-            >
-              {navOpen ? (
-                <div className="flex h-full flex-col">
-                  <div className="flex items-center justify-between px-3 py-2 border-b border-border">
-                    <span className="text-xs font-medium text-secondary uppercase tracking-wider">Navigator</span>
-                    <Tooltip.Root>
-                      <Tooltip.Trigger asChild>
-                        <button
-                          type="button"
-                          aria-label="Collapse navigator"
-                          onMouseDown={preserveEditorSelectionMouseDown}
-                          onClick={() => {
-                            dismissSelectionToolbar();
-                            setNavOpen(false);
-                          }}
-                          className="inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary hover:bg-surface-hover transition-colors"
-                        >
-                          <ChevronLeft className="h-3.5 w-3.5" />
-                        </button>
-                      </Tooltip.Trigger>
-                      <Tooltip.Portal>
-                        <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
-                          Collapse navigator
-                        </Tooltip.Content>
-                      </Tooltip.Portal>
-                    </Tooltip.Root>
-                  </div>
-                  <nav className="flex-1 overflow-y-auto px-2 py-2" aria-label="Document headings">
-                    {headings.length > 0 ? (
-                      <ul className="space-y-0.5">
-                        {headings.map((entry) => (
-                          <li key={entry.headingId}>
-                            <button
-                              type="button"
-                              className="block w-full truncate rounded-md px-2 py-1 text-left text-xs text-primary hover:bg-surface-hover"
-                              style={{ paddingLeft: `${8 + (entry.level - 1) * 12}px` }}
-                              onMouseDown={preserveEditorSelectionMouseDown}
-                              onClick={() => {
-                                dismissSelectionToolbar();
-                                props.onNavigateHeading?.(entry.headingId);
-                                setNavOpen(false);
-                              }}
-                            >
-                              {entry.text}
-                            </button>
-                          </li>
-                        ))}
-                      </ul>
-                    ) : (
-                      <p className="px-2 py-4 text-xs text-tertiary">No headings found.</p>
-                    )}
-                  </nav>
-                </div>
-              ) : null}
-            </aside>
-          ) : null}
-
-          {/* Navigator expand toggle — page mode only when collapsed */}
-          {isPageWorkspace && chromeVisibility.pageChrome && !navOpen ? (
-            <div className="shrink-0 flex items-start pt-2 pl-1">
-              <Tooltip.Root>
-                <Tooltip.Trigger asChild>
-                  <button
-                    type="button"
-                    aria-label="Open document navigator"
-                    onMouseDown={preserveEditorSelectionMouseDown}
-                    onClick={() => {
-                      dismissSelectionToolbar();
-                      setNavOpen(true);
-                    }}
-                    className="inline-flex h-7 w-7 items-center justify-center rounded-md text-secondary hover:bg-surface-hover transition-colors"
-                  >
-                    <List className="h-3.5 w-3.5" />
-                  </button>
-                </Tooltip.Trigger>
-                <Tooltip.Portal>
-                  <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
-                    Open document navigator
-                  </Tooltip.Content>
-                </Tooltip.Portal>
-              </Tooltip.Root>
-            </div>
-          ) : null}
+          <TwReviewWorkspaceNavigator
+            enabled={isPageWorkspace && chromeVisibility.pageChrome}
+            navOpen={navOpen}
+            setNavOpen={setNavOpen}
+            headings={headings}
+            {...(props.onNavigateHeading
+              ? { onNavigateHeading: props.onNavigateHeading }
+              : {})}
+            dismissSelectionToolbar={dismissSelectionToolbar}
+          />
 
           {/* Document column */}
           <div className="flex flex-1 flex-col min-w-0">
@@ -1414,157 +768,38 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                     : "wre-canvas-surface relative my-8 overflow-hidden"
                 }`}
                 data-zoom-bucket={pageZoomBucket}
-                data-zoom-scale={isPageWorkspace ? zoomScale : undefined}
                 data-workspace-canvas={isPageWorkspace ? "true" : undefined}
                 data-workspace-mode={isPageWorkspace ? "page" : "canvas"}
               >
-                {isPageWorkspace && chromeVisibility.pageChrome && snapshot.pageLayout ? (
-                  <div className="border-b border-border/70 bg-surface/65 px-5 py-3" data-testid="page-context-summary">
-                    <div className="flex flex-wrap items-center justify-between gap-2">
-                      <div className="flex flex-wrap items-center gap-2 text-xs text-secondary">
-                        <span className="rounded-full bg-canvas px-2 py-1 font-medium text-primary">
-                          {activePage
-                            ? `Page ${activePage.pageIndex + 1} of ${props.documentNavigation?.pageCount ?? 1}`
-                            : "Page workspace"}
-                        </span>
-                        <span>{`Section ${snapshot.pageLayout.sectionIndex + 1}`}</span>
-                        <span className="uppercase tracking-[0.12em] text-tertiary">
-                          {snapshot.pageLayout.orientation}
-                        </span>
-                      </div>
-                      <div className="flex items-center gap-2">
-                        {snapshot.activeStory.kind !== "main" ? (
-                          <button
-                            type="button"
-                            aria-label="Return to document body"
-                            onMouseDown={preserveEditorSelectionMouseDown}
-                            onClick={runWithSelectionToolbarDismiss(props.onCloseStory)}
-                            className="inline-flex items-center gap-1 rounded-md border border-border bg-canvas px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface"
-                          >
-                            Body
-                          </button>
-                        ) : null}
-                        {snapshot.activeStory.kind === "main" && snapshot.pageLayout.sectionIndex > 0 ? (
-                          <>
-                            <button
-                              type="button"
-                              aria-label="Link header to previous"
-                              disabled={!props.onSetHeaderFooterLink || !allowLocalChromeMutations}
-                              onMouseDown={preserveEditorSelectionMouseDown}
-                              onClick={() => {
-                                dismissSelectionToolbar();
-                                props.onSetHeaderFooterLink?.(snapshot.pageLayout!.sectionIndex, {
-                                  kind: "header",
-                                  variant: headerVariant,
-                                  linkToPrevious: true,
-                                });
-                              }}
-                              className="inline-flex items-center gap-1 rounded-md border border-border bg-canvas px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface disabled:cursor-not-allowed disabled:opacity-40"
-                            >
-                              Link header
-                            </button>
-                            <button
-                              type="button"
-                              aria-label="Link footer to previous"
-                              disabled={!props.onSetHeaderFooterLink || !allowLocalChromeMutations}
-                              onMouseDown={preserveEditorSelectionMouseDown}
-                              onClick={() => {
-                                dismissSelectionToolbar();
-                                props.onSetHeaderFooterLink?.(snapshot.pageLayout!.sectionIndex, {
-                                  kind: "footer",
-                                  variant: footerVariant,
-                                  linkToPrevious: true,
-                                });
-                              }}
-                              className="inline-flex items-center gap-1 rounded-md border border-border bg-canvas px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface disabled:cursor-not-allowed disabled:opacity-40"
-                            >
-                              Link footer
-                            </button>
-                          </>
-                        ) : null}
-                        <button
-                          type="button"
-                          aria-label="Toggle layout tools"
-                          aria-expanded={layoutToolsOpen}
-                          onMouseDown={preserveEditorSelectionMouseDown}
-                          onClick={() => {
-                            dismissSelectionToolbar();
-                            setLayoutToolsOpen((open) => !open);
-                          }}
-                          className="inline-flex items-center gap-1 rounded-md border border-border bg-canvas px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface"
-                        >
-                          <ChevronRight className={`h-3.5 w-3.5 transition-transform ${layoutToolsOpen ? "rotate-90" : ""}`} />
-                          Layout tools
-                        </button>
-                      </div>
-                    </div>
-                  </div>
-                ) : null}
-                {isPageWorkspace && chromeVisibility.pageChrome && snapshot.pageLayout && layoutToolsOpen ? (
-                  <div className="px-5 pt-3">
-                    <TwPageRuler
-                      pageLayout={snapshot.pageLayout}
-                      viewState={viewState}
-                      paragraphLayout={activeParagraphLayout}
-                      readOnly={pageChromeReadOnly}
-                      onReturnToBody={props.onCloseStory
-                        ? runWithSelectionToolbarDismiss(props.onCloseStory)
-                        : () => undefined}
-                      onOpenHeader={props.onOpenHeaderStory
-                        ? runWithSelectionToolbarDismiss(props.onOpenHeaderStory)
-                        : undefined}
-                      onOpenFooter={props.onOpenFooterStory
-                        ? runWithSelectionToolbarDismiss(props.onOpenFooterStory)
-                        : undefined}
-                      onSetIndentation={props.onSetParagraphIndentation
-                        ? (indentation) => {
-                          dismissSelectionToolbar();
-                          props.onSetParagraphIndentation?.(indentation);
-                        }
-                        : undefined}
-                      onSetTabStops={props.onSetParagraphTabStops
-                        ? (tabStops) => {
-                          dismissSelectionToolbar();
-                          props.onSetParagraphTabStops?.(tabStops);
-                        }
-                        : undefined}
-                      onRestartNumbering={props.onRestartNumbering
-                        ? runWithSelectionToolbarDismiss(props.onRestartNumbering)
-                        : undefined}
-                      onContinueNumbering={props.onContinueNumbering
-                        ? runWithSelectionToolbarDismiss(props.onContinueNumbering)
-                        : undefined}
-                    />
-                    <TwLayoutPanel
-                      pageLayout={snapshot.pageLayout}
-                      readOnly={pageChromeReadOnly}
-                      onInsertSectionBreak={props.onInsertSectionBreak
-                        ? (type) => {
-                          dismissSelectionToolbar();
-                          props.onInsertSectionBreak?.(type);
-                        }
-                        : undefined}
-                      onDeleteSectionBreak={props.onDeleteSectionBreak
-                        ? (sectionIndex) => {
-                          dismissSelectionToolbar();
-                          props.onDeleteSectionBreak?.(sectionIndex);
-                        }
-                        : undefined}
-                      onUpdateSectionLayout={props.onUpdateSectionLayout
-                        ? (sectionIndex, patch) => {
-                          dismissSelectionToolbar();
-                          props.onUpdateSectionLayout?.(sectionIndex, patch);
-                        }
-                        : undefined}
-                      onSetSectionPageNumbering={props.onSetSectionPageNumbering
-                        ? (sectionIndex, patch) => {
-                          dismissSelectionToolbar();
-                          props.onSetSectionPageNumbering?.(sectionIndex, patch);
-                        }
-                        : undefined}
-                    />
-                  </div>
-                ) : null}
+                <TwReviewWorkspacePageToolbar
+                  enabled={isPageWorkspace && chromeVisibility.pageChrome && Boolean(snapshot.pageLayout)}
+                  pageLayout={snapshot.pageLayout}
+                  activeStory={snapshot.activeStory}
+                  activePage={activePage}
+                  pageCount={props.documentNavigation?.pageCount ?? 1}
+                  headerVariant={headerVariant}
+                  footerVariant={footerVariant}
+                  allowLocalChromeMutations={allowLocalChromeMutations}
+                  pageChromeReadOnly={pageChromeReadOnly}
+                  layoutToolsOpen={layoutToolsOpen}
+                  setLayoutToolsOpen={setLayoutToolsOpen}
+                  viewState={viewState}
+                  activeParagraphLayout={activeParagraphLayout}
+                  dismissSelectionToolbar={dismissSelectionToolbar}
+                  runWithSelectionToolbarDismiss={runWithSelectionToolbarDismiss}
+                  {...(props.onCloseStory ? { onCloseStory: props.onCloseStory } : {})}
+                  {...(props.onOpenHeaderStory ? { onOpenHeaderStory: props.onOpenHeaderStory } : {})}
+                  {...(props.onOpenFooterStory ? { onOpenFooterStory: props.onOpenFooterStory } : {})}
+                  {...(props.onSetHeaderFooterLink ? { onSetHeaderFooterLink: props.onSetHeaderFooterLink } : {})}
+                  {...(props.onSetParagraphIndentation ? { onSetParagraphIndentation: props.onSetParagraphIndentation } : {})}
+                  {...(props.onSetParagraphTabStops ? { onSetParagraphTabStops: props.onSetParagraphTabStops } : {})}
+                  {...(props.onRestartNumbering ? { onRestartNumbering: props.onRestartNumbering } : {})}
+                  {...(props.onContinueNumbering ? { onContinueNumbering: props.onContinueNumbering } : {})}
+                  {...(props.onInsertSectionBreak ? { onInsertSectionBreak: props.onInsertSectionBreak } : {})}
+                  {...(props.onDeleteSectionBreak ? { onDeleteSectionBreak: props.onDeleteSectionBreak } : {})}
+                  {...(props.onUpdateSectionLayout ? { onUpdateSectionLayout: props.onUpdateSectionLayout } : {})}
+                  {...(props.onSetSectionPageNumbering ? { onSetSectionPageNumbering: props.onSetSectionPageNumbering } : {})}
+                />
                 {chromeVisibility.selectionOverlay &&
                 gatedSelectionTool &&
                 shouldRenderSelectionToolKind(scopedChromePolicy, gatedSelectionTool.kind) ? (
@@ -1624,6 +859,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                   }
                   data-line-numbering={pageChromeModel.lineNumberingEnabled ? "enabled" : "disabled"}
                   data-paper-frame={isPageWorkspace ? "true" : undefined}
+                  data-zoom-scale={zoomScale}
                   data-debug-page-layout={
                     isPageWorkspace && snapshot.pageLayout
                       ? `${snapshot.pageLayout.pageWidth}:${snapshot.pageLayout.pageHeight}:${snapshot.pageLayout.orientation}:${snapshot.pageLayout.sectionIndex}`
@@ -1646,7 +882,15 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                             : {}),
                           ...(zoomScale !== 1 ? { zoom: zoomScale } : {}),
                         }
-                      : undefined
+                      : zoomScale !== 1
+                        ? // U2 fix — canvas mode's zoom control was a no-op
+                          // because this wrapper only applied `zoom:` in page
+                          // mode.  Toolbar advertises "Zoom controls —
+                          // available in all workspace modes", so canvas must
+                          // honor it too.  Same CSS `zoom` property as page
+                          // mode for consistent overlay/selection math.
+                          { zoom: zoomScale }
+                        : undefined
                   }
                 >
                   {/* N1 (L8 Phase D): per-page paper card backgrounds at z-0,
@@ -1656,6 +900,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                   {isPageWorkspace && chromeVisibility.pageChrome && props.layoutFacet ? (
                     <TwPageStackOverlayLayer
                       facet={props.layoutFacet}
+                      geometryFacet={props.geometryFacet}
                       scrollRoot={pageStackScrollRoot}
                       renderFrameRevision={renderFrameRevision}
                       visiblePageIndexRange={visiblePageIndexRange}
@@ -1665,6 +910,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                   {isPageWorkspace && chromeVisibility.pageChrome && props.layoutFacet ? (
                     <TwFloatingImageLayer
                       facet={props.layoutFacet}
+                      geometryFacet={props.geometryFacet}
                       scrollRoot={pageStackScrollRoot}
                       renderFrameRevision={renderFrameRevision}
                       visiblePageIndexRange={visiblePageIndexRange}
@@ -1730,6 +976,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                         {isPageWorkspace && chromeVisibility.pageChrome && props.layoutFacet ? (
                           <TwFloatingImageLayer
                             facet={props.layoutFacet}
+                            geometryFacet={props.geometryFacet}
                             scrollRoot={pageStackScrollRoot}
                             renderFrameRevision={renderFrameRevision}
                             visiblePageIndexRange={visiblePageIndexRange}
@@ -1739,9 +986,11 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                             onActivateFloatingImage={props.onActivateFloatingImage}
                           />
                         ) : null}
-                        {props.layoutFacet ? (
+                        {props.layoutFacet && props.geometryFacet ? (
                           <TwChromeOverlay
                             facet={props.layoutFacet}
+                            geometryFacet={props.geometryFacet}
+                            workflowFacet={props.workflowFacet ?? null}
                             grabbedObjectId={snapshot.grabbedObjectId ?? null}
                             grabbedObjectFromOffset={grabbedSegmentOffsets?.from ?? null}
                             grabbedObjectToOffset={grabbedSegmentOffsets?.to ?? null}
@@ -1757,17 +1006,17 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                             onScopeCardModeChange={handleScopeCardModeChange}
                             onScopeCardIssueAction={handleScopeCardIssueAction}
                             onScopeCardAcceptSuggestionGroup={
-                              onScopeAcceptSuggestionGroup
+                              props.onScopeAcceptSuggestionGroup
                                 ? handleScopeCardAcceptSuggestionGroup
                                 : undefined
                             }
                             onScopeCardRejectSuggestionGroup={
-                              onScopeRejectSuggestionGroup
+                              props.onScopeRejectSuggestionGroup
                                 ? handleScopeCardRejectSuggestionGroup
                                 : undefined
                             }
                             onScopeCardAskAgent={
-                              onScopeAskAgent
+                              props.onScopeAskAgent
                                 ? handleScopeCardAskAgent
                                 : undefined
                             }
@@ -1815,590 +1064,60 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
           </div>
 
           {/* Review rail — docked on desktop, drawer-backed on narrow layouts */}
-          {responsiveChrome.showDockedReviewRail ? <TwReviewRail
-            activeTab={props.activeRailTab}
-            currentUserId={props.currentUserId}
-            comments={snapshot.comments}
-            trackedChanges={snapshot.trackedChanges}
-            compatibility={snapshot.compatibility}
-            warnings={snapshot.warnings}
-            markupDisplay={markupDisplay}
-            contextAnalytics={
-              chromeVisibility.contextAnalytics
-                ? props.currentScopeContextAnalytics
-                : null
+          <TwReviewWorkspaceRail
+            mode={
+              (responsiveChrome.showDockedReviewRail
+                ? "docked"
+                : responsiveChrome.showDrawerReviewRail
+                  ? "drawer"
+                  : "hidden") satisfies TwReviewWorkspaceRailMode
             }
-            activeCommentId={props.activeCommentId}
-            activeRevisionId={props.activeRevisionId}
-            onActiveTabChange={props.onActiveRailTabChange}
-            onOpenComment={props.onOpenComment}
-            onResolveComment={props.onResolveComment}
-            onReopenComment={props.onReopenComment}
-            onAddReply={props.onAddReply}
-            onEditBody={props.onEditBody}
-            onOpenRevision={props.onOpenRevision}
-            onAcceptRevision={props.onAcceptRevision}
-            onRejectRevision={props.onRejectRevision}
-            onAcceptAllChanges={props.onAcceptAllChanges}
-            onRejectAllChanges={props.onRejectAllChanges}
-            scopeRailSegments={props.layoutFacet?.getAllScopeRailSegments?.() ?? []}
-            workflowTab={props.reviewRailWorkflowTab}
-            workflowCount={props.reviewRailWorkflowCount}
-            workflowScopesTitle={props.reviewRailWorkflowScopesTitle}
-            intelligenceEyebrow={props.reviewRailIntelligenceEyebrow}
-            intelligenceHeader={props.reviewRailIntelligenceHeader}
-            railFooter={props.reviewRailFooter}
-          /> : null}
-
-          {responsiveChrome.showDrawerReviewRail ? (
-            <div
-              className="pointer-events-none absolute inset-0 z-30 flex justify-end"
-              data-testid="review-rail-drawer"
-            >
-              <button
-                type="button"
-                aria-label="Close sidebar overlay"
-                className="pointer-events-auto absolute inset-0 border-0 bg-[color:rgba(21,26,23,0.08)] dark:bg-[color:rgba(0,0,0,0.32)]"
-                onClick={() => setReviewRailOpen(false)}
-              />
-              <div className="pointer-events-auto relative h-full">
-                <TwReviewRail
-                  variant="drawer"
-                  activeTab={props.activeRailTab}
-                  currentUserId={props.currentUserId}
-                  comments={snapshot.comments}
-                  trackedChanges={snapshot.trackedChanges}
-                  compatibility={snapshot.compatibility}
-                  warnings={snapshot.warnings}
-                  markupDisplay={markupDisplay}
-                  contextAnalytics={
-                    chromeVisibility.contextAnalytics
-                      ? props.currentScopeContextAnalytics
-                      : null
-                  }
-                  activeCommentId={props.activeCommentId}
-                  activeRevisionId={props.activeRevisionId}
-                  onActiveTabChange={props.onActiveRailTabChange}
-                  onOpenComment={props.onOpenComment}
-                  onResolveComment={props.onResolveComment}
-                  onReopenComment={props.onReopenComment}
-                  onAddReply={props.onAddReply}
-                  onEditBody={props.onEditBody}
-                  onOpenRevision={props.onOpenRevision}
-                  onAcceptRevision={props.onAcceptRevision}
-                  onRejectRevision={props.onRejectRevision}
-                  onAcceptAllChanges={props.onAcceptAllChanges}
-                  onRejectAllChanges={props.onRejectAllChanges}
-                  scopeRailSegments={props.layoutFacet?.getAllScopeRailSegments?.() ?? []}
-                  workflowTab={props.reviewRailWorkflowTab}
-                  workflowCount={props.reviewRailWorkflowCount}
-                  workflowScopesTitle={props.reviewRailWorkflowScopesTitle}
-                  intelligenceEyebrow={props.reviewRailIntelligenceEyebrow}
-                  intelligenceHeader={props.reviewRailIntelligenceHeader}
-                  railFooter={props.reviewRailFooter}
-                />
-              </div>
-            </div>
-          ) : null}
-        </div>
-        {props.modeDock && props.experimental?.showModeDock === true ? (
-          <TwModeDock
-            label={props.modeDock.label}
-            icon={props.modeDock.icon}
-            actions={props.modeDock.actions}
+            onDrawerClose={() => setReviewRailOpen(false)}
+            rail={{
+              activeTab: props.activeRailTab,
+              currentUserId: props.currentUserId,
+              comments: snapshot.comments,
+              trackedChanges: snapshot.trackedChanges,
+              compatibility: snapshot.compatibility,
+              warnings: snapshot.warnings,
+              markupDisplay,
+              contextAnalytics: chromeVisibility.contextAnalytics
+                ? props.currentScopeContextAnalytics
+                : null,
+              activeCommentId: props.activeCommentId,
+              activeRevisionId: props.activeRevisionId,
+              onActiveTabChange: props.onActiveRailTabChange,
+              onOpenComment: props.onOpenComment,
+              onResolveComment: props.onResolveComment,
+              onReopenComment: props.onReopenComment,
+              onAddReply: props.onAddReply,
+              onEditBody: props.onEditBody,
+              onOpenRevision: props.onOpenRevision,
+              onAcceptRevision: props.onAcceptRevision,
+              onRejectRevision: props.onRejectRevision,
+              onAcceptAllChanges: props.onAcceptAllChanges,
+              onRejectAllChanges: props.onRejectAllChanges,
+              // Slice 4C rail-seam inversion: segments now come from the
+              // Layer-06 workflow facet. Layout facet no longer exposes
+              // `getAllScopeRailSegments` (methods removed in v40 / Slice 4C).
+              scopeRailSegments: props.workflowFacet?.getAllRailSegments() ?? [],
+              workflowTab: props.reviewRailWorkflowTab,
+              workflowCount: props.reviewRailWorkflowCount,
+              workflowScopesTitle: props.reviewRailWorkflowScopesTitle,
+              intelligenceEyebrow: props.reviewRailIntelligenceEyebrow,
+              intelligenceHeader: props.reviewRailIntelligenceHeader,
+              railFooter: props.reviewRailFooter,
+              showHealthTab: showHealthRailTab,
+              healthIssueCount,
+              ...(diagnosticsSignal.severity !== "none"
+                ? { healthSeverity: diagnosticsSignal.severity }
+                : {}),
+              workflowBlockedReasons: blockedReasons,
+            }}
           />
-        ) : null}
+        </div>
       </div>
     </Tooltip.Provider>
+    </LocalSurfaceArbiterContext.Provider>
   );
 }
-
-function readViewportWidth(): number | undefined {
-  return typeof window === "undefined" ? undefined : window.innerWidth;
-}
-
-function readViewportHeight(): number | undefined {
-  return typeof window === "undefined" ? undefined : window.innerHeight;
-}
-
-function shouldHidePageBorderForSelection(
-  selection: EditorViewStateSnapshot["selection"],
-): boolean {
-  if (selection.isCollapsed) {
-    return false;
-  }
-
-  return selection.activeRange.kind === "range";
-}
-
-function resolveActiveParagraphLayout(
-  surface: RuntimeRenderSnapshot["surface"],
-  position: number,
-): {
-  leftIndent: number;
-  rightIndent: number;
-  firstLineOffset: number;
-  tabStops: Array<{ pos: number; val?: string; leader?: string }>;
-  indentationReadOnly?: boolean;
-  tabStopsReadOnly?: boolean;
-} | null {
-  const paragraph = surface ? findActiveParagraph(surface.blocks, position) : null;
-  if (!paragraph) {
-    return null;
-  }
-  const resolvedIndentation = paragraph.resolvedNumbering?.geometry.indentation;
-  const resolvedTabStops = paragraph.resolvedNumbering?.geometry.tabStops;
-  const indentation = resolvedIndentation ?? paragraph.indentation;
-  const tabStops = resolvedTabStops ?? paragraph.tabStops;
-
-  return {
-    leftIndent: indentation?.left ?? 0,
-    rightIndent: indentation?.right ?? 0,
-    firstLineOffset:
-      indentation?.firstLine ??
-      (indentation?.hanging ? -indentation.hanging : 0),
-    tabStops: tabStops ? [...tabStops] : [],
-    indentationReadOnly:
-      Boolean(resolvedIndentation) &&
-      !areIndentationsEqual(resolvedIndentation, paragraph.indentation),
-    tabStopsReadOnly:
-      Boolean(resolvedTabStops) &&
-      !areTabStopsEqual(resolvedTabStops, paragraph.tabStops),
-  };
-}
-
-function areIndentationsEqual(
-  left:
-    | Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["indentation"]
-    | undefined,
-  right:
-    | Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["indentation"]
-    | undefined,
-): boolean {
-  return (
-    left?.left === right?.left &&
-    left?.right === right?.right &&
-    left?.firstLine === right?.firstLine &&
-    left?.hanging === right?.hanging
-  );
-}
-
-function areTabStopsEqual(
-  left: ReadonlyArray<{ pos: number; val?: string; leader?: string }> | undefined,
-  right: ReadonlyArray<{ pos: number; val?: string; leader?: string }> | undefined,
-): boolean {
-  if (!left?.length && !right?.length) {
-    return true;
-  }
-  if (!left || !right || left.length !== right.length) {
-    return false;
-  }
-  return left.every(
-    (tabStop, index) =>
-      tabStop.pos === right[index]?.pos &&
-      tabStop.val === right[index]?.val &&
-      tabStop.leader === right[index]?.leader,
-  );
-}
-
-function findActiveParagraph(
-  blocks: readonly SurfaceBlockSnapshot[],
-  position: number,
-): Extract<SurfaceBlockSnapshot, { kind: "paragraph" }> | null {
-  for (const block of blocks) {
-    if (block.kind === "paragraph" && position >= block.from && position <= block.to) {
-      return block;
-    }
-    if (block.kind === "table") {
-      for (const row of block.rows) {
-        for (const cell of row.cells) {
-          const paragraph = findActiveParagraph(cell.content, position);
-          if (paragraph) {
-            return paragraph;
-          }
-        }
-      }
-    }
-    if (block.kind === "sdt_block") {
-      const paragraph = findActiveParagraph(block.children, position);
-      if (paragraph) {
-        return paragraph;
-      }
-    }
-  }
-  return null;
-}
-
-interface PageChromeModel {
-  lineNumberingEnabled: boolean;
-  gutterWidthPx: number;
-  lineMarkers: Array<{ id: string; label: string; topPx: number }>;
-  showPageBorder: boolean;
-  pageBorderDisplay: string;
-  pageBorderStyle: CSSProperties | undefined;
-  documentGridType: string;
-  documentGridStyle: CSSProperties | undefined;
-}
-
-const EMPTY_PAGE_CHROME_MODEL: PageChromeModel = {
-  lineNumberingEnabled: false,
-  gutterWidthPx: 0,
-  lineMarkers: [],
-  showPageBorder: false,
-  pageBorderDisplay: "none",
-  pageBorderStyle: undefined,
-  documentGridType: "none",
-  documentGridStyle: undefined,
-};
-
-
-// P2.a — real-dimension page frame.  Page frame width/height are
-// `pageLayout.pageWidth/pageHeight × FRAME_PX_PER_TWIP_AT_96DPI` so
-// every paper size renders at its Word-matching CSS px (Letter
-// 816×1056, A4 794×1123, Legal 816×1344, …).  Constants are exported
-// so tests + harness panels can derive the same values.
-export const FRAME_PX_PER_TWIP_AT_96DPI = 96 / 1440;
-/** Floor on header/footer band heights so empty bands stay clickable. */
-export const MIN_BAND_HEIGHT_PX = 20;
-
-export interface PageShellMetrics {
-  /** P2.a — page frame CSS px width = `pageWidth × FRAME_PX_PER_TWIP_AT_96DPI`. */
-  frameWidthPx?: number;
-  /** P2.a — page frame CSS px height = `pageHeight × FRAME_PX_PER_TWIP_AT_96DPI`. */
-  frameHeightPx?: number;
-  contentInsetStyle: CSSProperties;
-  pageFrameStyle: CSSProperties;
-}
-
-function buildPageChromeModel(
-  surface: RuntimeRenderSnapshot["surface"] | undefined,
-  pageLayout: RuntimeRenderSnapshot["pageLayout"] | undefined,
-  navigation: DocumentNavigationSnapshot | undefined,
-  activeStory: RuntimeRenderSnapshot["activeStory"],
-): PageChromeModel {
-  if (!surface || !pageLayout || !navigation || activeStory.kind !== "main") {
-    return EMPTY_PAGE_CHROME_MODEL;
-  }
-
-  const lineMarkers = computeLineMarkersIfEnabled({
-    pageLayout,
-    surfaceBlocks: surface.blocks,
-    pages: navigation.pages,
-  });
-  const lineNumberingEnabled =
-    Boolean(pageLayout.lineNumbering) && lineMarkers.length > 0;
-  const distance = pageLayout.lineNumbering?.distance ?? 0;
-  const gutterWidthPx = lineNumberingEnabled
-    ? Math.max(40, Math.min(88, 24 + Math.round(distance * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP)))
-    : 0;
-  const showPageBorder = shouldRenderPageBorder(pageLayout, navigation.pages, navigation.activePageIndex);
-
-  return {
-    lineNumberingEnabled,
-    gutterWidthPx,
-    lineMarkers,
-    showPageBorder,
-    pageBorderDisplay: pageLayout.pageBorders?.display ?? "none",
-    pageBorderStyle: showPageBorder ? buildPageBorderStyle(pageLayout) : undefined,
-    documentGridType: pageLayout.documentGrid?.type ?? "none",
-    documentGridStyle: buildDocumentGridStyle(pageLayout.documentGrid),
-  };
-}
-
-export function buildPageShellMetrics(
-  pageLayout: RuntimeRenderSnapshot["pageLayout"] | undefined,
-): PageShellMetrics {
-  if (!pageLayout) {
-    return {
-      contentInsetStyle: {},
-      pageFrameStyle: {},
-      frameWidthPx: 0,
-      frameHeightPx: 0,
-    };
-  }
-
-  // P2.a — frame dimensions follow the section's real twip width/height
-  // so every paper size in the catalog renders at its Word-matching CSS
-  // px (Letter 816×1056, A4 794×1123, Legal 816×1344, …).
-  const pxPerTwip = FRAME_PX_PER_TWIP_AT_96DPI;
-  const frameWidthPx = Math.round(pageLayout.pageWidth * pxPerTwip);
-  const frameHeightPx = Math.round(pageLayout.pageHeight * pxPerTwip);
-  const horizontalInsetPx = Math.round(pageLayout.marginLeft * pxPerTwip);
-  const horizontalInsetRightPx = Math.round(pageLayout.marginRight * pxPerTwip);
-
-  // P8.11 — `headerBandStyle` / `footerBandStyle` removed.  The
-  // workspace-level band divs that consumed them are gone; per-page
-  // bands (rendered by `TwPageStackChromeLayer`) compute their own
-  // heights from the runtime's `PageRegionsSnapshot`.
-
-  return {
-    contentInsetStyle: {
-      paddingLeft: `${horizontalInsetPx}px`,
-      paddingRight: `${horizontalInsetRightPx}px`,
-    },
-    pageFrameStyle: {
-      backgroundColor: "var(--color-page-bg)",
-      borderRadius: "8px",
-      boxShadow: "0 24px 48px -32px rgba(15, 23, 42, 0.38), 0 8px 20px -18px rgba(15, 23, 42, 0.22)",
-      border: "1px solid rgba(148, 163, 184, 0.2)",
-    },
-    frameWidthPx,
-    frameHeightPx,
-  };
-}
-
-// P2.c — fit-to-width / fit-to-page resolves against the active section's
-// real paper size (not a global constant), so Letter and A4 produce the
-// expected 1.029:1 fit-width ratio at the same viewport.  Clamped so
-// extreme viewports don't pin the editor at unreadable zooms.
-const FIT_WIDTH_CHROME_RESERVATION_PX = 96;
-const FIT_HEIGHT_CHROME_RESERVATION_PX = 180;
-const MIN_FIT_ZOOM = 0.5;
-const MAX_FIT_ZOOM = 2.0;
-
-export function resolveZoomMultiplier(
-  zoomLevel: number | "pageWidth" | "onePage",
-  frameWidthPx: number,
-  frameHeightPx: number,
-  viewportWidth: number | undefined,
-  viewportHeight: number | undefined,
-): number {
-  if (typeof zoomLevel === "number") {
-    return zoomLevel / 100;
-  }
-  if (!viewportWidth || frameWidthPx <= 0) return 1;
-  const widthFit =
-    (viewportWidth - FIT_WIDTH_CHROME_RESERVATION_PX) / frameWidthPx;
-  if (zoomLevel === "pageWidth") {
-    return Math.max(MIN_FIT_ZOOM, Math.min(MAX_FIT_ZOOM, widthFit));
-  }
-  if (!viewportHeight || frameHeightPx <= 0) {
-    return Math.max(MIN_FIT_ZOOM, Math.min(MAX_FIT_ZOOM, widthFit));
-  }
-  const heightFit =
-    (viewportHeight - FIT_HEIGHT_CHROME_RESERVATION_PX) / frameHeightPx;
-  return Math.max(
-    MIN_FIT_ZOOM,
-    Math.min(MAX_FIT_ZOOM, Math.min(widthFit, heightFit)),
-  );
-}
-
-function shouldRenderPageBorder(
-  pageLayout: RuntimeRenderSnapshot["pageLayout"],
-  pages: ReadonlyArray<DocumentNavigationSnapshot["pages"][number]>,
-  activePageIndex: number,
-): boolean {
-  const display = pageLayout?.pageBorders?.display ?? "allPages";
-  const activePage = pages[activePageIndex];
-  if (!pageLayout?.pageBorders || !activePage) {
-    return false;
-  }
-
-  switch (display) {
-    case "firstPage":
-      return activePage.pageInSection === 0;
-    case "notFirstPage":
-      return activePage.pageInSection > 0;
-    default:
-      return true;
-  }
-}
-
-function buildPageBorderStyle(
-  pageLayout: NonNullable<RuntimeRenderSnapshot["pageLayout"]>,
-): CSSProperties | undefined {
-  const pageBorders = pageLayout.pageBorders;
-  if (!pageBorders) {
-    return undefined;
-  }
-
-  const leftInset = createInsetValue(
-    pageBorders.left?.space,
-    pageBorders.offsetFrom === "text"
-      ? (pageLayout.marginLeft / Math.max(1, pageLayout.pageWidth)) * 100
-      : 1.25,
-  );
-  const rightInset = createInsetValue(
-    pageBorders.right?.space,
-    pageBorders.offsetFrom === "text"
-      ? (pageLayout.marginRight / Math.max(1, pageLayout.pageWidth)) * 100
-      : 1.25,
-  );
-  const topInset = createInsetValue(
-    pageBorders.top?.space,
-    pageBorders.offsetFrom === "text"
-      ? (pageLayout.marginTop / Math.max(1, pageLayout.pageHeight)) * 100
-      : 1.5,
-  );
-  const bottomInset = createInsetValue(
-    pageBorders.bottom?.space,
-    pageBorders.offsetFrom === "text"
-      ? (pageLayout.marginBottom / Math.max(1, pageLayout.pageHeight)) * 100
-      : 1.5,
-  );
-
-  return {
-    top: topInset,
-    right: rightInset,
-    bottom: bottomInset,
-    left: leftInset,
-    borderTop: toBorderCss(pageBorders.top),
-    borderRight: toBorderCss(pageBorders.right),
-    borderBottom: toBorderCss(pageBorders.bottom),
-    borderLeft: toBorderCss(pageBorders.left),
-    boxSizing: "border-box",
-    mixBlendMode: pageBorders.zOrder === "back" ? "multiply" : undefined,
-  };
-}
-
-function buildDocumentGridStyle(
-  documentGrid: NonNullable<RuntimeRenderSnapshot["pageLayout"]>["documentGrid"] | undefined,
-): CSSProperties | undefined {
-  if (!documentGrid || !documentGrid.type || documentGrid.type === "default") {
-    return undefined;
-  }
-
-  const linePitchPx = Math.max(
-    18,
-    Math.round((documentGrid.linePitch ?? 360) * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP),
-  );
-  const charSpacePx = Math.max(
-    12,
-    Math.round((documentGrid.charSpace ?? 204) * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP),
-  );
-  const gridColor = "rgba(15, 23, 42, 0.06)";
-  const backgrounds: string[] = [];
-
-  if (
-    documentGrid.type === "lines" ||
-    documentGrid.type === "linesAndChars" ||
-    documentGrid.type === "snapToChars"
-  ) {
-    backgrounds.push(
-      `repeating-linear-gradient(to bottom, ${gridColor} 0, ${gridColor} 1px, transparent 1px, transparent ${linePitchPx}px)`,
-    );
-  }
-  if (
-    documentGrid.type === "linesAndChars" ||
-    documentGrid.type === "snapToChars"
-  ) {
-    backgrounds.push(
-      `repeating-linear-gradient(to right, rgba(15, 23, 42, 0.04) 0, rgba(15, 23, 42, 0.04) 1px, transparent 1px, transparent ${charSpacePx}px)`,
-    );
-  }
-
-  if (backgrounds.length === 0) {
-    return undefined;
-  }
-
-  return {
-    backgroundImage: backgrounds.join(", "),
-    backgroundOrigin: "content-box",
-  };
-}
-
-function createInsetValue(spaceTwips: number | undefined, percent: number): string {
-  const spacingPx = Math.max(0, Math.round((spaceTwips ?? 0) * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP));
-  return `calc(${percent.toFixed(2)}% + ${spacingPx}px)`;
-}
-
-function resolveSelectionToolbarPlacement(
-  anchor: SelectionToolAnchor | null | undefined,
-  root: HTMLDivElement | null,
-  zoomScale: number,
-): { placement: "right" | "left" | "above" | "below"; style: CSSProperties } | null {
-  if (!anchor || !root) {
-    return null;
-  }
-
-  const rootRect = root.getBoundingClientRect();
-  if (rootRect.width <= 0 || rootRect.height <= 0 || zoomScale <= 0) {
-    return null;
-  }
-
-  const centerX = (anchor.left + anchor.right) / 2;
-  const centerY = (anchor.top + anchor.bottom) / 2;
-  const localLeftEdge = (anchor.left - rootRect.left) / zoomScale;
-  const localRightEdge = (anchor.right - rootRect.left) / zoomScale;
-  const localLeft = (centerX - rootRect.left) / zoomScale;
-  const localCenterY = (centerY - rootRect.top) / zoomScale;
-  const localTop = (anchor.top - rootRect.top) / zoomScale;
-  const localBottom = (anchor.bottom - rootRect.top) / zoomScale;
-  const edgePadding = 16 / zoomScale;
-  const containerWidth = rootRect.width / zoomScale;
-  const containerHeight = rootRect.height / zoomScale;
-  const gapPx = 12 / zoomScale;
-  const estimatedToolbarWidth = Math.min(260 / zoomScale, Math.max(168 / zoomScale, containerWidth * 0.32));
-  const estimatedToolbarHeight = 44 / zoomScale;
-  const clampedCenterLeft = Math.max(
-    edgePadding,
-    Math.min(localLeft, Math.max(edgePadding, containerWidth - edgePadding)),
-  );
-  const clampedCenterY = Math.max(
-    edgePadding + estimatedToolbarHeight / 2,
-    Math.min(localCenterY, Math.max(edgePadding + estimatedToolbarHeight / 2, containerHeight - edgePadding - estimatedToolbarHeight / 2)),
-  );
-  const rightClearance = containerWidth - localRightEdge - gapPx - edgePadding;
-  const leftClearance = localLeftEdge - gapPx - edgePadding;
-
-  if (rightClearance >= estimatedToolbarWidth) {
-    return {
-      placement: "right",
-      style: {
-        left: `${localRightEdge}px`,
-        top: `${clampedCenterY}px`,
-        maxWidth: `${Math.max(220, containerWidth - edgePadding * 2)}px`,
-        transform: `translate(${gapPx}px, -50%)`,
-      },
-    };
-  }
-
-  if (leftClearance >= estimatedToolbarWidth) {
-    return {
-      placement: "left",
-      style: {
-        left: `${localLeftEdge}px`,
-        top: `${clampedCenterY}px`,
-        maxWidth: `${Math.max(220, containerWidth - edgePadding * 2)}px`,
-        transform: `translate(calc(-100% - ${gapPx}px), -50%)`,
-      },
-    };
-  }
-
-  const placement = localTop < estimatedToolbarHeight + gapPx + edgePadding ? "below" : "above";
-
-  return {
-    placement,
-    style: {
-      left: `${clampedCenterLeft}px`,
-      top: `${placement === "above" ? localTop : localBottom}px`,
-      maxWidth: `${Math.max(220, containerWidth - edgePadding * 2)}px`,
-      transform:
-        placement === "above"
-          ? `translate(-50%, calc(-100% - ${gapPx}px))`
-          : `translate(-50%, ${gapPx}px)`,
-    },
-  };
-}
-
-function toBorderCss(
-  border:
-    | NonNullable<NonNullable<RuntimeRenderSnapshot["pageLayout"]>["pageBorders"]>["top"]
-    | undefined,
-): string | undefined {
-  if (!border || border.value === "none" || border.value === "nil") {
-    return undefined;
-  }
-
-  const width = border.size ? `${Math.max(1, Math.round(border.size / 8))}px` : "1px";
-  const style =
-    border.value === "double"
-      ? "double"
-      : border.value === "dotted"
-        ? "dotted"
-        : border.value === "dashed" || border.value === "dashSmallGap"
-          ? "dashed"
-          : "solid";
-  const color = border.color && border.color !== "auto" ? `#${border.color}` : "rgba(31, 31, 31, 0.28)";
-  return `${width} ${style} ${color}`;
-}