@beyondwork/docx-react-component 1.0.71 → 1.0.72

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -253,12 +253,26 @@ export const editorSchema = new Schema({
         else if (indentFirstLine) styles.push(`text-indent: ${indentFirstLine / 20}pt`);
         const shadingColor = safeHexColor(node.attrs.shadingFill as string | null);
         if (shadingColor) styles.push(`background-color: ${shadingColor}`);
+        // Paragraph borders. Reads the PublicBorderSpec shape
+        // (`{value, size, space, color}`) that `pm-state-from-snapshot.ts`
+        // forwards verbatim from `SurfaceBlockFragment.borders`. `size` is
+        // in eighths of a point (ECMA-376 §17.18.88 ST_Border); `value`
+        // follows ECMA-376 §17.18.2 ST_Border enumeration.
         for (const [side, attrName] of [["top", "borderTop"], ["bottom", "borderBottom"], ["left", "borderLeft"], ["right", "borderRight"]] as const) {
-          const border = node.attrs[attrName] as { color?: string; sz?: number; val?: string } | null;
-          if (border && border.val && border.val !== "none") {
-            const width = border.sz ? `${border.sz / 8}px` : "1px";
+          const border = node.attrs[attrName] as
+            | { color?: string; size?: number; space?: number; value?: string }
+            | null;
+          if (border && border.value && border.value !== "none" && border.value !== "nil") {
+            const width = border.size ? `${Math.max(1, Math.round(border.size / 8))}px` : "1px";
             const color = safeHexColor(border.color ?? null) ?? "#000000";
-            const bStyle = border.val === "dotted" ? "dotted" : border.val === "dashed" ? "dashed" : "solid";
+            const bStyle =
+              border.value === "double"
+                ? "double"
+                : border.value === "dashed" || border.value === "dashSmallGap"
+                  ? "dashed"
+                  : border.value === "dotted"
+                    ? "dotted"
+                    : "solid";
             styles.push(`border-${side}: ${width} ${bStyle} ${color}`);
           }
         }

package/src/ui-tailwind/editor-surface/scroll-anchor.ts

@@ -101,10 +101,13 @@ export function findScrollAnchor(
 
   // Cold-open / pre-paint fallback — the single permitted DOM-origin
   // branch under `src/ui-tailwind/editor-surface/scroll-anchor.ts` per
-  // the Slice-3 plan.
+  // the Slice-3 plan. Warm path flows through `geometryFacet.getBlock`
+  // above; this fallback fires only before the first render frame.
+  // geometry:allow-dom-fallback
   const rootRect = root.getBoundingClientRect();
   const rootTop = rootRect.top;
   for (const block of blocks) {
+    // geometry:allow-dom-fallback
     const rect = block.getBoundingClientRect();
     if (rect.bottom < rootTop) continue;
     const blockId = block.getAttribute("data-block-id");
@@ -153,7 +156,11 @@ export function restoreScrollAnchor(
   const selector = `[data-block-id="${cssEscape(anchor.blockId)}"]`;
   const block = root.querySelector<HTMLElement>(selector);
   if (!block) return;
+  // Cold-open / pre-paint DOM fallback — same rationale as
+  // findScrollAnchor's fallback above.
+  // geometry:allow-dom-fallback
   const rootRect = root.getBoundingClientRect();
+  // geometry:allow-dom-fallback
   const blockRect = block.getBoundingClientRect();
   // We want, post-restore, `blockRect.top === rootRect.top - offsetWithinBlock`
   // (i.e. the block's leading edge sits `offsetWithinBlock` px above the

package/src/ui-tailwind/editor-surface/search-plugin.ts

@@ -15,17 +15,15 @@ import { Plugin, PluginKey } from "prosemirror-state";
 import type { EditorState, Transaction } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
 
-import type {
-  SearchOptions as PublicSearchOptions,
-} from "../../api/public-types";
 import {
+  type SearchOptions as PublicSearchOptions,
   buildSearchPattern,
   createSearchExcerpt,
   findSearchMatches,
   searchSecondaryStories,
   type SecondaryStorySearchResult,
   type SearchTextOptions,
-} from "../../core/search/search-text.ts";
+} from "../../api/public-types";
 
 // ---------------------------------------------------------------------------
 // Public types

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

@@ -159,6 +159,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)";

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";
 
 /**

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,7 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
           style={{ width: "100%", height: "100%" }}
         />
       ) : (
-        <TwRegionBlockRenderer blocks={blocks} />
+        <TwRegionBlockRenderer blocks={blocks} mediaPreviews={mediaPreviews} />
       )}
     </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,7 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
           style={{ width: "100%", height: "100%" }}
         />
       ) : (
-        <TwRegionBlockRenderer blocks={blocks} />
+        <TwRegionBlockRenderer blocks={blocks} mediaPreviews={mediaPreviews} />
       )}
     </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>
   );
 };

package/src/ui-tailwind/page-stack/tw-region-block-renderer.tsx

@@ -4,6 +4,7 @@ import type {
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
 } from "../../api/public-types.ts";
+import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import {
   buildMarkerStyle,
   buildParagraphStyle,
@@ -13,6 +14,8 @@ import {
   resolveHeadingLevel,
 } from "../editor-surface/tw-page-block-view.helpers.ts";
 
+const EMU_PER_PX = 9525;
+
 // ---------------------------------------------------------------------------
 // TwRegionBlockRenderer (P8.4)
 //
@@ -37,7 +40,10 @@ import {
 // Inline segment renderer — mirrors `tw-page-block-view`'s `renderSegment`.
 // ---------------------------------------------------------------------------
 
-function renderSegment(seg: SurfaceInlineSegment): React.ReactNode {
+function renderSegment(
+  seg: SurfaceInlineSegment,
+  mediaPreviews: Record<string, MediaPreviewDescriptor>,
+): React.ReactNode {
   switch (seg.kind) {
     case "text": {
       const style = buildSegmentStyle(seg.marks, seg.markAttrs);
@@ -63,11 +69,46 @@ function renderSegment(seg: SurfaceInlineSegment): React.ReactNode {
       );
     case "hard_break":
       return <br key={seg.segmentId} />;
-    case "image":
+    case "image": {
+      // Mirror body-renderer behavior (`pm-state-from-snapshot.ts` :500+):
+      // look up the preview via `seg.mediaId` and render a real <img> when
+      // available. Without a preview (or `state === "missing"`), fall back
+      // to the placeholder chip — a deliberate signal that the media part
+      // exists canonical-side but no bytes have been resolved yet.
+      const preview = mediaPreviews[seg.mediaId];
+      const widthEmu = preview?.widthEmu ?? seg.anchor?.extent.widthEmu;
+      const heightEmu = preview?.heightEmu ?? seg.anchor?.extent.heightEmu;
+      if (preview?.src && seg.state !== "missing") {
+        const widthPx = widthEmu
+          ? Math.max(8, Math.round(widthEmu / EMU_PER_PX))
+          : undefined;
+        const heightPx = heightEmu
+          ? Math.max(8, Math.round(heightEmu / EMU_PER_PX))
+          : undefined;
+        return (
+          <img
+            key={seg.segmentId}
+            src={preview.src}
+            alt={seg.altText ?? ""}
+            data-node-type="image"
+            data-media-id={seg.mediaId}
+            style={{
+              display: "inline-block",
+              verticalAlign: "middle",
+              ...(widthPx ? { width: `${widthPx}px` } : {}),
+              ...(heightPx ? { height: `${heightPx}px` } : {}),
+              maxWidth: "100%",
+              objectFit: "contain",
+            }}
+          />
+        );
+      }
       return (
         <span
           key={seg.segmentId}
           data-node-type="image"
+          data-media-id={seg.mediaId}
+          data-state={seg.state}
           style={{
             display: "inline-block",
             width: "48px",
@@ -80,6 +121,7 @@ function renderSegment(seg: SurfaceInlineSegment): React.ReactNode {
           title={seg.altText ?? "Image"}
         />
       );
+    }
     case "field_ref":
       return (
         <span
@@ -121,8 +163,10 @@ function renderSegment(seg: SurfaceInlineSegment): React.ReactNode {
 
 function RegionParagraph({
   block,
+  mediaPreviews,
 }: {
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>;
+  mediaPreviews: Record<string, MediaPreviewDescriptor>;
 }): React.ReactElement {
   const headingLevel = resolveHeadingLevel(block.styleId, block.outlineLevel);
   const classes: string[] = ["leading-relaxed"];
@@ -195,7 +239,7 @@ function RegionParagraph({
     <div {...attrs}>
       {prefixSpan}
       <span className="pm-paragraph-content">
-        {block.segments.map((seg) => renderSegment(seg))}
+        {block.segments.map((seg) => renderSegment(seg, mediaPreviews))}
       </span>
     </div>
   );
@@ -203,8 +247,10 @@ function RegionParagraph({
 
 function RegionTable({
   block,
+  mediaPreviews,
 }: {
   block: Extract<SurfaceBlockSnapshot, { kind: "table" }>;
+  mediaPreviews: Record<string, MediaPreviewDescriptor>;
 }): React.ReactElement {
   const tableStyle: React.CSSProperties = {
     borderCollapse: "collapse",
@@ -273,7 +319,11 @@ function RegionTable({
                   style={Object.keys(cellStyle).length > 0 ? cellStyle : undefined}
                 >
                   {cell.content.map((childBlock) => (
-                    <RegionBlockItem key={childBlock.blockId} block={childBlock} />
+                    <RegionBlockItem
+                      key={childBlock.blockId}
+                      block={childBlock}
+                      mediaPreviews={mediaPreviews}
+                    />
                   ))}
                 </td>
               );
@@ -311,14 +361,16 @@ function RegionOpaque({
 
 function RegionBlockItem({
   block,
+  mediaPreviews,
 }: {
   block: SurfaceBlockSnapshot;
+  mediaPreviews: Record<string, MediaPreviewDescriptor>;
 }): React.ReactElement | null {
   switch (block.kind) {
     case "paragraph":
-      return <RegionParagraph block={block} />;
+      return <RegionParagraph block={block} mediaPreviews={mediaPreviews} />;
     case "table":
-      return <RegionTable block={block} />;
+      return <RegionTable block={block} mediaPreviews={mediaPreviews} />;
     case "sdt_block":
       return (
         <section
@@ -328,7 +380,7 @@ function RegionBlockItem({
           style={{ margin: "8px 0" }}
         >
           {block.children.map((child) => (
-            <RegionBlockItem key={child.blockId} block={child} />
+            <RegionBlockItem key={child.blockId} block={child} mediaPreviews={mediaPreviews} />
           ))}
         </section>
       );
@@ -348,8 +400,19 @@ export interface TwRegionBlockRendererProps {
   blocks: readonly SurfaceBlockSnapshot[];
   /** Optional class name applied to the root wrapper. */
   className?: string;
+  /**
+   * Media preview catalog. Without it, any `kind: "image"` segment falls
+   * back to the 48×32 gray placeholder chip — the pre-existing behavior
+   * for the 7-of-8 CCEP docs whose headers carry a logo. Pass the same
+   * catalog the body renderer uses (`props.mediaPreviews` on the
+   * workspace root) to light up headers + footers + footnote bodies with
+   * real image bytes.
+   */
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
 }
 
+const EMPTY_MEDIA_PREVIEWS: Record<string, MediaPreviewDescriptor> = {};
+
 /**
  * TwRegionBlockRenderer — read-only React renderer for a region's
  * `SurfaceBlockSnapshot[]`.  Used by the header / footer / footnote /
@@ -363,9 +426,11 @@ export interface TwRegionBlockRendererProps {
 export function TwRegionBlockRenderer({
   blocks,
   className,
+  mediaPreviews,
 }: TwRegionBlockRendererProps): React.ReactElement {
   const rootClasses = ["ProseMirror"];
   if (className) rootClasses.push(className);
+  const previews = mediaPreviews ?? EMPTY_MEDIA_PREVIEWS;
   return (
     <div
       className={rootClasses.join(" ")}
@@ -373,7 +438,7 @@ export function TwRegionBlockRenderer({
       data-region-block-renderer=""
     >
       {blocks.map((block) => (
-        <RegionBlockItem key={block.blockId} block={block} />
+        <RegionBlockItem key={block.blockId} block={block} mediaPreviews={previews} />
       ))}
     </div>
   );

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

@@ -5,7 +5,7 @@ import type {
   CommentBody,
   CommentMention,
 } from "../../api/comment-presentation-types";
-import { sanitizeMarkdown } from "../../runtime/markdown-sanitizer";
+import { sanitizeMarkdown } from "../../api/public-types";
 
 export interface CommentMarkdownRendererProps {
   body: CommentBody;