@beyondwork/docx-react-component 1.0.52 → 1.0.53

package/src/runtime/table-style-resolver.ts

@@ -27,10 +27,31 @@ export interface ResolvedTableRowStyle {
   activeConditionalRegions: TableStyleConditionalRegion[];
 }
 
+/**
+ * R3.a Phase 2 — typed bundle of table-level resolved properties projected onto
+ * the surface snapshot so the PM schema + node-view can render them inline at
+ * commit time.
+ *
+ * Borders are kept as the typed `TableBorders` shape here (BorderSpec per side);
+ * the surface-projection step converts them to per-side CSS shorthand strings
+ * (e.g. "1px solid #000") to mirror the existing `resolveCellBorderStyles`
+ * pattern at `surface-projection.ts:506`.
+ */
+export interface ResolvedTableLevelProperties {
+  width?: number;
+  widthType?: TableWidth["type"];
+  layoutMode?: "fixed" | "autofit";
+  cellSpacing?: number;
+  cellSpacingType?: TableWidth["type"];
+  borders?: TableBorders;
+}
+
 export interface ResolvedTableStyleResolution {
   rawTblLook?: TableLook;
   effectiveTblLook: TableLook;
   table?: TableStyleFormatting["table"];
+  /** R3.a Phase 2 — table-level resolved properties (width / layout / spacing / borders). */
+  tableResolved: ResolvedTableLevelProperties;
   rows: Array<{
     style: ResolvedTableRowStyle;
     cells: ResolvedTableCellStyle[];
@@ -140,10 +161,40 @@ export function resolveTableStyleResolution(
     },
   );
 
+  // R3.a Phase 2 — collect the table-level resolved property bundle. Direct
+  // TableNode properties win over the resolved table-style formatting; both
+  // paths still populate the optional fields independently so a partial style
+  // (e.g. style provides borders, direct provides width) merges cleanly.
+  const resolvedTableLevel: ResolvedTableLevelProperties = {};
+  const styleTable = resolvedStyle.formatting?.table;
+  const directWidth = table.width;
+  const styleWidth = styleTable?.width;
+  if (directWidth) {
+    resolvedTableLevel.width = directWidth.value;
+    resolvedTableLevel.widthType = directWidth.type;
+  } else if (styleWidth) {
+    resolvedTableLevel.width = styleWidth.value;
+    resolvedTableLevel.widthType = styleWidth.type;
+  }
+  if (table.layoutMode) {
+    resolvedTableLevel.layoutMode = table.layoutMode;
+  }
+  if (table.cellSpacing) {
+    resolvedTableLevel.cellSpacing = table.cellSpacing.value;
+    resolvedTableLevel.cellSpacingType = table.cellSpacing.type;
+  }
+  // Borders: prefer direct TableNode.borders, fall back to merged style borders.
+  // Both shapes are TableBorders so we can hand the side-bag straight back.
+  const mergedBorders = mergeBorderMap<TableBorders>(styleTable?.borders, table.borders);
+  if (mergedBorders) {
+    resolvedTableLevel.borders = mergedBorders;
+  }
+
   return {
     ...(table.tblLook ? { rawTblLook: table.tblLook } : {}),
     effectiveTblLook,
     ...(tableFormatting ? { table: tableFormatting } : {}),
+    tableResolved: resolvedTableLevel,
     rows,
   };
 }

package/src/ui/editor-runtime-boundary.ts

@@ -8,6 +8,7 @@ import type {
   EditorError,
   EditorHostAdapter,
   EditorSessionState,
+  EditorSurfaceSnapshot,
   EditorViewStateSnapshot,
   EditorWarning,
   ExportDocxOptions,
@@ -134,6 +135,8 @@ export interface EditorRuntimeBoundaryState {
   runtime: WordReviewEditorRuntime | null;
   loadError: EditorError | null;
   activeRuntime: WordReviewEditorRuntime;
+  /** C2c: partial surface snapshot from body-normalize stage; null once full runtime is ready. */
+  progressiveSurface: EditorSurfaceSnapshot | null;
   commandAppliedBridge: RuntimeCommandAppliedBridge;
   fallbackSnapshot: RuntimeRenderSnapshot;
   loadingSessionState: EditorSessionState;
@@ -302,6 +305,12 @@ export function useEditorRuntimeBoundary(
 
   const [runtime, setRuntime] = useState<WordReviewEditorRuntime | null>(null);
   const [loadError, setLoadError] = useState<EditorError | null>(null);
+  // C2c: progressive initial mount — transient surface snapshot from the
+  // body-normalize stage. Cleared when the full runtime commits (setRuntime).
+  const [progressiveSurface, setProgressiveSurface] =
+    useState<EditorSurfaceSnapshot | null>(null);
+  const progressiveSurfaceRef = useRef<EditorSurfaceSnapshot | null>(null);
+  progressiveSurfaceRef.current = progressiveSurface;
   const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
   const pendingReadySourceRef = useRef<"docx" | "session" | "snapshot" | null>(null);
   const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -445,7 +454,20 @@ export function useEditorRuntimeBoundary(
             bytes: source.initialDocx,
             editorBuild: "dev",
             scheduler,
-            ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {}),
+            ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {
+              // C2c: on the cold path (no cached envelope), emit the first
+              // viewport surface as soon as body-normalize completes so the
+              // UI can show the first page before the full session is ready.
+              // Wrapped in startTransition so React treats this as a
+              // low-priority update — the full setRuntime commit (urgent)
+              // will preempt it if it arrives before React flushes the
+              // transition.
+              onProgressiveSnapshot: (partial) => {
+                React.startTransition(() => {
+                  setProgressiveSurface(partial.surface);
+                });
+              },
+            }),
           });
           if (cancelled) {
             scheduler.dispose();
@@ -478,6 +500,10 @@ export function useEditorRuntimeBoundary(
         recordPerfSample("runtime.create");
         runtimeRef.current = nextRuntime;
         pendingReadySourceRef.current = source.source;
+        // C2c: clear the transient progressive surface — the full runtime
+        // snapshot supersedes it. No need for startTransition here since
+        // this is the higher-priority commit that preempts the transition.
+        setProgressiveSurface(null);
         setRuntime(nextRuntime);
       } catch (error) {
         if (cancelled) {
@@ -627,6 +653,9 @@ export function useEditorRuntimeBoundary(
         sessionState: loadingSessionState,
         viewState: loadingViewState,
         navigation: loadingNavigation,
+        // C2c: ref so the bridge can serve the progressive surface in
+        // getRenderSnapshot().surface without recreating on each update.
+        progressiveSurfaceRef,
       }),
     [fallbackSnapshot, loadingNavigation, loadingSessionState, loadingViewState],
   );
@@ -635,6 +664,7 @@ export function useEditorRuntimeBoundary(
     runtime,
     loadError,
     activeRuntime: runtime ?? loadingRuntimeBridge,
+    progressiveSurface,
     commandAppliedBridge,
     fallbackSnapshot,
     loadingSessionState,
@@ -876,6 +906,8 @@ function createLoadingRuntimeBridge(input: {
   sessionState: EditorSessionState;
   viewState: EditorViewStateSnapshot;
   navigation: DocumentNavigationSnapshot;
+  /** C2c: when present, getRenderSnapshot() injects the progressive surface. */
+  progressiveSurfaceRef?: React.RefObject<EditorSurfaceSnapshot | null>;
 }): WordReviewEditorRuntime {
   const inertLayoutFacet = createInertLayoutFacet();
   const emptyFieldSnapshot: FieldSnapshot = {
@@ -908,7 +940,11 @@ function createLoadingRuntimeBridge(input: {
     subscribe: () => () => undefined,
     subscribeToEvents: () => () => undefined,
     emitBlockedCommand: () => undefined,
-    getRenderSnapshot: () => input.snapshot,
+    getRenderSnapshot: () => {
+      const progressive = input.progressiveSurfaceRef?.current;
+      if (progressive == null) return input.snapshot;
+      return { ...input.snapshot, surface: progressive };
+    },
     getCanonicalDocument: () => input.sessionState.canonicalDocument,
     getSourcePackage: () => input.sessionState.sourcePackage,
     replaceText: () => undefined,
@@ -922,6 +958,7 @@ function createLoadingRuntimeBridge(input: {
     }),
     dispatch: () => undefined,
     applyRemoteCommand: () => undefined,
+    applyRemoteCommandBatch: () => undefined,
     undo: () => undefined,
     redo: () => undefined,
     focus: () => undefined,

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -6,6 +6,7 @@ export type PerfProbeKind =
   | "selection"
   | "runtime.create"
   | "loadSession.laycacheProbe"
+  | "loadSession.compatReportCached"
   | "snapshot.surface"
   | "snapshot.compatibility"
   | "snapshot.navigation"

package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts

@@ -519,6 +519,8 @@ function buildTable(
             borderRight: cell.borderRight ?? null,
             borderBottom: cell.borderBottom ?? null,
             borderLeft: cell.borderLeft ?? null,
+            // R3.a Phase 2 — per-cell text-flow direction.
+            textDirection: cell.textDirection ?? null,
             bandClasses: cell.bandClasses ?? null,
           },
           Fragment.from(cellContent),
@@ -536,6 +538,20 @@ function buildTable(
       Fragment.from(cells),
     ));
   }
+  // R3.a Phase 2 — convert each typed BorderSpec on `tableResolved.borders`
+  // into a CSS shorthand string ("1px solid #000000") so the schema attrs
+  // carry render-ready values. The four outer sides are applied as inline
+  // styles by the node-view; insideH / insideV ride along for round-trip
+  // and future use but do not change CSS at the table level (the per-cell
+  // border resolver already paints them on each cell).
+  const tr = block.tableResolved;
+  const tableBorderTop = tr?.borders?.top ? borderSpecToCss(tr.borders.top) : null;
+  const tableBorderRight = tr?.borders?.right ? borderSpecToCss(tr.borders.right) : null;
+  const tableBorderBottom = tr?.borders?.bottom ? borderSpecToCss(tr.borders.bottom) : null;
+  const tableBorderLeft = tr?.borders?.left ? borderSpecToCss(tr.borders.left) : null;
+  const tableBorderInsideH = tr?.borders?.insideH ? borderSpecToCss(tr.borders.insideH) : null;
+  const tableBorderInsideV = tr?.borders?.insideV ? borderSpecToCss(tr.borders.insideV) : null;
+
   return editorSchema.nodes.table.create(
     {
       styleId: block.styleId ?? null,
@@ -548,11 +564,49 @@ function buildTable(
       tblLookNoHBand: block.tblLook?.noHBand ?? false,
       tblLookNoVBand: block.tblLook?.noVBand ?? false,
       tblLookVal: block.tblLook?.val ?? null,
+      // R3.a Phase 2 — table-level resolved properties.
+      tableWidth: tr?.width ?? null,
+      tableWidthType: tr?.widthType ?? null,
+      tableLayoutMode: tr?.layoutMode ?? null,
+      tableCellSpacing: tr?.cellSpacing ?? null,
+      tableCellSpacingType: tr?.cellSpacingType ?? null,
+      tableBorderTop,
+      tableBorderRight,
+      tableBorderBottom,
+      tableBorderLeft,
+      tableBorderInsideH,
+      tableBorderInsideV,
     },
     Fragment.from(rows),
   );
 }
 
+/**
+ * R3.a Phase 2 — convert a parsed OOXML `BorderSpec` shape (size in eighths of
+ * a point, color hex without `#`, value like "single"/"double"/"dashed") to a
+ * CSS shorthand string. Mirrors the cell-side helper at
+ * `src/runtime/surface-projection.ts:506` so cell + table borders look the
+ * same. Returns `null` for absent / "none" / "nil" specs so callers can stamp
+ * `null` cleanly into PM attrs.
+ */
+function borderSpecToCss(
+  spec: { value?: string; size?: number; color?: string } | null | undefined,
+): string | null {
+  if (!spec) return null;
+  if (spec.value === "none" || spec.value === "nil") return null;
+  const width = spec.size ? `${Math.max(1, Math.round(spec.size / 8))}px` : "1px";
+  const style =
+    spec.value === "double"
+      ? "double"
+      : spec.value === "dashed" || spec.value === "dashSmallGap"
+        ? "dashed"
+        : spec.value === "dotted"
+          ? "dotted"
+          : "solid";
+  const color = spec.color && spec.color !== "auto" ? `#${spec.color}` : "currentColor";
+  return `${width} ${style} ${color}`;
+}
+
 function buildSdtBlock(
   block: Extract<SurfaceBlockSnapshot, { kind: "sdt_block" }>,
   mediaPreviews: Record<string, MediaPreviewDescriptor>,

package/src/ui-tailwind/editor-surface/tw-table-node-view.tsx

@@ -282,11 +282,33 @@ function requestTableLayoutSync(start: HTMLElement): void {
   table?.dispatchEvent(new Event(TABLE_LAYOUT_SYNC_EVENT));
 }
 
+// R3.a Phase 2 — single source of truth for the inline style properties
+// `applyTableAttrs` writes back. Adding a new managed property requires only
+// adding it here (and the matching conditional assignment below); the reset
+// loop will pick it up automatically so stale values can never persist
+// across PM snapshot updates.
+const R3A_MANAGED_TABLE_STYLES = [
+  "marginLeft",
+  "marginRight",
+  "width",
+  "tableLayout",
+  "borderCollapse",
+  "borderSpacing",
+  "borderTop",
+  "borderRight",
+  "borderBottom",
+  "borderLeft",
+] as const;
+
 function applyTableAttrs(table: HTMLTableElement, node: PMNode): void {
-  table.className = "border-collapse w-full my-2 text-sm";
+  // Reset every R3.a-managed inline style first so re-application doesn't
+  // accumulate stale values across PM updates (e.g. width changes, layout
+  // mode flips). The base Tailwind className is rebuilt below to match.
   table.setAttribute("data-pm-table-root", "true");
-  table.style.marginLeft = "";
-  table.style.marginRight = "";
+  for (const prop of R3A_MANAGED_TABLE_STYLES) {
+    table.style[prop] = "";
+  }
+
   const alignment = node.attrs.alignment as string | null | undefined;
   if (alignment === "center") {
     table.style.marginLeft = "auto";
@@ -294,6 +316,67 @@ function applyTableAttrs(table: HTMLTableElement, node: PMNode): void {
   } else if (alignment === "right") {
     table.style.marginLeft = "auto";
   }
+
+  // R3.a Phase 2 — table-level inline styles from resolved properties.
+  // Width: pct → "%", dxa → "pt" (twips/20), auto → "auto", null → unset.
+  // When an explicit width is present we drop Tailwind's `w-full` so the
+  // explicit value wins; otherwise keep the responsive default.
+  const tableWidth = node.attrs.tableWidth as number | null | undefined;
+  const tableWidthType = node.attrs.tableWidthType as string | null | undefined;
+  let baseClasses = "border-collapse w-full my-2 text-sm";
+  if (tableWidthType === "pct" && typeof tableWidth === "number") {
+    // OOXML pct widths are fiftieths of a percent (5000 = 100%).
+    table.style.width = `${tableWidth / 50}%`;
+    baseClasses = "border-collapse my-2 text-sm";
+  } else if (tableWidthType === "dxa" && typeof tableWidth === "number") {
+    table.style.width = `${tableWidth / 20}pt`;
+    baseClasses = "border-collapse my-2 text-sm";
+  } else if (tableWidthType === "auto") {
+    table.style.width = "auto";
+    baseClasses = "border-collapse my-2 text-sm";
+  }
+
+  // Layout mode: w:tblLayout/@w:type. "fixed" → CSS `table-layout: fixed`
+  // (column widths from <colgroup> rule); "autofit" falls through to the
+  // browser default ("auto").
+  const layoutMode = node.attrs.tableLayoutMode as string | null | undefined;
+  if (layoutMode === "fixed") {
+    table.style.tableLayout = "fixed";
+  }
+
+  // Cell spacing: w:tblCellSpacing. Non-zero spacing requires
+  // `border-collapse: separate` in CSS (border-collapse: collapse ignores
+  // border-spacing).
+  // ECMA-376 §17.4.44: w:tblCellSpacing is total spacing between cells in
+  // twentieths of a point; direct CSS border-spacing equivalent.
+  const cellSpacing = node.attrs.tableCellSpacing as number | null | undefined;
+  const cellSpacingType = node.attrs.tableCellSpacingType as string | null | undefined;
+  if (typeof cellSpacing === "number" && cellSpacing > 0 && cellSpacingType === "dxa") {
+    table.style.borderCollapse = "separate";
+    table.style.borderSpacing = `${cellSpacing / 20}pt`;
+    // `border-collapse` overrides Tailwind's `border-collapse` utility, so
+    // strip it from the base class set to avoid the conflicting cascade
+    // result that some browsers cache.
+    baseClasses = baseClasses.replace("border-collapse", "border-separate");
+  }
+
+  // Outer borders (top / right / bottom / left) — apply directly as inline
+  // styles. insideH / insideV are intentionally NOT applied at the table
+  // level because CSS has no native "table-inside-border" property; their
+  // visual effect is realized through per-cell borders projected on the
+  // cell snapshot via resolveCellBorderStyles in surface-projection.
+  // (See Lane 3b R3.a Phase 2 close-out plan: "option 1 — cell-level
+  // fallback".)
+  const tBorderTop = node.attrs.tableBorderTop as string | null | undefined;
+  const tBorderRight = node.attrs.tableBorderRight as string | null | undefined;
+  const tBorderBottom = node.attrs.tableBorderBottom as string | null | undefined;
+  const tBorderLeft = node.attrs.tableBorderLeft as string | null | undefined;
+  if (tBorderTop) table.style.borderTop = tBorderTop;
+  if (tBorderRight) table.style.borderRight = tBorderRight;
+  if (tBorderBottom) table.style.borderBottom = tBorderBottom;
+  if (tBorderLeft) table.style.borderLeft = tBorderLeft;
+
+  table.className = baseClasses;
   syncColgroup(table, node);
 }
 
@@ -423,6 +506,27 @@ function applyCellAttrs(cell: HTMLTableCellElement, node: PMNode, isHeader: bool
   cell.style.borderRight = borderRight ?? "";
   cell.style.borderBottom = borderBottom ?? "";
   cell.style.borderLeft = borderLeft ?? "";
+
+  // R3.a Phase 2 — vertical text direction. OOXML: tbRl = top→bottom, right→left
+  // (most common for vertical headers, reads when tilting the head right);
+  // btLr = bottom→top, left→right (rare, reads tilting head left); lrTb is the
+  // default horizontal flow. CSS `writing-mode` is the direct equivalent.
+  const textDirection = node.attrs.textDirection as
+    | "lrTb"
+    | "tbRl"
+    | "btLr"
+    | null
+    | undefined;
+  cell.style.writingMode = "";
+  if (textDirection === "tbRl") {
+    cell.style.writingMode = "vertical-rl";
+    cell.setAttribute("data-text-direction", "tbRl");
+  } else if (textDirection === "btLr") {
+    cell.style.writingMode = "vertical-lr";
+    cell.setAttribute("data-text-direction", "btLr");
+  } else {
+    cell.removeAttribute("data-text-direction");
+  }
 }
 
 /**

package/src/ui-tailwind/page-stack/tw-footnote-area.tsx

@@ -32,7 +32,7 @@ export interface TwFootnoteAreaProps {
   "data-testid"?: string;
 }
 
-export const TwFootnoteArea: React.FC<TwFootnoteAreaProps> = ({
+export const TwFootnoteArea: React.FC<TwFootnoteAreaProps> = React.memo(({
   pageIndex,
   blocks,
   topPx,
@@ -66,6 +66,6 @@ export const TwFootnoteArea: React.FC<TwFootnoteAreaProps> = ({
       <TwRegionBlockRenderer blocks={blocks} />
     </div>
   );
-};
+});
 
 export default TwFootnoteArea;

package/src/ui-tailwind/page-stack/tw-page-chrome-entry.tsx

@@ -0,0 +1,224 @@
+/**
+ * TwPageChromeEntry — memo-wrapped per-page chrome subtree.
+ *
+ * Extracted from `TwPageStackChromeLayer`'s per-page `.map()` so that
+ * `React.memo` can skip re-renders for pages whose `page` reference is
+ * stable (guaranteed post-D1+B2 for pages past the splice-convergence
+ * point).  Rect values are compared structurally (topPx / bottomPx /
+ * pageId) because `resolvePageOverlayRects` allocates new objects each
+ * measurement pass even when positions haven't changed.
+ *
+ * Block arrays and click-handler callbacks are memoized on
+ * `(page, renderFrameRevision)` so they don't create new references
+ * when the page is unchanged.
+ */
+
+import React from "react";
+import type {
+  EditorStoryTarget,
+  PublicPageNode,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types.ts";
+import type { PageOverlayRect } from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
+import { FRAME_PX_PER_TWIP_AT_96DPI } from "../tw-review-workspace.tsx";
+import { TwPageHeaderBand } from "./tw-page-header-band.tsx";
+import { TwPageFooterBand } from "./tw-page-footer-band.tsx";
+import { TwFootnoteArea } from "./tw-footnote-area.tsx";
+
+export interface TwPageChromeEntryProps {
+  rect: PageOverlayRect;
+  pageIndex: number;
+  page: PublicPageNode;
+  facet: WordReviewEditorLayoutFacet;
+  activeStory: EditorStoryTarget;
+  onOpenStory?: (target: EditorStoryTarget) => void;
+  visiblePageIndexRange?: { start: number; end: number } | null;
+  renderFrameRevision: number;
+}
+
+function TwPageChromeEntryInner({
+  rect,
+  pageIndex,
+  page,
+  facet,
+  activeStory,
+  onOpenStory,
+  visiblePageIndexRange,
+  renderFrameRevision,
+}: TwPageChromeEntryProps): React.ReactElement {
+  const layout = page.layout;
+  const headerStory = page.stories.header;
+  const footerStory = page.stories.footer;
+  const headerRegion = page.regions.header;
+  const footerRegion = page.regions.footer;
+  const footnoteRegion = page.regions.footnotes?.[0];
+
+  // All hooks must be called unconditionally before any early return.
+  const headerBlocks = React.useMemo(
+    () =>
+      headerStory
+        ? facet.getStoryBlocksForRegion(pageIndex, "header").map((b) => b.blockSnapshot)
+        : [],
+    // `page` as dependency captures per-page reference stability (D1+B2):
+    // when page ref is stable, the memo doesn't re-run even if revision ticks.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [facet, pageIndex, page, renderFrameRevision],
+  );
+
+  const footerBlocks = React.useMemo(
+    () =>
+      footerStory
+        ? facet.getStoryBlocksForRegion(pageIndex, "footer").map((b) => b.blockSnapshot)
+        : [],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [facet, pageIndex, page, renderFrameRevision],
+  );
+
+  const footnoteBlocks = React.useMemo(
+    () =>
+      footnoteRegion
+        ? facet
+            .getStoryBlocksForRegion(pageIndex, "footnote-area")
+            .map((b) => b.blockSnapshot)
+        : [],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [facet, pageIndex, page, renderFrameRevision],
+  );
+
+  const handleHeaderClick = React.useCallback(
+    () => headerStory && onOpenStory?.(headerStory),
+    [onOpenStory, headerStory],
+  );
+
+  const handleFooterClick = React.useCallback(
+    () => footerStory && onOpenStory?.(footerStory),
+    [onOpenStory, footerStory],
+  );
+
+  const frameHeightPx = rect.bottomPx - rect.topPx;
+
+  // Viewport cull — lightweight placeholder outside the visible range.
+  const isCulled =
+    visiblePageIndexRange !== null &&
+    visiblePageIndexRange !== undefined &&
+    (pageIndex < visiblePageIndexRange.start || pageIndex >= visiblePageIndexRange.end);
+
+  if (isCulled) {
+    return (
+      <div
+        data-page-chrome-frame=""
+        data-page-index={pageIndex}
+        data-page-chrome-culled=""
+        style={{
+          position: "absolute",
+          top: `${rect.topPx}px`,
+          left: 0,
+          width: "100%",
+          height: `${frameHeightPx}px`,
+          pointerEvents: "none",
+        }}
+      />
+    );
+  }
+
+  const px = (twips: number): number => twips * FRAME_PX_PER_TWIP_AT_96DPI;
+  const bandWidthPx = px(layout.pageWidth - layout.marginLeft - layout.marginRight);
+  const bandLeftPx = px(layout.marginLeft);
+
+  return (
+    <div
+      data-page-chrome-frame=""
+      data-page-index={pageIndex}
+      style={{
+        position: "absolute",
+        top: `${rect.topPx}px`,
+        left: 0,
+        width: "100%",
+        height: `${frameHeightPx}px`,
+        pointerEvents: "none",
+      }}
+    >
+      {headerRegion && headerStory ? (
+        <TwPageHeaderBand
+          pageIndex={pageIndex}
+          blocks={headerBlocks}
+          topPx={px(layout.headerMargin ?? 720)}
+          leftPx={bandLeftPx}
+          widthPx={bandWidthPx}
+          bandHeightPx={px(headerRegion.heightTwips)}
+          isActiveSlot={isActiveStoryMatch(activeStory, headerStory)}
+          onClick={handleHeaderClick}
+        />
+      ) : null}
+      {footerRegion && footerStory ? (
+        <TwPageFooterBand
+          pageIndex={pageIndex}
+          blocks={footerBlocks}
+          bottomPx={px(layout.footerMargin ?? 720)}
+          leftPx={bandLeftPx}
+          widthPx={bandWidthPx}
+          bandHeightPx={px(footerRegion.heightTwips)}
+          isActiveSlot={isActiveStoryMatch(activeStory, footerStory)}
+          onClick={handleFooterClick}
+        />
+      ) : null}
+      {footnoteRegion ? (
+        <TwFootnoteArea
+          pageIndex={pageIndex}
+          blocks={footnoteBlocks}
+          topPx={px(footnoteRegion.originTwips - layout.marginTop)}
+          leftPx={bandLeftPx}
+          widthPx={px(footnoteRegion.widthTwips)}
+          heightPx={px(footnoteRegion.heightTwips)}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function propsAreEqual(
+  prev: TwPageChromeEntryProps,
+  next: TwPageChromeEntryProps,
+): boolean {
+  return (
+    prev.pageIndex === next.pageIndex &&
+    prev.page === next.page &&
+    prev.facet === next.facet &&
+    prev.activeStory === next.activeStory &&
+    prev.onOpenStory === next.onOpenStory &&
+    prev.visiblePageIndexRange === next.visiblePageIndexRange &&
+    prev.renderFrameRevision === next.renderFrameRevision &&
+    prev.rect.topPx === next.rect.topPx &&
+    prev.rect.bottomPx === next.rect.bottomPx &&
+    prev.rect.pageId === next.rect.pageId
+  );
+}
+
+export const TwPageChromeEntry = React.memo(TwPageChromeEntryInner, propsAreEqual);
+
+function isActiveStoryMatch(
+  active: EditorStoryTarget,
+  candidate: EditorStoryTarget,
+): boolean {
+  if (active.kind !== candidate.kind) return false;
+  if (active.kind === "main" || candidate.kind === "main") {
+    return active.kind === candidate.kind;
+  }
+  if (active.kind === "footnote" && candidate.kind === "footnote") {
+    return active.noteId === candidate.noteId;
+  }
+  if (active.kind === "endnote" && candidate.kind === "endnote") {
+    return active.noteId === candidate.noteId;
+  }
+  if (
+    (active.kind === "header" && candidate.kind === "header") ||
+    (active.kind === "footer" && candidate.kind === "footer")
+  ) {
+    return (
+      active.relationshipId === candidate.relationshipId &&
+      active.variant === candidate.variant &&
+      active.sectionIndex === candidate.sectionIndex
+    );
+  }
+  return false;
+}

package/src/ui-tailwind/page-stack/tw-page-footer-band.tsx

@@ -31,7 +31,7 @@ export interface TwPageFooterBandProps {
   "data-testid"?: string;
 }
 
-export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = ({
+export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
   pageIndex,
   blocks,
   bandHeightPx,
@@ -68,6 +68,6 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = ({
       )}
     </div>
   );
-};
+});
 
 export default TwPageFooterBand;

package/src/ui-tailwind/page-stack/tw-page-header-band.tsx

@@ -32,7 +32,7 @@ export interface TwPageHeaderBandProps {
   "data-testid"?: string;
 }
 
-export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = ({
+export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
   pageIndex,
   blocks,
   bandHeightPx,
@@ -69,6 +69,6 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = ({
       )}
     </div>
   );
-};
+});
 
 export default TwPageHeaderBand;