@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/ui-tailwind/page-stack/floating-image-overlay-model.ts

@@ -6,12 +6,23 @@ import type {
   SurfaceDrawingAnchor,
   SurfaceInlineSegment,
 } from "../../api/public-types.ts";
-import type { WordReviewEditorLayoutFacet } from "../../runtime/layout/index.ts";
+import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
 import { storyTargetKey } from "../../runtime/story-targeting.ts";
-import { EMU_PER_PX } from "../../runtime/units.ts";
+import { EMU_PER_PX, TWIPS_PER_PX } from "../../api/public-types.ts";
 import type { PageOverlayRect } from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
 
-const FRAME_PX_PER_TWIP_AT_96DPI = 96 / 1440;
+/**
+ * Default twip → pixel conversion at 96 dpi / 100% zoom.
+ * `pxPerTwip = 96 / 1440 = 1 / TWIPS_PER_PX`.
+ *
+ * Callers that render the page stack at a non-baseline zoom (e.g.
+ * 75% / 125% / 150%) must pass `pxPerTwip` derived from
+ * `geometryFacet.getRenderZoom()?.pxPerTwip` so floating-image rects
+ * track the rendered page frame. Otherwise the overlay math drifts
+ * — a 150%-zoomed page is 1.5× bigger, but floats computed with the
+ * 96 dpi baseline land at 66% of the target position.
+ */
+const BASELINE_PX_PER_TWIP = 1 / TWIPS_PER_PX;
 
 export interface FloatingImagePreviewDescriptor {
   src: string;
@@ -66,12 +77,22 @@ export function collectFloatingImageOverlayItems(input: {
   facet: WordReviewEditorLayoutFacet;
   pageRects: readonly PageOverlayRect[];
   mediaPreviews?: Record<string, FloatingImagePreviewDescriptor>;
+  /**
+   * Live `pxPerTwip` from the geometry facet
+   * (`geometryFacet.getRenderZoom()?.pxPerTwip`). When absent, defaults
+   * to the 96 dpi baseline (100% zoom). Supply this whenever the page
+   * stack is rendered at a non-baseline zoom — otherwise floating-image
+   * rects drift off the rendered page frame.
+   */
+  pxPerTwip?: number;
 }): FloatingImageOverlayItem[] {
   const { surface, activeStory, facet } = input;
   if (!surface) {
     return [];
   }
 
+  const pxPerTwip = input.pxPerTwip ?? BASELINE_PX_PER_TWIP;
+
   const rectByPageIndex = new Map<number, PageOverlayRect>(
     input.pageRects.map((rect) => [rect.pageIndex, rect]),
   );
@@ -88,7 +109,7 @@ export function collectFloatingImageOverlayItems(input: {
       if (!pageRect) {
         continue;
       }
-      const localRect = resolveFloatingImageLocalRect(page, activeStory, segment);
+      const localRect = resolveFloatingImageLocalRect(page, activeStory, segment, pxPerTwip);
       if (!localRect) {
         continue;
       }
@@ -164,6 +185,7 @@ function resolveFloatingImageLocalRect(
   page: PublicPageNode,
   activeStory: EditorStoryTarget,
   segment: Extract<SurfaceInlineSegment, { kind: "image" }>,
+  pxPerTwip: number,
 ): {
   topPx: number;
   leftPx: number;
@@ -175,18 +197,18 @@ function resolveFloatingImageLocalRect(
     return null;
   }
 
-  const widthPx = Math.max(24, Math.round(anchor.extent.widthEmu / EMU_PER_PX));
-  const heightPx = Math.max(24, Math.round(anchor.extent.heightEmu / EMU_PER_PX));
-  const horizontalSpace = resolveHorizontalSpace(page, activeStory, anchor);
-  const verticalSpace = resolveVerticalSpace(page, activeStory, anchor);
+  const widthPx = Math.max(24, Math.round(emuToPx(anchor.extent.widthEmu, pxPerTwip)));
+  const heightPx = Math.max(24, Math.round(emuToPx(anchor.extent.heightEmu, pxPerTwip)));
+  const horizontalSpace = resolveHorizontalSpace(page, activeStory, anchor, pxPerTwip);
+  const verticalSpace = resolveVerticalSpace(page, activeStory, anchor, pxPerTwip);
 
   if (!horizontalSpace || !verticalSpace) {
     return null;
   }
 
   return {
-    topPx: resolveAxisPosition(verticalSpace, heightPx, anchor.positionV, page, "vertical"),
-    leftPx: resolveAxisPosition(horizontalSpace, widthPx, anchor.positionH, page, "horizontal"),
+    topPx: resolveAxisPosition(verticalSpace, heightPx, anchor.positionV, page, "vertical", pxPerTwip),
+    leftPx: resolveAxisPosition(horizontalSpace, widthPx, anchor.positionH, page, "horizontal", pxPerTwip),
     widthPx,
     heightPx,
   };
@@ -196,9 +218,10 @@ function resolveHorizontalSpace(
   page: PublicPageNode,
   activeStory: EditorStoryTarget,
   anchor: SurfaceDrawingAnchor,
+  pxPerTwip: number,
 ): { startPx: number; sizePx: number } | null {
-  const pageWidthPx = twipsToPx(page.layout.pageWidth);
-  const storyHost = resolveStoryHostSpace(page, activeStory);
+  const pageWidthPx = twipsToPx(page.layout.pageWidth, pxPerTwip);
+  const storyHost = resolveStoryHostSpace(page, activeStory, pxPerTwip);
   switch (anchor.positionH?.relativeFrom) {
     case "page":
       return { startPx: 0, sizePx: pageWidthPx };
@@ -213,9 +236,10 @@ function resolveVerticalSpace(
   page: PublicPageNode,
   activeStory: EditorStoryTarget,
   anchor: SurfaceDrawingAnchor,
+  pxPerTwip: number,
 ): { startPx: number; sizePx: number } | null {
-  const pageHeightPx = twipsToPx(page.layout.pageHeight);
-  const storyHost = resolveStoryHostSpace(page, activeStory);
+  const pageHeightPx = twipsToPx(page.layout.pageHeight, pxPerTwip);
+  const storyHost = resolveStoryHostSpace(page, activeStory, pxPerTwip);
   switch (anchor.positionV?.relativeFrom) {
     case "page":
       return { startPx: 0, sizePx: pageHeightPx };
@@ -229,31 +253,32 @@ function resolveVerticalSpace(
 function resolveStoryHostSpace(
   page: PublicPageNode,
   activeStory: EditorStoryTarget,
+  pxPerTwip: number,
 ): { topPx: number; leftPx: number; widthPx: number; heightPx: number } | null {
   switch (activeStory.kind) {
     case "main":
       return {
-        topPx: twipsToPx(page.regions.body.originTwips),
-        leftPx: twipsToPx(page.layout.marginLeft),
-        widthPx: twipsToPx(page.regions.body.widthTwips),
-        heightPx: twipsToPx(page.regions.body.heightTwips),
+        topPx: twipsToPx(page.regions.body.originTwips, pxPerTwip),
+        leftPx: twipsToPx(page.layout.marginLeft, pxPerTwip),
+        widthPx: twipsToPx(page.regions.body.widthTwips, pxPerTwip),
+        heightPx: twipsToPx(page.regions.body.heightTwips, pxPerTwip),
       };
     case "header":
       return page.regions.header
         ? {
-            topPx: twipsToPx(page.regions.header.originTwips),
-            leftPx: twipsToPx(page.layout.marginLeft),
-            widthPx: twipsToPx(page.regions.header.widthTwips),
-            heightPx: twipsToPx(page.regions.header.heightTwips),
+            topPx: twipsToPx(page.regions.header.originTwips, pxPerTwip),
+            leftPx: twipsToPx(page.layout.marginLeft, pxPerTwip),
+            widthPx: twipsToPx(page.regions.header.widthTwips, pxPerTwip),
+            heightPx: twipsToPx(page.regions.header.heightTwips, pxPerTwip),
           }
         : null;
     case "footer":
       return page.regions.footer
         ? {
-            topPx: twipsToPx(page.regions.footer.originTwips),
-            leftPx: twipsToPx(page.layout.marginLeft),
-            widthPx: twipsToPx(page.regions.footer.widthTwips),
-            heightPx: twipsToPx(page.regions.footer.heightTwips),
+            topPx: twipsToPx(page.regions.footer.originTwips, pxPerTwip),
+            leftPx: twipsToPx(page.layout.marginLeft, pxPerTwip),
+            widthPx: twipsToPx(page.regions.footer.widthTwips, pxPerTwip),
+            heightPx: twipsToPx(page.regions.footer.heightTwips, pxPerTwip),
           }
         : null;
     default:
@@ -269,6 +294,7 @@ function resolveAxisPosition(
     | undefined,
   page: PublicPageNode,
   orientation: "horizontal" | "vertical",
+  pxPerTwip: number,
 ): number {
   if (!axis) {
     return space.startPx;
@@ -277,7 +303,7 @@ function resolveAxisPosition(
     return alignAxisPosition(space, objectSizePx, axis.align, page, orientation);
   }
   if (axis.offset !== undefined) {
-    return space.startPx + Math.round(axis.offset / EMU_PER_PX);
+    return space.startPx + Math.round(emuToPx(axis.offset, pxPerTwip));
   }
   return space.startPx;
 }
@@ -314,6 +340,17 @@ function alignAxisPosition(
   }
 }
 
-function twipsToPx(value: number): number {
-  return value * FRAME_PX_PER_TWIP_AT_96DPI;
+function twipsToPx(value: number, pxPerTwip: number): number {
+  return value * pxPerTwip;
+}
+
+/**
+ * Convert EMU → zoom-aware CSS pixels. The baseline is 96 dpi
+ * (`EMU_PER_PX = 9525`); at zoom `z`, a 1-inch object renders as
+ * `z * 96 px`. We scale by `pxPerTwip / BASELINE_PX_PER_TWIP`,
+ * which equals the zoom factor.
+ */
+function emuToPx(emu: number, pxPerTwip: number): number {
+  const zoomFactor = pxPerTwip / BASELINE_PX_PER_TWIP;
+  return (emu / EMU_PER_PX) * zoomFactor;
 }

package/src/ui-tailwind/page-stack/tw-floating-image-layer.tsx

@@ -4,7 +4,10 @@ import type {
   EditorStoryTarget,
   RuntimeRenderSnapshot,
 } from "../../api/public-types.ts";
-import type { WordReviewEditorLayoutFacet } from "../../runtime/layout/index.ts";
+import type {
+  GeometryFacet,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types";
 import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection.ts";
 import {
   measureWidgetsViaBoundingRect,
@@ -19,6 +22,14 @@ import {
 
 export interface TwFloatingImageLayerProps {
   facet: WordReviewEditorLayoutFacet;
+  /**
+   * Geometry facet supplies live `pxPerTwip` so floating-image rects
+   * track the rendered page frame at non-baseline zoom (75% / 125% /
+   * 150% / …). When absent, the overlay falls back to the 96 dpi
+   * baseline (100% zoom) — safe for tests and for consumers that
+   * haven't migrated yet, but visibly drifts in the zoomed UI.
+   */
+  geometryFacet?: GeometryFacet;
   scrollRoot: HTMLElement | null;
   renderFrameRevision: number;
   visiblePageIndexRange?: VisiblePageIndexRange | null;
@@ -35,6 +46,7 @@ export interface TwFloatingImageLayerProps {
 
 export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
   facet,
+  geometryFacet,
   scrollRoot,
   renderFrameRevision,
   visiblePageIndexRange,
@@ -154,17 +166,28 @@ export const TwFloatingImageLayer: React.FC<TwFloatingImageLayerProps> = ({
   }, [refreshPageRects, scrollRoot]);
 
   const items = React.useMemo(() => {
+    const pxPerTwip = geometryFacet?.getRenderZoom()?.pxPerTwip;
     const allItems = collectFloatingImageOverlayItems({
       surface: snapshot.surface,
       activeStory: snapshot.activeStory,
       facet,
       pageRects,
       mediaPreviews,
+      pxPerTwip,
     });
     return allItems.filter((item) =>
       plane === "behind" ? item.behindDoc : !item.behindDoc,
     );
-  }, [facet, mediaPreviews, pageRects, plane, snapshot.activeStory, snapshot.surface]);
+  }, [
+    facet,
+    geometryFacet,
+    mediaPreviews,
+    pageRects,
+    plane,
+    renderFrameRevision,
+    snapshot.activeStory,
+    snapshot.surface,
+  ]);
 
   return (
     <div

package/src/ui-tailwind/review/comment-markdown-renderer.tsx

@@ -131,6 +131,18 @@ function renderAttachmentImage(
   return <span key={key}>{alt || attachment?.displayName || ""}</span>;
 }
 
+// SEC-UI-02 (2026-04-23): scheme allowlist on comment-renderer hrefs.
+// Defense-in-depth against the sanitizer. Any `target` that does not match
+// one of the safe schemes renders as a plain <span>, never as a clickable
+// <a href>. Prevents `javascript:alert(1)`, `data:text/html,<script>...`,
+// and similar vectors from leaking through the renderer even if the
+// sanitizer regresses.
+const SAFE_LINK_SCHEME_RE = /^(?:https?|mailto):/i;
+
+function isSafeHref(target: string): boolean {
+  return SAFE_LINK_SCHEME_RE.test(target);
+}
+
 function renderLinkOrMention(
   key: number,
   label: string,
@@ -147,6 +159,9 @@ function renderLinkOrMention(
       </span>
     );
   }
+  if (!isSafeHref(target)) {
+    return <span key={key}>{label}</span>;
+  }
   return (
     <a key={key} href={target} target="_blank" rel="noopener noreferrer">
       {label}

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

@@ -11,20 +11,25 @@ import type {
   RuntimeContextAnalyticsSnapshot,
   TrackedChangesSnapshot,
   TrackedChangeEntrySnapshot,
+  WorkflowBlockedCommandReason,
 } from "../../api/public-types";
-import type { ScopeRailSegment } from "../../runtime/layout";
+import type { ScopeRailSegment } from "../../api/public-types";
 import type { MarkupDisplay } from "../../ui/headless/comment-decoration-model";
 import { TwCommentSidebar } from "./tw-comment-sidebar";
 import { TwRevisionSidebar } from "./tw-revision-sidebar";
 import { TwWorkflowTab } from "./tw-workflow-tab";
+import { TwHealthPanel } from "./tw-health-panel";
 import {
   TwReviewRailFooter,
   type TwReviewRailFooterProps,
 } from "./tw-review-rail-footer";
 
 /**
- * Review rail with three tabs (Comments / Changes / Workflow) that matches
- * the editorial reference mock while preserving the shipped R3a surface.
+ * Review rail with up to four tabs (Workflow / Comments / Changes / Health).
+ * Health is opt-in via `showHealthTab` — Phase E of the chrome-composition
+ * refactor routes diagnostics detail into the rail so the toolbar can shrink
+ * to a signal-only chip.  When `showHealthTab` is absent the rail retains the
+ * shipped three-tab layout for back-compat.
  *
  * The Workflow tab reads `scopeRailSegments` from the runtime facet — that
  * stays the default path.  For hosts that need to override the Workflow card
@@ -40,7 +45,7 @@ import {
  *   - `railFooter?: TwReviewRailFooterProps` mounts the SEARCH / HELP footer.
  */
 
-export type ReviewRailTab = "comments" | "changes" | "workflow";
+export type ReviewRailTab = "comments" | "changes" | "workflow" | "health";
 
 export interface TwReviewRailProps {
   activeTab: ReviewRailTab;
@@ -81,6 +86,23 @@ export interface TwReviewRailProps {
   intelligenceHeader?: boolean;
   /** Utility footer with SEARCH / HELP links.  Hides when unset. */
   railFooter?: TwReviewRailFooterProps;
+  /**
+   * Phase E — mount the fourth "Health" tab with the diagnostics panel
+   * inside.  Hosts typically derive this from
+   * `composition.rail.visibleTabs.has("health")`.  Omit (default `false`)
+   * to preserve the shipped three-tab layout.
+   */
+  showHealthTab?: boolean;
+  /** Count rendered as the Health tab's badge when > 0. */
+  healthIssueCount?: number;
+  /**
+   * Severity tier of the diagnostics signal — drives the Health tab
+   * badge tone via `designsystem.md §3.8` tokens (info / warning /
+   * error / success).  Defaults to `"warning"` when omitted.
+   */
+  healthSeverity?: "info" | "warning" | "blocked";
+  /** Forwarded to the Health tab's `TwHealthPanel` to surface blocked reasons. */
+  workflowBlockedReasons?: WorkflowBlockedCommandReason[];
 
   onActiveTabChange: (tab: ReviewRailTab) => void;
   onOpenComment?: (thread: CommentSidebarThreadSnapshot) => void;
@@ -177,6 +199,7 @@ export function TwReviewRail(props: TwReviewRailProps) {
         >
           <Tabs.Trigger
             value="workflow"
+            data-rail-tab="workflow"
             className={editorial ? UNDERLINE_TRIGGER_CLASS : PILL_TRIGGER_CLASS}
           >
             {editorial ? "Workflow" : "Workflow "}
@@ -188,6 +211,7 @@ export function TwReviewRail(props: TwReviewRailProps) {
           </Tabs.Trigger>
           <Tabs.Trigger
             value="comments"
+            data-rail-tab="comments"
             className={editorial ? UNDERLINE_TRIGGER_CLASS : PILL_TRIGGER_CLASS}
           >
             {editorial ? "Comments" : "Comments "}
@@ -199,6 +223,7 @@ export function TwReviewRail(props: TwReviewRailProps) {
           </Tabs.Trigger>
           <Tabs.Trigger
             value="changes"
+            data-rail-tab="changes"
             className={editorial ? UNDERLINE_TRIGGER_CLASS : PILL_TRIGGER_CLASS}
           >
             {editorial ? "Changes" : "Changes "}
@@ -208,6 +233,25 @@ export function TwReviewRail(props: TwReviewRailProps) {
               </span>
             ) : null}
           </Tabs.Trigger>
+          {props.showHealthTab ? (
+            <Tabs.Trigger
+              value="health"
+              data-rail-tab="health"
+              className={editorial ? UNDERLINE_TRIGGER_CLASS : PILL_TRIGGER_CLASS}
+            >
+              {editorial ? "Health" : "Health "}
+              {props.healthIssueCount !== undefined &&
+              props.healthIssueCount > 0 ? (
+                <span
+                  className="ml-1 inline-flex min-w-[14px] items-center justify-center rounded-full px-1.5 py-px text-[10px] font-medium"
+                  data-severity={props.healthSeverity ?? "warning"}
+                  style={resolveHealthBadgeStyle(props.healthSeverity)}
+                >
+                  {props.healthIssueCount}
+                </span>
+              ) : null}
+            </Tabs.Trigger>
+          ) : null}
         </Tabs.List>
 
         <ScrollArea.Root className="flex-1 min-h-0">
@@ -247,6 +291,18 @@ export function TwReviewRail(props: TwReviewRailProps) {
                 onRejectAllChanges={props.onRejectAllChanges}
               />
             </Tabs.Content>
+
+            {props.showHealthTab ? (
+              <Tabs.Content value="health" className="p-3 outline-none">
+                <TwHealthPanel
+                  compatibility={props.compatibility}
+                  warnings={props.warnings}
+                  {...(props.workflowBlockedReasons
+                    ? { blockedReasons: props.workflowBlockedReasons }
+                    : {})}
+                />
+              </Tabs.Content>
+            ) : null}
           </ScrollArea.Viewport>
           <ScrollArea.Scrollbar
             orientation="vertical"
@@ -262,6 +318,35 @@ export function TwReviewRail(props: TwReviewRailProps) {
   );
 }
 
+/**
+ * Health tab badge tones per `designsystem.md §3.8` severity ladder.
+ *   - `info`    → semantic.info soft/solid
+ *   - `warning` → semantic.warning soft/solid (default)
+ *   - `blocked` → semantic.error soft/solid
+ */
+function resolveHealthBadgeStyle(
+  severity: "info" | "warning" | "blocked" | undefined,
+): React.CSSProperties {
+  switch (severity) {
+    case "info":
+      return {
+        backgroundColor: "var(--color-semantic-info-soft)",
+        color: "var(--color-semantic-info)",
+      };
+    case "blocked":
+      return {
+        backgroundColor: "var(--color-semantic-error-soft)",
+        color: "var(--color-semantic-error)",
+      };
+    case "warning":
+    default:
+      return {
+        backgroundColor: "var(--color-semantic-warning-soft)",
+        color: "var(--color-semantic-warning)",
+      };
+  }
+}
+
 function resolveHeaderTitle(props: TwReviewRailProps): string {
   if (props.workflowScopesTitle) {
     return props.workflowScopesTitle;
@@ -275,5 +360,8 @@ function resolveHeaderTitle(props: TwReviewRailProps): string {
   if (props.activeTab === "changes") {
     return "Tracked Changes";
   }
+  if (props.activeTab === "health") {
+    return "Document Health";
+  }
   return "Review";
 }

package/src/ui-tailwind/review/tw-workflow-tab.tsx

@@ -9,7 +9,7 @@
  */
 
 import React from "react";
-import type { ScopeRailSegment, ScopeRailPosture } from "../../runtime/layout";
+import type { ScopeRailSegment, ScopeRailPosture } from "../../api/public-types";
 
 export interface TwWorkflowTabProps {
   segments: readonly ScopeRailSegment[];

package/src/ui-tailwind/review-workspace/page-chrome.ts

@@ -0,0 +1,210 @@
+import type { CSSProperties } from "react";
+
+import type {
+  DocumentNavigationSnapshot,
+  RuntimeRenderSnapshot,
+} from "../../api/public-types";
+import { DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP } from "../../runtime/page-layout-estimation.ts";
+import { computeLineMarkersIfEnabled } from "../page-chrome-model.ts";
+
+export 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;
+}
+
+export const EMPTY_PAGE_CHROME_MODEL: PageChromeModel = {
+  lineNumberingEnabled: false,
+  gutterWidthPx: 0,
+  lineMarkers: [],
+  showPageBorder: false,
+  pageBorderDisplay: "none",
+  pageBorderStyle: undefined,
+  documentGridType: "none",
+  documentGridStyle: undefined,
+};
+
+export 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),
+  };
+}
+
+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 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}`;
+}