@beyondwork/docx-react-component 1.0.71 → 1.0.73

package/src/ui-tailwind/editor-surface/tw-page-block-view.helpers.ts

@@ -85,6 +85,54 @@ export function resolveMarkerAlignCss(raw: string | undefined): React.CSSPropert
   }
 }
 
+/**
+ * Precompute per-tab-segment widths from the paragraph's tabStops.
+ *
+ * Returns a map `segmentId -> widthPt`. The N-th tab segment gets the
+ * width `(tabStops[N].pos - (tabStops[N-1]?.pos ?? 0)) / 20` points —
+ * the horizontal span from the previous stop (or the paragraph's
+ * content-left edge) to the current stop.
+ *
+ * This is a conservative approximation of Word's real tab algorithm
+ * (which advances to the next stop >= cumulative X considering prior
+ * content width). Without run-width measurement, the approximation
+ * holds best when the text in each zone is short relative to the zone
+ * width — which is exactly the three-zone-header / TOC case L11 needs
+ * to render correctly.
+ *
+ * Direct `block.tabStops` wins over `block.resolvedParagraphFormatting.tabStops`
+ * (consistent with other resolved fields).
+ */
+export function computeTabWidthsInPoints(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): Map<string, number> {
+  const widths = new Map<string, number>();
+  // Direct `block.tabStops` uses the public `{pos, val?, leader?}` shape;
+  // `block.resolvedParagraphFormatting.tabStops` uses the canonical
+  // `{position, align, leader?}` shape. Normalize to a single accessor.
+  const readPos = (stop: { pos?: number; position?: number }): number =>
+    stop.pos ?? stop.position ?? 0;
+
+  const rawStops: Array<{ pos?: number; position?: number }> | undefined =
+    block.tabStops ?? block.resolvedParagraphFormatting?.tabStops;
+  if (!rawStops || rawStops.length === 0) return widths;
+
+  let tabIndex = 0;
+  for (const seg of block.segments) {
+    if (seg.kind !== "tab") continue;
+    const stop = rawStops[tabIndex];
+    if (stop) {
+      const prevPos = tabIndex > 0 ? readPos(rawStops[tabIndex - 1]) : 0;
+      const widthTwips = readPos(stop) - prevPos;
+      if (widthTwips > 0) {
+        widths.set(seg.segmentId, widthTwips / 20);
+      }
+    }
+    tabIndex += 1;
+  }
+  return widths;
+}
+
 /** Build CSSProperties for a paragraph block from spacing/indent/alignment. */
 export function buildParagraphStyle(
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
@@ -159,6 +207,43 @@ export function buildParagraphStyle(
   const shadingColor = safeHexColor(shadingFill);
   if (shadingColor) style.backgroundColor = shadingColor;
 
+  // Paragraph borders (`w:pBdr`). Mirror `pm-schema.ts::paragraph.toDOM`
+  // so the static render path (pages 2+, non-PM) paints the same
+  // borders as the PM-rendered page 1. Reads the PublicBorderSpec shape
+  // (`{value, size, space, color}`); `size` is eighths of a point.
+  const borders = block.borders;
+  if (borders) {
+    const sideToCss: Array<["top" | "bottom" | "left" | "right", keyof NonNullable<typeof borders>]> = [
+      ["top", "top"],
+      ["bottom", "bottom"],
+      ["left", "left"],
+      ["right", "right"],
+    ];
+    for (const [cssSide, key] of sideToCss) {
+      const border = borders[key];
+      if (!border || !border.value || border.value === "none" || border.value === "nil") continue;
+      const width = border.size ? `${Math.max(1, Math.round(border.size / 8))}px` : "1px";
+      const color = safeHexColor(border.color ?? null) ?? "#000000";
+      const bStyle =
+        border.value === "double"
+          ? "double"
+          : border.value === "dashed" || border.value === "dashSmallGap"
+            ? "dashed"
+            : border.value === "dotted"
+              ? "dotted"
+              : "solid";
+      const cssKey =
+        cssSide === "top"
+          ? "borderTop"
+          : cssSide === "bottom"
+            ? "borderBottom"
+            : cssSide === "left"
+              ? "borderLeft"
+              : "borderRight";
+      (style as Record<string, string>)[cssKey] = `${width} ${bStyle} ${color}`;
+    }
+  }
+
   // Page break visual indicator
   if (block.pageBreakBefore) {
     style.borderTop = "2px dashed rgba(0,0,0,0.1)";
@@ -166,6 +251,35 @@ export function buildParagraphStyle(
     style.marginTop = "16px";
   }
 
+  // `<w:framePr>` out-of-flow frame (ECMA-376 §17.3.1.11). L04 returns 0
+  // from measureBlockHeight for these paragraphs (a298391e) so the inline
+  // flow doesn't double-count; L11 renders them absolutely positioned.
+  // Drop-cap (dropCap="drop"|"margin") is in-flow — only the initial
+  // letter is framed — so skip the absolute switch there.
+  const framePr = block.frameProperties;
+  if (framePr && framePr.dropCap !== "drop" && framePr.dropCap !== "margin") {
+    style.position = "absolute";
+    if (typeof framePr.xTwips === "number") {
+      style.left = `${framePr.xTwips / 20}pt`;
+    }
+    if (typeof framePr.yTwips === "number") {
+      style.top = `${framePr.yTwips / 20}pt`;
+    }
+    if (typeof framePr.widthTwips === "number") {
+      style.width = `${framePr.widthTwips / 20}pt`;
+    }
+    if (typeof framePr.heightTwips === "number") {
+      if (framePr.hRule === "exact") {
+        style.height = `${framePr.heightTwips / 20}pt`;
+      } else if (framePr.hRule === "atLeast") {
+        style.minHeight = `${framePr.heightTwips / 20}pt`;
+      }
+      // hRule === "auto" (or missing) leaves the frame's vertical size
+      // content-driven. The height field is ignored — OOXML treats the
+      // value as a hint that layout engines may override.
+    }
+  }
+
   return style;
 }
 

package/src/ui-tailwind/editor-surface/tw-page-block-view.tsx

@@ -8,6 +8,7 @@ import {
   buildMarkerStyle,
   buildParagraphStyle,
   buildSegmentStyle,
+  computeTabWidthsInPoints,
   hasStyleEntries,
   headingClassList,
   resolveHeadingLevel,
@@ -18,7 +19,7 @@ import {
 // ---------------------------------------------------------------------------
 
 /** Render a single inline segment. */
-function renderSegment(seg: SurfaceInlineSegment): React.ReactNode {
+function renderSegment(seg: SurfaceInlineSegment, tabWidthsPt: Map<string, number>): React.ReactNode {
   switch (seg.kind) {
     case "text": {
       const style = buildSegmentStyle(seg.marks, seg.markAttrs);
@@ -32,16 +33,22 @@ function renderSegment(seg: SurfaceInlineSegment): React.ReactNode {
         </span>
       );
     }
-    case "tab":
+    case "tab": {
+      const widthPt = tabWidthsPt.get(seg.segmentId);
+      const tabStyle: React.CSSProperties =
+        typeof widthPt === "number"
+          ? { display: "inline-block", width: `${widthPt}pt`, minWidth: "8px" }
+          : { display: "inline-block", width: "32px", minWidth: "8px" };
       return (
         <span
           key={seg.segmentId}
           data-node-type="tab"
-          style={{ display: "inline-block", width: "32px", minWidth: "8px" }}
+          style={tabStyle}
         >
           {"\u00A0"}
         </span>
       );
+    }
     case "hard_break":
       return <br key={seg.segmentId} />;
     case "image":
@@ -114,6 +121,7 @@ function ParagraphBlock({
   }
 
   const pStyle = buildParagraphStyle(block);
+  const tabWidthsPt = computeTabWidthsInPoints(block);
   const attrs: React.HTMLAttributes<HTMLParagraphElement> & {
     "data-heading-level"?: string;
     "data-numbered"?: string;
@@ -177,7 +185,7 @@ function ParagraphBlock({
     <p {...attrs}>
       {prefixSpan}
       <span className="pm-paragraph-content">
-        {block.segments.map((seg) => renderSegment(seg))}
+        {block.segments.map((seg) => renderSegment(seg, tabWidthsPt))}
       </span>
     </p>
   );

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -53,7 +53,7 @@ import { buildDecorations } from "./pm-decorations";
 import { buildPageBreakDecorations } from "./pm-page-break-decorations";
 import { DecorationSet } from "prosemirror-view";
 import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
-import { buildPagePreviewMaps } from "../../runtime/layout/resolve-page-previews";
+import { buildPagePreviewMaps } from "../../api/public-types";
 import { createContextualInteractionPlugin } from "./pm-contextual-ui";
 import {
   finishPerfProbe,
@@ -65,7 +65,10 @@ import { buildPositionMap, type PositionMap } from "./pm-position-map";
 import { createLocalEditSessionState } from "./local-edit-session-state";
 import { createFastTextEditLane } from "./fast-text-edit-lane";
 import { createPredictedTxGate } from "./predicted-tx-gate";
-import { createScopeTagRegistry } from "../../runtime/workflow/scope-tag-registry";
+import {
+  createScopeTagRegistry,
+  type ScopeTagRegistry,
+} from "../../api/public-types";
 import { hasBailIfCrossedTagInRange } from "./predicted-tag-preflight";
 import {
   clearSearch as clearSearchPlugin,
@@ -265,6 +268,20 @@ export interface TwProseMirrorSurfaceProps {
   runtimeGetTableSelectionDescriptor?: (
     state: import("prosemirror-state").EditorState,
   ) => TableSelectionDescriptor | null;
+  /**
+   * Coord-10 L11-4 — host-supplied scope-tag registry factory.
+   * Threaded from `api.runtime.workflow.createScopeTagRegistry` at the
+   * WordReviewEditor mount. Mints a fresh default-seeded
+   * `ScopeTagRegistry` that the PM surface uses to drive annotation-
+   * family boundary behaviors (bail-on-cross, split-on-cross, etc.).
+   *
+   * When omitted, the surface falls back to the public-types re-export
+   * (`createScopeTagRegistry` from `src/api/public-types.ts`, shipped
+   * 2026-04-24 per refactor/11 §4.17 as a pragmatic pass-through).
+   * The fallback is retained for back-compat with any consumer that
+   * mounts the surface without threading an api handle (legacy tests).
+   */
+  scopeTagRegistryFactory?: () => ScopeTagRegistry;
   onPasteApplied?: (meta: {
     segmentCount: number;
     charCount: number;
@@ -435,9 +452,17 @@ export const TwProseMirrorSurface = forwardRef<
   const snapshotRef = useRef(snapshot);
   snapshotRef.current = snapshot;
 
+  // Coord-10 L11-4 — prefer the host-supplied `scopeTagRegistryFactory`
+  // (threaded from `api.runtime.workflow.createScopeTagRegistry` at the
+  // WordReviewEditor mount); fall back to the public-types re-export
+  // for legacy mounts that don't thread an api handle.
+  const scopeTagRegistryFactoryProp = props.scopeTagRegistryFactory;
   const scopeTagRegistry = useMemo(
-    () => createScopeTagRegistry(),
-    [],
+    () =>
+      scopeTagRegistryFactoryProp
+        ? scopeTagRegistryFactoryProp()
+        : createScopeTagRegistry(),
+    [scopeTagRegistryFactoryProp],
   );
 
   // Keep callbacks ref up to date (avoids stale closures in PM plugins)

package/src/ui-tailwind/index.ts

@@ -112,11 +112,13 @@ export {
   type TwScopeRailLayerProps,
 } from "./chrome-overlay";
 
-// Session capabilities
+// Session capabilities — sourced via `src/api/public-types` re-export
+// so the public facade under `src/ui-tailwind/**` stays P3-clean.
+// Canonical impl lives on `src/runtime/session-capabilities.ts`.
 export {
   deriveCapabilities,
   type SessionCapabilities,
-} from "../runtime/session-capabilities";
+} from "../api/public-types";
 
 // Headless (re-export for convenience)
 export {

package/src/ui-tailwind/page-chrome-model.ts

@@ -1,16 +1,14 @@
-import type {
-  DocumentNavigationSnapshot,
-  PageLayoutSnapshot,
-  SurfaceBlockSnapshot,
-} from "../api/public-types.ts";
-import { findPageForOffset } from "../runtime/document-navigation.ts";
 import {
+  type DocumentNavigationSnapshot,
+  type PageLayoutSnapshot,
+  type SurfaceBlockSnapshot,
+  findPageForOffset,
   DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP,
   estimateBlockHeight,
   estimateParagraphLineCount,
   estimateParagraphLineHeight,
   getUsableColumnWidth,
-} from "../runtime/page-layout-estimation.ts";
+} from "../api/public-types.ts";
 
 const DOCUMENT_CONTENT_TOP_PADDING_PX = 40;
 

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

@@ -7,8 +7,11 @@ import type {
   SurfaceInlineSegment,
 } from "../../api/public-types.ts";
 import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
-import { storyTargetKey } from "../../runtime/story-targeting.ts";
-import { EMU_PER_PX, TWIPS_PER_PX } from "../../api/public-types.ts";
+import {
+  storyTargetKey,
+  EMU_PER_PX,
+  TWIPS_PER_PX,
+} from "../../api/public-types.ts";
 import type { PageOverlayRect } from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
 
 /**
@@ -98,40 +101,57 @@ export function collectFloatingImageOverlayItems(input: {
   );
   const items: FloatingImageOverlayItem[] = [];
 
-  walkSurfaceBlocks(surface.blocks, (segment) => {
-    if (segment.kind !== "image" || !shouldRenderAbsoluteFloatingImageInPageOverlay(segment.anchor)) {
-      return;
-    }
-
-    const pages = resolveTargetPages(facet, segment.from, activeStory);
-    for (const page of pages) {
-      const pageRect = rectByPageIndex.get(page.pageIndex);
-      if (!pageRect) {
-        continue;
+  const collectFromStory = (
+    blocks: readonly SurfaceBlockSnapshot[],
+    storyTarget: EditorStoryTarget,
+  ) => {
+    walkSurfaceBlocks(blocks, (segment) => {
+      if (
+        segment.kind !== "image" ||
+        !shouldRenderAbsoluteFloatingImageInPageOverlay(segment.anchor)
+      ) {
+        return;
       }
-      const localRect = resolveFloatingImageLocalRect(page, activeStory, segment, pxPerTwip);
-      if (!localRect) {
-        continue;
+
+      const pages = resolveTargetPages(facet, segment.from, storyTarget);
+      for (const page of pages) {
+        const pageRect = rectByPageIndex.get(page.pageIndex);
+        if (!pageRect) {
+          continue;
+        }
+        const localRect = resolveFloatingImageLocalRect(page, storyTarget, segment, pxPerTwip);
+        if (!localRect) {
+          continue;
+        }
+        const preview = input.mediaPreviews?.[segment.mediaId];
+        items.push({
+          key: `${segment.segmentId}:${page.pageId}`,
+          mediaId: segment.mediaId,
+          from: segment.from,
+          to: segment.to,
+          pageId: page.pageId,
+          pageIndex: page.pageIndex,
+          topPx: pageRect.topPx + localRect.topPx,
+          leftPx: localRect.leftPx,
+          widthPx: localRect.widthPx,
+          heightPx: localRect.heightPx,
+          behindDoc: Boolean(segment.anchor?.behindDoc),
+          src: preview?.src ?? null,
+          altText: segment.altText ?? null,
+          detail: segment.detail ?? null,
+        });
       }
-      const preview = input.mediaPreviews?.[segment.mediaId];
-      items.push({
-        key: `${segment.segmentId}:${page.pageId}`,
-        mediaId: segment.mediaId,
-        from: segment.from,
-        to: segment.to,
-        pageId: page.pageId,
-        pageIndex: page.pageIndex,
-        topPx: pageRect.topPx + localRect.topPx,
-        leftPx: localRect.leftPx,
-        widthPx: localRect.widthPx,
-        heightPx: localRect.heightPx,
-        behindDoc: Boolean(segment.anchor?.behindDoc),
-        src: preview?.src ?? null,
-        altText: segment.altText ?? null,
-        detail: segment.detail ?? null,
-      });
-    }
-  });
+    });
+  };
+
+  // coord-01 §9 / §5.1 — CCEP logos live in header stories; collect from
+  // the main story for the active-story case AND from every secondary
+  // story so header/footer images reach the overlay regardless of which
+  // story is active in the editor.
+  collectFromStory(surface.blocks, activeStory);
+  for (const secondary of surface.secondaryStories ?? []) {
+    collectFromStory(secondary.blocks, secondary.target);
+  }
 
   return items;
 }

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

@@ -1,6 +1,7 @@
 import React from "react";
 
 import type { SurfaceBlockSnapshot } from "../../api/public-types.ts";
+import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
 
 // ---------------------------------------------------------------------------
@@ -27,11 +28,13 @@ import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
 export interface TwEndnoteAreaProps {
   blocks: readonly SurfaceBlockSnapshot[];
   "data-testid"?: string;
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
 }
 
 export const TwEndnoteArea: React.FC<TwEndnoteAreaProps> = ({
   blocks,
   "data-testid": testId,
+  mediaPreviews,
 }) => {
   if (blocks.length === 0) return null;
   return (
@@ -49,7 +52,7 @@ export const TwEndnoteArea: React.FC<TwEndnoteAreaProps> = ({
           marginBottom: "8pt",
         }}
       />
-      <TwRegionBlockRenderer blocks={blocks} />
+      <TwRegionBlockRenderer blocks={blocks} mediaPreviews={mediaPreviews} />
     </div>
   );
 };

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

@@ -1,6 +1,7 @@
 import React from "react";
 
 import type { SurfaceBlockSnapshot } from "../../api/public-types.ts";
+import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
 
 // ---------------------------------------------------------------------------
@@ -30,6 +31,7 @@ export interface TwFootnoteAreaProps {
   widthPx: number;
   heightPx: number;
   "data-testid"?: string;
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
 }
 
 export const TwFootnoteArea: React.FC<TwFootnoteAreaProps> = React.memo(({
@@ -40,6 +42,7 @@ export const TwFootnoteArea: React.FC<TwFootnoteAreaProps> = React.memo(({
   widthPx,
   heightPx,
   "data-testid": testId,
+  mediaPreviews,
 }) => {
   return (
     <div
@@ -63,7 +66,7 @@ export const TwFootnoteArea: React.FC<TwFootnoteAreaProps> = React.memo(({
           marginBottom: "4pt",
         }}
       />
-      <TwRegionBlockRenderer blocks={blocks} />
+      <TwRegionBlockRenderer blocks={blocks} mediaPreviews={mediaPreviews} />
     </div>
   );
 });

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

@@ -26,6 +26,7 @@ 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";
+import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 
 export interface TwPageChromeEntryProps {
   rect: PageOverlayRect;
@@ -36,6 +37,9 @@ export interface TwPageChromeEntryProps {
   onOpenStory?: (target: EditorStoryTarget) => void;
   visiblePageIndexRange?: { start: number; end: number } | null;
   renderFrameRevision: number;
+  /** Preview catalog threaded into header/footer/footnote region renderers
+   *  so images (CCEP logos on 7-of-8 CCEP docs) render as real <img>s. */
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
 }
 
 function TwPageChromeEntryInner({
@@ -47,6 +51,7 @@ function TwPageChromeEntryInner({
   onOpenStory,
   visiblePageIndexRange,
   renderFrameRevision,
+  mediaPreviews,
 }: TwPageChromeEntryProps): React.ReactElement {
   const layout = page.layout;
   const headerStory = page.stories.header;
@@ -186,6 +191,7 @@ function TwPageChromeEntryInner({
           isActiveSlot={Boolean(headerActive)}
           sectionLabel={headerActive ? headerSectionLabel : undefined}
           onClick={handleHeaderClick}
+          mediaPreviews={mediaPreviews}
         />
       ) : null}
       {footerRegion && footerStory ? (
@@ -199,6 +205,7 @@ function TwPageChromeEntryInner({
           isActiveSlot={Boolean(footerActive)}
           sectionLabel={footerActive ? footerSectionLabel : undefined}
           onClick={handleFooterClick}
+          mediaPreviews={mediaPreviews}
         />
       ) : null}
       {footnoteRegion ? (
@@ -209,6 +216,7 @@ function TwPageChromeEntryInner({
           leftPx={bandLeftPx}
           widthPx={px(footnoteRegion.widthTwips)}
           heightPx={px(footnoteRegion.heightTwips)}
+          mediaPreviews={mediaPreviews}
         />
       ) : null}
       {continuationTableEntries.map(({ blockId, headerRows }) => (
@@ -240,7 +248,8 @@ function propsAreEqual(
     prev.renderFrameRevision === next.renderFrameRevision &&
     prev.rect.topPx === next.rect.topPx &&
     prev.rect.bottomPx === next.rect.bottomPx &&
-    prev.rect.pageId === next.rect.pageId
+    prev.rect.pageId === next.rect.pageId &&
+    prev.mediaPreviews === next.mediaPreviews
   );
 }
 

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

@@ -1,6 +1,7 @@
 import React from "react";
 
 import type { SurfaceBlockSnapshot } from "../../api/public-types.ts";
+import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
 
 // ---------------------------------------------------------------------------
@@ -34,6 +35,7 @@ export interface TwPageFooterBandProps {
   sectionLabel?: string;
   onClick: () => void;
   "data-testid"?: string;
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
 }
 
 export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
@@ -47,6 +49,7 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
   sectionLabel,
   onClick,
   "data-testid": testId,
+  mediaPreviews,
 }) => {
   return (
     <div
@@ -77,7 +80,11 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
           style={{ width: "100%", height: "100%" }}
         />
       ) : (
-        <TwRegionBlockRenderer blocks={blocks} />
+        <TwRegionBlockRenderer
+          blocks={blocks}
+          mediaPreviews={mediaPreviews}
+          fallbackDisplay="hidden"
+        />
       )}
     </div>
   );

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

@@ -1,6 +1,7 @@
 import React from "react";
 
 import type { SurfaceBlockSnapshot } from "../../api/public-types.ts";
+import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
 
 // ---------------------------------------------------------------------------
@@ -35,6 +36,10 @@ export interface TwPageHeaderBandProps {
   sectionLabel?: string;
   onClick: () => void;
   "data-testid"?: string;
+  /** Preview catalog threaded to the region renderer so header images
+   *  (CCEP logos on 7-of-8 CCEP docs) render as real <img>s instead of
+   *  the 48×32 placeholder chip. */
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
 }
 
 export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
@@ -48,6 +53,7 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
   sectionLabel,
   onClick,
   "data-testid": testId,
+  mediaPreviews,
 }) => {
   return (
     <div
@@ -78,7 +84,11 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
           style={{ width: "100%", height: "100%" }}
         />
       ) : (
-        <TwRegionBlockRenderer blocks={blocks} />
+        <TwRegionBlockRenderer
+          blocks={blocks}
+          mediaPreviews={mediaPreviews}
+          fallbackDisplay="hidden"
+        />
       )}
     </div>
   );

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

@@ -145,6 +145,10 @@ export interface TwPageStackChromeLayerProps {
   visiblePageIndexRange?: { start: number; end: number } | null;
   /** Optional test id applied to the layer root. */
   "data-testid"?: string;
+  /** Preview catalog threaded through to per-page chrome bands so images
+   *  in headers/footers/footnote bodies render as real <img>s. Without
+   *  this, image segments fall back to the 48×32 gray placeholder chip. */
+  mediaPreviews?: Record<string, import("../editor-surface/pm-state-from-snapshot.ts").MediaPreviewDescriptor>;
 }
 
 const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
@@ -157,6 +161,7 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
   pmView,
   visiblePageIndexRange,
   "data-testid": testId,
+  mediaPreviews,
 }) => {
   const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
   const overlayRootRef = React.useRef<HTMLDivElement | null>(null);
@@ -401,10 +406,11 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
             onOpenStory={onOpenStory}
             visiblePageIndexRange={visiblePageIndexRange}
             renderFrameRevision={renderFrameRevision}
+            mediaPreviews={mediaPreviews}
           />
         );
       })}
-      <TwEndnoteArea blocks={endnoteBlocks} />
+      <TwEndnoteArea blocks={endnoteBlocks} mediaPreviews={mediaPreviews} />
     </div>
   );
 };