@beyondwork/docx-react-component 1.0.40 → 1.0.42

package/src/ui-tailwind/status/tw-status-bar.tsx

@@ -1,6 +1,9 @@
 import React from "react";
 
-import type { RuntimeContextAnalyticsSnapshot } from "../../api/public-types";
+import type {
+  PublicMeasurementFidelity,
+  RuntimeContextAnalyticsSnapshot,
+} from "../../api/public-types";
 
 export interface TwStatusBarProps {
   isDirty: boolean;
@@ -10,6 +13,26 @@ export interface TwStatusBarProps {
   changeCount: number;
   sessionId: string;
   contextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
+  /**
+   * P5b: **displayed** page number for the selection head.  When the
+   * active section restarts page numbering (roman front matter → arabic
+   * body), this reflects what Word would print on the page — not the
+   * raw 0-based document-order index.  Pass `null` when the facet has
+   * no resolved page (e.g., during initial load).
+   */
+  displayPageNumber?: number | null;
+  /**
+   * P5b: total **content** page count (excludes evenPage / oddPage
+   * blank fillers).  Matches `facet.getPageCount()` — same quantity a
+   * `NUMPAGES` field resolves to on every page.
+   */
+  pageCount?: number | null;
+  /**
+   * P5b: measurement fidelity the layout engine is computing against.
+   * Surfaced as a compact badge so harness operators can see when the
+   * canvas backend is live vs. the empirical fallback.  Absent = skip.
+   */
+  measurementFidelity?: PublicMeasurementFidelity;
 }
 
 export function TwStatusBar(props: TwStatusBarProps) {
@@ -56,10 +79,38 @@ export function TwStatusBar(props: TwStatusBarProps) {
         {props.commentCount} comment{props.commentCount !== 1 ? "s" : ""} ·{" "}
         {props.changeCount} change{props.changeCount !== 1 ? "s" : ""}
       </span>
+      {props.displayPageNumber != null && props.pageCount != null ? (
+        <span data-testid="status-bar-page-count">
+          Page {props.displayPageNumber} of {props.pageCount}
+        </span>
+      ) : null}
       <span className="flex-1" />
+      {props.measurementFidelity ? (
+        <span
+          data-testid="status-bar-measurement-fidelity"
+          data-fidelity={props.measurementFidelity}
+          className="uppercase tracking-[0.12em] text-tertiary/70"
+          title={`Measurement fidelity: ${props.measurementFidelity}`}
+        >
+          {formatFidelityBadge(props.measurementFidelity)}
+        </span>
+      ) : null}
       <span className="truncate text-[10px] uppercase tracking-[0.12em] text-tertiary/80">
         Session active
       </span>
     </footer>
   );
 }
+
+function formatFidelityBadge(fidelity: PublicMeasurementFidelity): string {
+  switch (fidelity) {
+    case "empirical":
+      return "E";
+    case "canvas":
+      return "C";
+    case "canvas-with-font-loading":
+      return "C+F";
+    default:
+      return String(fidelity);
+  }
+}

package/src/ui-tailwind/theme/editor-theme.css

@@ -488,6 +488,31 @@
   outline-offset: -1px;
 }
 
+/*
+ * ─── Agent-pending shimmer (K2 / scope-card-overlay P2) ───
+ *
+ * Painted on every scope tint that overlaps a WorkflowCandidateRange
+ * with `source: "ai"`.  A soft 1.8s pulse signals the agent is
+ * thinking without competing with the active outline.  Reduced-
+ * motion disables the animation and holds a static 60% opacity
+ * border so the posture is still readable.
+ */
+@keyframes wre-agent-pulse {
+  0%, 100% { opacity: 0.4; }
+  50% { opacity: 0.85; }
+}
+
+.wre-scope-rail-tint-agent-pending {
+  outline: 1px solid color-mix(in srgb, var(--color-workflow) 70%, transparent);
+  outline-offset: -1px;
+  animation: wre-agent-pulse 1.8s ease-in-out infinite;
+}
+
+[data-reduced-motion="true"] .wre-scope-rail-tint-agent-pending {
+  animation: none;
+  opacity: 0.6;
+}
+
 /*
  * ─── Scope rail stripe ───
  *

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

@@ -88,6 +88,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;
 
@@ -343,6 +347,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) {
@@ -373,6 +405,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 +454,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 +497,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 +547,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,10 +609,37 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     renderFrameRevision,
   ]);
   const activePage = props.documentNavigation?.pages[props.documentNavigation.activePageIndex] ?? null;
-  const pageShellMetrics = useMemo(
-    () => buildPageShellMetrics(snapshot.pageLayout),
-    [snapshot.pageLayout],
-  );
+  // 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]);
   const headerBandLabel = resolvePageBandLabel("header", snapshot.activeStory);
   const footerBandLabel = resolvePageBandLabel("footer", snapshot.activeStory);
   const hidePageBorderForActiveEditing =
@@ -573,24 +713,44 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
       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;
@@ -923,11 +1083,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">
@@ -1208,10 +1389,27 @@ 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
+                            }
                           />
                         ) : null}
                       </div>
@@ -1257,6 +1455,9 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                     ? props.documentContextAnalytics
                     : null
                 }
+                displayPageNumber={statusBarPageFacts.displayPageNumber}
+                pageCount={statusBarPageFacts.pageCount}
+                measurementFidelity={statusBarPageFacts.measurementFidelity}
               />
             ) : null}
           </div>
@@ -1364,6 +1565,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,7 +1701,20 @@ 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;
@@ -1539,7 +1757,7 @@ function buildPageChromeModel(
   };
 }
 
-function buildPageShellMetrics(
+export function buildPageShellMetrics(
   pageLayout: RuntimeRenderSnapshot["pageLayout"] | undefined,
 ): PageShellMetrics {
   if (!pageLayout) {
@@ -1548,32 +1766,35 @@ function buildPageShellMetrics(
       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)),
-  );
+  // 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);
+  // Header BAND height = margin space NOT consumed by header content.
+  // When marginTop == headerMargin, the band has no headroom — floor to
+  // MIN_BAND_HEIGHT_PX so empty bands stay clickable.
   const headerBandHeightPx = Math.max(
-    40,
-    Math.min(96, Math.round(pageLayout.headerMargin * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP + 16)),
+    MIN_BAND_HEIGHT_PX,
+    Math.round(Math.max(0, pageLayout.marginTop - pageLayout.headerMargin) * pxPerTwip),
   );
   const footerBandHeightPx = Math.max(
-    40,
-    Math.min(96, Math.round(pageLayout.footerMargin * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP + 16)),
+    MIN_BAND_HEIGHT_PX,
+    Math.round(Math.max(0, pageLayout.marginBottom - pageLayout.footerMargin) * pxPerTwip),
   );
 
   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)",
@@ -1587,9 +1808,47 @@ function buildPageShellMetrics(
     footerBandStyle: {
       minHeight: `${footerBandHeightPx}px`,
     },
+    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 resolvePageBandLabel(
   region: "header" | "footer",
   activeStory: RuntimeRenderSnapshot["activeStory"],