@beyondwork/docx-react-component 1.0.41 → 1.0.43

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

@@ -17,6 +17,7 @@ import type {
   ActiveListContext,
   CommentSidebarThreadSnapshot,
   DocumentNavigationSnapshot,
+  EditorStoryTarget,
   EditorViewStateSnapshot,
   FormattingStateSnapshot,
   FormattingAlignment,
@@ -88,6 +89,10 @@ import { TwReviewRail, type ReviewRailTab } from "./review/tw-review-rail";
 import { TwStatusBar } from "./status/tw-status-bar";
 import { type ToolbarInteractionPolicy } from "./toolbar/tw-toolbar";
 import { TwChromeOverlay } from "./chrome-overlay";
+import {
+  cycleScopeIndex,
+  shouldHandleScopeNavKey,
+} from "./chrome-overlay/scope-keyboard-cycle";
 
 export type ReviewWorkspaceChromeVisibility = WordReviewEditorChromeVisibility;
 
@@ -153,6 +158,16 @@ export interface TwReviewWorkspaceProps {
   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;
@@ -274,7 +289,18 @@ export interface TwReviewWorkspaceProps {
   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
@@ -284,6 +310,13 @@ export interface TwReviewWorkspaceProps {
    */
   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;
@@ -343,6 +376,34 @@ export interface TwReviewWorkspaceProps {
     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;
+  }) => 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;
 }
 
 export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
@@ -352,6 +413,17 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   } as TwReviewWorkspaceProps & EditorCommandBag;
   const { snapshot, viewState } = props;
   const selectionToolbarRootRef = useRef<HTMLDivElement>(null);
+  // P8.11 — body slot wrapping `{props.document}` (the PM surface) + scroll
+  // root ref.  The chrome layer's `TwPageStackChromeLayer` needs both to
+  // 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 caps = props.capabilities;
   const isPageWorkspace = props.workspaceMode === "page";
   const markupDisplay = props.markupDisplay;
@@ -373,6 +445,37 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   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) => {
@@ -391,10 +494,32 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     },
     [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) => {
+      onScopeAskAgent?.({ scopeId });
+    },
+    [onScopeAskAgent],
+  );
   const zoomLevel = props.zoomLevel ?? 100;
-  const zoomScale = typeof zoomLevel === "number" ? zoomLevel / 100 : 1;
-  const pageZoomBucket =
-    !isPageWorkspace ? undefined : zoomScale < 1 ? "low" : zoomScale > 1 ? "high" : "base";
+  // Numeric zooms resolve immediately; "pageWidth" / "onePage" need the
+  // page-frame dimensions to fit against — they're resolved below once
+  // `pageShellMetrics` has been computed (P2.c).
+  const numericZoomScale = typeof zoomLevel === "number" ? zoomLevel / 100 : 1;
   const chromePreset = resolveChromePreset(props.chromePreset, props.reviewMode);
   const chromeOptions = resolveChromePresetOptions(chromePreset, props.chromeOptions);
   const preserveOnlyCount = caps?.preserveOnlyCount ??
@@ -412,6 +537,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   });
   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(),
@@ -461,6 +587,33 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     }
     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,
+    );
+  }, [
+    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
@@ -496,12 +649,41 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     renderFrameRevision,
   ]);
   const activePage = props.documentNavigation?.pages[props.documentNavigation.activePageIndex] ?? null;
-  const pageShellMetrics = useMemo(
-    () => buildPageShellMetrics(snapshot.pageLayout),
-    [snapshot.pageLayout],
-  );
-  const headerBandLabel = resolvePageBandLabel("header", snapshot.activeStory);
-  const footerBandLabel = resolvePageBandLabel("footer", snapshot.activeStory);
+  // P5b — status-bar facts derived from the layout facet so the
+  // Page-N-of-M display + measurement-fidelity badge ("E" / "C" / "C+F")
+  // refresh on every layout-affecting facet event.  The subscription
+  // above bumps `renderFrameRevision` on the same kinds; including it
+  // in the dependency list re-runs this memo without a separate
+  // subscription.
+  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]);
+  // P8.11 — `headerBandLabel` / `footerBandLabel` retired along with the
+  // workspace-level bands.  Per-page bands in `TwPageStackChromeLayer`
+  // render the actual header / footer story blocks via
+  // `TwRegionBlockRenderer`, so a label row is no longer meaningful here.
   const hidePageBorderForActiveEditing =
     isPageWorkspace &&
     snapshot.activeStory.kind === "main" &&
@@ -568,29 +750,131 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     }
   }, [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);
+      }
+    });
+    // `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 updateViewportWidth = () => {
+    const updateViewport = () => {
       setViewportWidth(readViewportWidth());
+      setViewportHeight(readViewportHeight());
     };
 
-    updateViewportWidth();
-    window.addEventListener("resize", updateViewportWidth);
+    updateViewport();
+    window.addEventListener("resize", updateViewport);
     return () => {
-      window.removeEventListener("resize", updateViewportWidth);
+      window.removeEventListener("resize", updateViewport);
     };
   }, []);
 
-  // Subscribe to layout facet events so chrome re-projects on zoom changes
-  // and after incremental relayout (R4).
+  // 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;
     const unsub = props.layoutFacet.subscribe((event) => {
-      if (event.kind === "zoom_changed" || event.kind === "render_frame_ready") {
-        setRenderFrameRevision((n) => n + 1);
+      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":
+          setRenderFrameRevision((n) => n + 1);
+          break;
+        default:
+          break;
       }
     });
     return unsub;
@@ -658,6 +942,20 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
           <div className="px-3 pt-3">
             <ChromePresetToolbar
               chromePreset={chromePreset}
+              {...(props.collabSession ? { collabSession: props.collabSession } : {})}
+              {...(props.collabTransportStatus
+                ? { collabTransportStatus: props.collabTransportStatus }
+                : {})}
+              {...(props.activeCommentId !== undefined
+                ? { activeCommentId: props.activeCommentId }
+                : {})}
+              {...(props.collabActorId !== undefined
+                ? { collabActorId: props.collabActorId }
+                : {})}
+              {...(props.collabSendBaseline
+                ? { collabSendBaseline: props.collabSendBaseline }
+                : {})}
+              chromeOptionsResolved={chromeOptions}
               capabilities={caps}
               compatibility={snapshot.compatibility}
               warnings={snapshot.warnings}
@@ -916,6 +1214,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
           {/* Document column */}
           <div className="flex flex-1 flex-col min-w-0">
             <div
+              ref={scrollRootRef}
               className="flex-1 overflow-y-auto bg-surface"
               data-wre-scroll-root="true"
             >
@@ -923,11 +1222,32 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                 ref={selectionToolbarRootRef}
                 className={`mx-auto min-h-full w-full ${
                   isPageWorkspace
-                    ? "wre-page-chrome wre-page-surface relative max-w-[840px] my-8 overflow-hidden"
+                    ? "wre-page-chrome wre-page-surface relative my-8 overflow-hidden"
                     : "wre-canvas-surface relative my-8 overflow-hidden"
                 }`}
                 data-zoom-bucket={pageZoomBucket}
-                style={isPageWorkspace && zoomScale !== 1 ? { transform: `scale(${zoomScale})`, transformOrigin: "top center" } : undefined}
+                data-zoom-scale={isPageWorkspace ? zoomScale : undefined}
+                style={
+                  isPageWorkspace
+                    ? {
+                        // P2.a — real-dim page frame: width/height from
+                        // `pageLayout.pageWidth/pageHeight × FRAME_PX_PER_TWIP_AT_96DPI`
+                        // so every paper size renders at its
+                        // Word-matching CSS px.  `max-w-[840px]` retired.
+                        ...(pageShellMetrics.frameWidthPx
+                          ? { width: `${pageShellMetrics.frameWidthPx}px` }
+                          : {}),
+                        ...(pageShellMetrics.frameHeightPx
+                          ? { minHeight: `${pageShellMetrics.frameHeightPx}px` }
+                          : {}),
+                        // P2.b — browser-native CSS `zoom` rescales layout
+                        // so `getBoundingClientRect()` and hit-test offsets
+                        // stay truthful at any zoom — no inverse-projection
+                        // math needed downstream.
+                        ...(zoomScale !== 1 ? { zoom: zoomScale } : {}),
+                      }
+                    : undefined
+                }
               >
                 {isPageWorkspace && chromeVisibility.pageChrome && snapshot.pageLayout ? (
                   <div className="border-b border-border/70 bg-surface/65 px-5 py-3" data-testid="page-context-summary">
@@ -1164,25 +1484,6 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                           }
                         : pageChromeModel.documentGridStyle}
                     >
-                      {isPageWorkspace && chromeVisibility.pageChrome ? (
-                        <div
-                          data-testid="page-header-band"
-                          className="relative z-10 flex items-center justify-between border-b border-border/50 bg-surface/45 px-4 text-[11px] text-secondary backdrop-blur-[1px]"
-                          style={pageShellMetrics.headerBandStyle}
-                        >
-                          <span className="uppercase tracking-[0.12em] text-tertiary">{headerBandLabel}</span>
-                          {snapshot.pageLayout?.headerVariants[0] ? (
-                            <button
-                              type="button"
-                              aria-label="Open header story"
-                              onClick={props.onOpenHeaderStory}
-                              className="rounded-md px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface"
-                            >
-                              Edit header
-                            </button>
-                          ) : null}
-                        </div>
-                      ) : null}
                       {isPageWorkspace && chromeVisibility.pageChrome && pageChromeModel.showPageBorder && !hidePageBorderForActiveEditing ? (
                         <div
                           aria-hidden="true"
@@ -1192,15 +1493,23 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                         />
                       ) : null}
                       <div className={isPageWorkspace ? "relative z-10" : "relative"}>
-                        {/* Page chrome (frame borders, header/footer bands,
-                            page-number labels, inter-page separators) is
-                            rendered as in-flow widget decorations inside
-                            the PM surface itself — see
-                            `pm-page-break-decorations.ts`.  That keeps the
-                            chrome perfectly aligned with PM content without
-                            any absolute-positioned overlay that would drift
-                            relative to the browser's line layout. */}
-                        {props.document}
+                        {/* P8.11 — workspace-level header / footer bands
+                            retired.  The PM surface now mounts inside
+                            `data-pm-body-slot`; per-page header, footer,
+                            footnote, and endnote chrome is owned by
+                            `TwPageStackChromeLayer` inside `TwChromeOverlay`
+                            (see below).  When the user clicks a per-page
+                            band, the chrome layer reparents PM's DOM node
+                            into the active band's `data-pm-portal-slot`;
+                            when the user returns to the body, PM slides
+                            back into this wrapper. */}
+                        <div
+                          data-pm-body-slot=""
+                          ref={bodySlotRef}
+                          style={{ width: "100%" }}
+                        >
+                          {props.document}
+                        </div>
                         {props.layoutFacet ? (
                           <TwChromeOverlay
                             facet={props.layoutFacet}
@@ -1208,32 +1517,39 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                             onSetColumnWidth={props.onSetColumnWidth}
                             onSetRowHeight={props.onSetRowHeight}
                             activeScopeId={activeScopeId}
+                            editorRole={viewState.editorRole}
+                            scopeCardScopeTagEditor={props.scopeCardScopeTagEditor}
                             onScopeStripeClick={handleScopeStripeClick}
                             onScopeCardClose={handleScopeCardClose}
                             onScopeCardModeChange={handleScopeCardModeChange}
                             onScopeCardIssueAction={handleScopeCardIssueAction}
+                            onScopeCardAcceptSuggestionGroup={
+                              onScopeAcceptSuggestionGroup
+                                ? handleScopeCardAcceptSuggestionGroup
+                                : undefined
+                            }
+                            onScopeCardRejectSuggestionGroup={
+                              onScopeRejectSuggestionGroup
+                                ? handleScopeCardRejectSuggestionGroup
+                                : undefined
+                            }
+                            onScopeCardAskAgent={
+                              onScopeAskAgent
+                                ? handleScopeCardAskAgent
+                                : undefined
+                            }
+                            pageStackScrollRoot={
+                              isPageWorkspace && chromeVisibility.pageChrome
+                                ? pageStackScrollRoot
+                                : undefined
+                            }
+                            renderFrameRevision={renderFrameRevision}
+                            activeStory={snapshot.activeStory}
+                            onOpenStory={props.onOpenStory}
+                            pmSurfaceElement={pmSurfaceElement}
                           />
                         ) : null}
                       </div>
-                      {isPageWorkspace && chromeVisibility.pageChrome ? (
-                        <div
-                          data-testid="page-footer-band"
-                          className="relative z-10 flex items-center justify-between border-t border-border/50 bg-surface/45 px-4 text-[11px] text-secondary backdrop-blur-[1px]"
-                          style={pageShellMetrics.footerBandStyle}
-                        >
-                          <span className="uppercase tracking-[0.12em] text-tertiary">{footerBandLabel}</span>
-                          {snapshot.pageLayout?.footerVariants[0] ? (
-                            <button
-                              type="button"
-                              aria-label="Open footer story"
-                              onClick={props.onOpenFooterStory}
-                              className="rounded-md px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-surface"
-                            >
-                              Edit footer
-                            </button>
-                          ) : null}
-                        </div>
-                      ) : null}
                     </div>
                   </div>
                 </div>
@@ -1257,6 +1573,9 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                     ? props.documentContextAnalytics
                     : null
                 }
+                displayPageNumber={statusBarPageFacts.displayPageNumber}
+                pageCount={statusBarPageFacts.pageCount}
+                measurementFidelity={statusBarPageFacts.measurementFidelity}
               />
             ) : null}
           </div>
@@ -1364,6 +1683,10 @@ 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 {
@@ -1496,11 +1819,22 @@ const EMPTY_PAGE_CHROME_MODEL: PageChromeModel = {
 
 const DOCUMENT_CONTENT_TOP_PADDING_PX = 40;
 
-interface PageShellMetrics {
+// 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;
-  headerBandStyle: CSSProperties;
-  footerBandStyle: CSSProperties;
 }
 
 function buildPageChromeModel(
@@ -1539,41 +1873,36 @@ function buildPageChromeModel(
   };
 }
 
-function buildPageShellMetrics(
+export function buildPageShellMetrics(
   pageLayout: RuntimeRenderSnapshot["pageLayout"] | undefined,
 ): PageShellMetrics {
   if (!pageLayout) {
     return {
       contentInsetStyle: {},
       pageFrameStyle: {},
-      headerBandStyle: {},
-      footerBandStyle: {},
+      frameWidthPx: 0,
+      frameHeightPx: 0,
     };
   }
 
-  const horizontalInsetPx = Math.max(
-    24,
-    Math.min(120, Math.round(pageLayout.marginLeft * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP)),
-  );
-  const verticalInsetPx = Math.max(
-    24,
-    Math.min(140, Math.round(pageLayout.marginTop * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP)),
-  );
-  const headerBandHeightPx = Math.max(
-    40,
-    Math.min(96, Math.round(pageLayout.headerMargin * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP + 16)),
-  );
-  const footerBandHeightPx = Math.max(
-    40,
-    Math.min(96, Math.round(pageLayout.footerMargin * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP + 16)),
-  );
+  // 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: `${horizontalInsetPx}px`,
-      paddingTop: `${Math.max(20, verticalInsetPx - 12)}px`,
-      paddingBottom: `${Math.max(20, Math.round(pageLayout.marginBottom * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP) - 12)}px`,
+      paddingRight: `${horizontalInsetRightPx}px`,
     },
     pageFrameStyle: {
       backgroundColor: "var(--color-page-bg)",
@@ -1581,37 +1910,45 @@ function buildPageShellMetrics(
       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)",
     },
-    headerBandStyle: {
-      minHeight: `${headerBandHeightPx}px`,
-    },
-    footerBandStyle: {
-      minHeight: `${footerBandHeightPx}px`,
-    },
+    frameWidthPx,
+    frameHeightPx,
   };
 }
 
-function resolvePageBandLabel(
-  region: "header" | "footer",
-  activeStory: RuntimeRenderSnapshot["activeStory"],
-): string {
-  const regionLabel = region === "header" ? "header" : "footer";
-  let label: string;
-  if (activeStory.kind !== region) {
-    label = region === "header" ? "Header" : "Footer";
-  } else {
-    switch (activeStory.variant) {
-      case "first":
-        label = `First page ${regionLabel}`;
-        break;
-      case "even":
-        label = `Even page ${regionLabel}`;
-        break;
-      default:
-        label = `Default ${regionLabel}`;
-        break;
-    }
+// 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;
   }
-  return label;
+  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 buildLineNumberMarkers(