@beyondwork/docx-react-component 1.0.70 → 1.0.72

package/src/session/export/embedded-reconstitute.ts

@@ -68,6 +68,34 @@ export async function reconstituteEmbeddedDocuments(
   }
 }
 
+/**
+ * SEC-IO-01 (2026-04-23): tamper-verified resolution.
+ *
+ * Two sources are consulted in order:
+ *   1. `hostAdapter.loadEmbeddedDocument(storageReference)` — verified against
+ *      `entry.sha256`. Mismatch falls through to inline bytes, treated as a
+ *      storage failure.
+ *   2. `entry.inlineBytes` base64 fallback — also verified against
+ *      `entry.sha256`. If the inline bytes have been tampered with (attacker-
+ *      modified customXml payload carrying altered bytes with the original
+ *      declared sha), this check fail-closes: export throws a specific error
+ *      rather than shipping attacker-chosen bytes into the OPC package.
+ *
+ * Before the fix, the inline-bytes path returned the decoded payload without
+ * verification — a crafted DOCX could inject attacker-controlled bytes into
+ * every exported package part whose host-adapter lookup happened to fail.
+ */
+class EmbeddedOffloadTamperError extends Error {
+  constructor(public readonly entry: { sourcePartPath: string; sha256: string }) {
+    super(
+      `Embedded offload entry '${entry.sourcePartPath}' failed sha256 integrity ` +
+        `check against inline-bytes fallback (expected sha256=${entry.sha256.slice(0, 16)}…). ` +
+        `Source customXml payload is tampered.`,
+    );
+    this.name = "EmbeddedOffloadTamperError";
+  }
+}
+
 async function resolveEntryBytes(
   hostAdapter: EditorHostAdapter | undefined,
   entry: EmbeddingOffloadEntry,
@@ -89,11 +117,17 @@ async function resolveEntryBytes(
       }
     } catch {
       // Treat identically to `null` — fall through to the inline-
-      // bytes fallback. The architecture guarantees export never
-      // fails on storage unavailability.
+      // bytes fallback.
     }
   }
-  return decodeInlineBytes(entry.inlineBytes);
+  // SEC-IO-01 verification on the inline fallback. Unlike storage
+  // unavailability (which is benign), sha mismatch here means the
+  // source customXml payload was tampered with. Fail closed.
+  const decoded = decodeInlineBytes(entry.inlineBytes);
+  if (sha256Hex(decoded) !== entry.sha256) {
+    throw new EmbeddedOffloadTamperError(entry);
+  }
+  return decoded;
 }
 
 /**

package/src/session/import/embedded-offload.ts

@@ -263,6 +263,31 @@ const EMPTY_RESULT: EmbeddedOffloadResult = Object.freeze({
 // (Buffer) and browser (btoa/atob) contexts. Direct call; the earlier
 // local `encodeBase64` alias was unnecessary indirection.
 
+/**
+ * SEC-IO-02 (2026-04-23): allowlist check for offload sourcePartPath.
+ *
+ * Offload entries come from customXml — untrusted content. The export-time
+ * `reconstituteEmbeddedDocuments` writes to `entry.sourcePartPath` via
+ * `exportSession.replaceOwnedPart`, which accepts arbitrary OPC paths. A
+ * malicious `sourcePartPath` could overwrite `/[Content_Types].xml`,
+ * `/_rels/.rels`, `/word/document.xml`, or any other sensitive part of the
+ * exported package.
+ *
+ * The offload feature covers EMBEDDED documents only — sub-documents Word
+ * stores under `/word/embeddings/embedded{N}.bin` (OLE) or similar. Narrow
+ * the allowlist to that canonical prefix. Entries with any other path,
+ * any traversal segment, or any control char silently drop.
+ */
+const SAFE_EMBEDDING_PATH = /^\/word\/embeddings\/[A-Za-z0-9_.-]+$/;
+
+function isSafeSourcePartPath(path: unknown): path is string {
+  if (typeof path !== "string") return false;
+  if (path.length === 0 || path.length > 256) return false;
+  if (path.includes("..")) return false;
+  if (path.includes("\0") || path.includes("\n") || path.includes("\r")) return false;
+  return SAFE_EMBEDDING_PATH.test(path);
+}
+
 function parseEmbeddingsInline(
   inline: unknown,
 ): EmbeddingOffloadEntry[] | undefined {
@@ -293,7 +318,7 @@ function parseEmbeddingsInline(
     if (
       typeof r.embeddedDocId !== "string" ||
       typeof r.relationshipId !== "string" ||
-      typeof r.sourcePartPath !== "string" ||
+      !isSafeSourcePartPath(r.sourcePartPath) ||
       typeof r.contentType !== "string" ||
       typeof r.sha256 !== "string" ||
       typeof r.inlineBytes !== "string" ||

package/src/shell/media-previews.ts

@@ -6,11 +6,13 @@
  * digest, walks the OPC parts table, and projects each canonical media
  * item into a `MediaPreviewDescriptor`.
  *
- * SVG is included in the browser-safe content-type allowlist — Chromium
- * sandboxes SVGs loaded via `<img src="data:image/svg+xml;base64,…">`
- * (no script execution, no external refs), so XSS surface matches PNG.
- * Required for CCEP-synthesized chart previews (Stage 0B) and hosts
- * that ship `.svg` inside `word/media/`.
+ * SVG is EXCLUDED from the content-type allowlist (SEC-UI-03, 2026-04-23).
+ * While Chromium's `<img src="data:image/svg+xml;base64,…">` path does block
+ * script execution on modern browsers, user-authored SVGs in DOCX `word/media/`
+ * can still leak user presence via `<image xlink:href="http://...">` trackers
+ * and have historically had CSP-bypass gaps. Chart-preview SVGs (Stage 0B)
+ * come from our own renderer via `chart-preview-resolver.ts`, not from
+ * `word/media/*`, so dropping SVG here does not regress charts.
  *
  * Lives in `src/shell/` so the three `io/**` substrate imports stay
  * outside the L11 boundary register — package decoding is a shell
@@ -33,7 +35,7 @@ const BROWSER_SAFE_PREVIEW_TYPES = new Set([
   "image/gif",
   "image/webp",
   "image/bmp",
-  "image/svg+xml",
+  // SVG intentionally EXCLUDED — see SEC-UI-03 header comment.
 ]);
 
 export function buildMediaPreviews(

package/src/ui/WordReviewEditor.tsx

@@ -3321,6 +3321,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         pasteFragmentParser={SHELL_PASTE_FRAGMENT_PARSER}
         runtimeSearchDocument={api.runtime.search.searchDocument}
         runtimeGetTableSelectionDescriptor={api.runtime.table.getSelectionDescriptor}
+        scopeTagRegistryFactory={api.runtime.workflow.createScopeTagRegistry}
         snapshot={snapshot}
         canonicalDocument={canonicalDocument}
         documentNavigation={documentNavigation}

package/src/ui/editor-surface-controller.tsx

@@ -84,6 +84,17 @@ export interface EditorSurfaceControllerProps {
   runtimeGetTableSelectionDescriptor?: (
     state: import("prosemirror-state").EditorState,
   ) => TableSelectionDescriptor | null;
+  /**
+   * Coord-10 L11-4 — forwarded to `TwProseMirrorSurface`. Threaded
+   * from `api.runtime.workflow.createScopeTagRegistry` (shipped by
+   * L06 in react-refactor `534f2b97`). Replaces the pre-L06-catalog
+   * pragmatic public-types re-export (refactor/11 §4.17, 2026-04-24
+   * `7a2d2fc0`). When absent, `TwProseMirrorSurface` falls back to
+   * the public-types re-export for test / headless mount back-compat.
+   */
+  scopeTagRegistryFactory?: () => import(
+    "../api/public-types.ts"
+  ).ScopeTagRegistry;
   onPasteApplied?: (meta: {
     segmentCount: number;
     charCount: number;

package/src/ui/headless/selection-helpers.ts

@@ -1,8 +1,8 @@
-import type { SelectionSnapshot } from "../../api/public-types";
 import {
+  type SelectionSnapshot,
   createPublicNodeAnchor,
   createPublicRangeAnchor,
-} from "../../core/selection/anchor-conversion.ts";
+} from "../../api/public-types";
 
 /**
  * Headless-UI-side `createSelectionSnapshot` that produces the **public**

package/src/ui/runtime-shortcut-dispatch.ts

@@ -1,8 +1,8 @@
-import type {
-  StyleCatalogSnapshot,
-  WorkflowBlockedCommandReason,
+import {
+  CAPABILITY_BY_ID,
+  type StyleCatalogSnapshot,
+  type WorkflowBlockedCommandReason,
 } from "../api/public-types.ts";
-import { CAPABILITY_BY_ID } from "../runtime/editor-surface/capabilities.ts";
 
 export interface ShortcutKeyInput {
   key: string;

package/src/ui-tailwind/chrome/tw-runtime-repl-dialog.tsx

@@ -6,10 +6,28 @@ import React, {
 } from "react";
 
 import type { WordReviewEditorRef } from "../../api/public-types";
-import type { DocumentRuntime } from "../../runtime/document-runtime";
+
+/**
+ * Opaque runtime handle for the REPL. The REPL hands the value to
+ * `new Function("runtime", ...)` for user-supplied JS evaluation and
+ * does not introspect its shape — so the dialog's prop type is
+ * deliberately structurally loose (`object | null`) rather than the
+ * non-public `DocumentRuntime`.
+ *
+ * Callers inside the component tree that actually hold a
+ * `DocumentRuntime` / `RuntimeApiHandle` / `ApiV3` can pass it here
+ * unchanged; the widening only affects compile-time autocomplete for
+ * the REPL's internal use, not the live eval target.
+ *
+ * Retired handoff §4.8 residual: the previous `DocumentRuntime`
+ * prop type was the last direct import of the non-public runtime
+ * class name in `src/ui-tailwind/**` per refactor/11 handoff §4.8
+ * remainder row.
+ */
+export type TwRuntimeReplTarget = object;
 
 export interface TwRuntimeReplDialogProps {
-  runtime: DocumentRuntime | null;
+  runtime: TwRuntimeReplTarget | null;
   /**
    * Optional editor ref. When provided, the REPL exposes it to evaluated
    * expressions as `ref` — e.g. `ref.getRenderSnapshot()`. The REPL reads
@@ -370,11 +388,11 @@ export function isReplToggleShortcut(event: KeyboardEvent): boolean {
 
 export async function evaluateReplExpression(
   code: string,
-  runtime: DocumentRuntime,
+  runtime: TwRuntimeReplTarget,
   ref: WordReviewEditorRef | null = null,
 ): Promise<unknown> {
   type ReplFn = (
-    runtime: DocumentRuntime,
+    runtime: TwRuntimeReplTarget,
     ref: WordReviewEditorRef | null,
   ) => Promise<unknown>;
   let fn: ReplFn | null = null;

package/src/ui-tailwind/chrome/tw-table-context-toolbar.tsx

@@ -214,17 +214,17 @@ export function TwTableContextToolbar(props: TwTableContextToolbarProps) {
               capability={tableContext?.operations.setTableAlignment}
               disabled={props.disabled}
               onClick={() => props.onSetTableAlignment?.(align)}
-              // Chrome Closure Pass · Task 3 — pre-fix bug:
-              // `active` was hardcoded to `align === "left"`, lighting
-              // up the Left button regardless of the actual table
-              // alignment. `TableStructureContextSnapshot` does not
-              // currently surface table-level alignment (the field
-              // lives on `RuntimeTableRenderPlanSnapshot`); until the
-              // runtime exposes it on the structure context, treat
-              // alignment buttons as plain action buttons (no toggle).
-              // Fix scope: presentation-only correction; runtime
-              // enrichment is a follow-up issue against L07.
-              active={false}
+              // Refactor/11 handoff §4.13 — L07 shipped
+              // `TableStructureContextSnapshot.alignment` in
+              // `4cfe52a3` (2026-04-24), landing alignment on the
+              // structure context alongside the existing
+              // `PublicTableSummary.alignment`. Toggle the active
+              // state against the live value. `null` means no
+              // explicit alignment declared (parent default, typically
+              // left) — all three buttons remain inactive in that
+              // case; setting any alignment via the callback produces
+              // a subsequent snapshot with a non-null value.
+              active={tableContext?.alignment === align}
             >
               {align[0]!.toUpperCase()}
             </ToolbarButton>

package/src/ui-tailwind/chrome/tw-table-grip-layer.tsx

@@ -28,9 +28,9 @@ import type {
   WordReviewEditorLayoutFacet,
 } from "../../api/public-types";
 import type { GeometryFacet } from "../../api/public-types";
+import { DEFAULT_PX_PER_TWIP } from "../../api/public-types";
 import type { OverlayCoordinateSpace } from "../chrome-overlay/chrome-overlay-projector";
 import { projectRectToOverlay } from "../chrome-overlay/chrome-overlay-projector";
-import { DEFAULT_PX_PER_TWIP } from "../../runtime/render/render-frame-types";
 import { forwardNonDragClick } from "./forward-non-drag-click";
 
 const GRIP_PX = 2;

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -183,6 +183,9 @@ export interface TwChromeOverlayProps {
    * See `useVisiblePageIndexRange` in `src/ui-tailwind/page-stack/use-visible-block-range.ts`.
    */
   visiblePageIndexRange?: { start: number; end: number } | null;
+  /** Preview catalog threaded into the page-stack chrome so header /
+   *  footer / footnote / endnote regions render real <img>s. */
+  mediaPreviews?: Record<string, import("../editor-surface/pm-state-from-snapshot").MediaPreviewDescriptor>;
 }
 
 /**
@@ -226,6 +229,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   pmSurfaceElement,
   pmView,
   visiblePageIndexRange,
+  mediaPreviews,
 }) => {
   return (
     <div
@@ -243,6 +247,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
           pmSurfaceElement={pmSurfaceElement}
           pmView={pmView}
           visiblePageIndexRange={visiblePageIndexRange ?? null}
+          mediaPreviews={mediaPreviews}
         />
       ) : null}
       <TwScopeRailLayer

package/src/ui-tailwind/chrome-overlay/tw-comment-balloon-layer.tsx

@@ -1,6 +1,10 @@
 import * as React from "react";
 import type { RenderBlockDecoration } from "../../api/public-types.ts";
 import { TwCommentPreview } from "../chrome/tw-comment-preview";
+import {
+  projectRectToOverlay,
+  type OverlayCoordinateSpace,
+} from "./chrome-overlay-projector.ts";
 
 const WIDE_BREAKPOINT_PX = 1024;
 const CONNECTOR_GAP_PX = 16;
@@ -24,14 +28,26 @@ export interface TwCommentBalloonLayerProps {
   viewportWidthPx: number;
   /** Right edge of the page frame in overlay coordinates (px). */
   pageRightEdgePx: number;
+  /**
+   * Overlay coordinate space — subtracted from each decoration rect so
+   * balloon `top` is relative to the overlay's own top-left, not the
+   * document column. Matches `TwScopeCardLayer` / `TwTableGripLayer`
+   * precedent. Defaults to the zero-origin space so existing callers
+   * that mount the layer at the document column's origin continue to
+   * work unchanged.
+   */
+  space?: OverlayCoordinateSpace;
   onOpenThread?: (commentId: string) => void;
 }
 
+const ZERO_SPACE: OverlayCoordinateSpace = { originLeftPx: 0, originTopPx: 0 };
+
 export const TwCommentBalloonLayer = React.memo(function TwCommentBalloonLayer({
   commentDecorations,
   commentDataById,
   viewportWidthPx,
   pageRightEdgePx,
+  space = ZERO_SPACE,
   onOpenThread,
 }: TwCommentBalloonLayerProps) {
   if (viewportWidthPx < WIDE_BREAKPOINT_PX) return null;
@@ -42,12 +58,13 @@ export const TwCommentBalloonLayer = React.memo(function TwCommentBalloonLayer({
       {commentDecorations.map((dec) => {
         const data = commentDataById.get(dec.refId);
         if (!data) return null;
+        const projected = projectRectToOverlay(dec.frame, space);
         return (
           <div
             key={dec.refId}
             style={{
               position: "absolute",
-              top: dec.frame.topPx,
+              top: projected.top,
               left: pageRightEdgePx + CONNECTOR_GAP_PX,
               width: BALLOON_MAX_WIDTH_PX,
               pointerEvents: "auto",

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

@@ -176,6 +176,7 @@ export function resolvePageOverlayRects(
     if (!scrollRoot || count <= 0) return [];
     widgets = measureWidgetsViaOffsetChain(scrollRoot);
     pageCount = count;
+    // geometry:allow-dom-fallback
     scrollHeight = scrollRoot.clientHeight;
   } else if (
     input !== null &&
@@ -195,6 +196,7 @@ export function resolvePageOverlayRects(
     if (legacyPageCount <= 0) return [];
     widgets = measureWidgetsViaOffsetChain(scrollRoot);
     pageCount = legacyPageCount;
+    // geometry:allow-dom-fallback
     scrollHeight = scrollRoot.clientHeight;
   } else {
     return [];
@@ -275,6 +277,10 @@ export function measureWidgetsViaBoundingRect(
   },
 ): PageBoundaryMeasurement[] {
   if (!queryRoot || !originElement) return [];
+  // Cold-open / pre-paint DOM fallback — warm path flows through
+  // `geometryFacet.getPage(i)` at the caller; this branch fires only
+  // before the first render frame.
+  // geometry:allow-dom-fallback
   const originRect = originElement.getBoundingClientRect();
   const normalizedVisiblePageIndexRange = normalizeVisiblePageIndexRange(
     options?.visiblePageIndexRange,
@@ -301,6 +307,7 @@ export function measureWidgetsViaBoundingRect(
     const prevPageId = widget.getAttribute("data-page-frame-end");
     const nextPageId = widget.getAttribute("data-page-frame-start");
     if (!prevPageId || !nextPageId) continue;
+    // geometry:allow-dom-fallback
     const rect = widget.getBoundingClientRect();
     out.push({
       prevPageId,
@@ -380,10 +387,14 @@ function resolveOffsetTop(
   // still defined and defaults to 0.  Browsers set it relative to the
   // offsetParent.  We walk up the offset chain until we reach the scroll
   // root (or exit the document) so the result is scroll-root-relative.
+  // Cold-open / pre-paint DOM fallback — warm path flows through
+  // `geometryFacet.getPage(i)` at the caller.
   let node: HTMLElement | null = widget;
   let top = 0;
   while (node) {
+    // geometry:allow-dom-fallback
     top += node.offsetTop ?? 0;
+    // geometry:allow-dom-fallback
     const parent = node.offsetParent as HTMLElement | null;
     if (parent === scrollRoot || parent === null) break;
     node = parent;
@@ -392,6 +403,7 @@ function resolveOffsetTop(
 }
 
 function resolveOffsetHeight(widget: HTMLElement): number {
+  // geometry:allow-dom-fallback
   return widget.offsetHeight ?? 0;
 }
 
@@ -437,12 +449,10 @@ export interface TwPageStackOverlayLayerProps {
  * owns the projection math; the overlay component re-exports from this
  * module for back-compat with existing imports.
  *
- * Known coordinate-space caveat documented in
- * `src/runtime/geometry/overlay-rects.ts` — the kernel's page-stacking
- * gap (16 px) diverges from the DOM chrome's inter-page gap (48 px).
- * Until Slice 3c reconciles them, production consumers should not pass
- * a `geometryFacet` to this overlay — the DOM-measurement path remains
- * the default.
+ * **Slice 3c reconciliation shipped 2026-04-23** — kernel `PAGE_GAP_PX`
+ * (16 → 48) now matches the DOM chrome's `interGapPx`, so `geometryFacet`
+ * is the production warm path. The DOM-measurement branch below stays as
+ * the cold-open fallback only.
  */
 export const resolvePageOverlayRectsFromGeometry =
   resolvePageOverlayRectsFromGeometryImpl;
@@ -628,17 +638,22 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       }
     }
 
+    // Cold-open / pre-paint DOM fallback — warm path early-returned
+    // above via `geometryFacet` or the UI-API resolver. Lines below
+    // fire only before the first render frame.
     if (origin) {
       const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
         pageCount,
         visiblePageIndexRange,
       });
+      // geometry:allow-dom-fallback
       const originRect = origin.getBoundingClientRect();
       setRects(
         resolvePageOverlayRects({
           widgets,
           pageCount,
           scrollHeight:
+            // geometry:allow-dom-fallback
             origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
           visiblePageIndexRange,
         }),
@@ -652,6 +667,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
         resolvePageOverlayRects({
           widgets,
           pageCount,
+          // geometry:allow-dom-fallback
           scrollHeight: scrollRoot.clientHeight,
           visiblePageIndexRange,
         }),

package/src/ui-tailwind/chrome-overlay/tw-revision-margin-bar-layer.tsx

@@ -1,6 +1,10 @@
 import * as React from "react";
 import type { RenderBlockDecoration } from "../../api/public-types.ts";
 import { AUTHOR_PALETTE } from "../../ui/headless/revision-decoration-model";
+import {
+  projectRectToOverlay,
+  type OverlayCoordinateSpace,
+} from "./chrome-overlay-projector.ts";
 
 const BAR_WIDTH_PX = 3;
 const BAR_LEFT_OFFSET_PX = 8;
@@ -15,12 +19,24 @@ export interface TwRevisionMarginBarLayerProps {
   authorPaletteIndexById: ReadonlyMap<string, number>;
   /** Left edge of the page body in overlay coordinates (px). */
   pageBodyLeftPx: number;
+  /**
+   * Overlay coordinate space — subtracted from each decoration rect so
+   * bar `top` is relative to the overlay's own top-left, not the
+   * document column. Matches `TwScopeCardLayer` / `TwTableGripLayer`
+   * precedent. Defaults to the zero-origin space so existing callers
+   * that mount the layer at the document column's origin continue to
+   * work unchanged.
+   */
+  space?: OverlayCoordinateSpace;
 }
 
+const ZERO_SPACE: OverlayCoordinateSpace = { originLeftPx: 0, originTopPx: 0 };
+
 export const TwRevisionMarginBarLayer = React.memo(function TwRevisionMarginBarLayer({
   revisionDecorations,
   authorPaletteIndexById,
   pageBodyLeftPx,
+  space = ZERO_SPACE,
 }: TwRevisionMarginBarLayerProps) {
   if (revisionDecorations.length === 0) return null;
 
@@ -29,13 +45,14 @@ export const TwRevisionMarginBarLayer = React.memo(function TwRevisionMarginBarL
       {revisionDecorations.map((dec, idx) => {
         const paletteIdx = authorPaletteIndexById.get(dec.refId) ?? 0;
         const color = AUTHOR_PALETTE[paletteIdx % AUTHOR_PALETTE.length];
+        const projected = projectRectToOverlay(dec.frame, space);
         return (
           <div
             key={`rev-bar-${dec.refId}-${idx}`}
             aria-hidden
             style={{
               position: "absolute",
-              top: dec.frame.topPx,
+              top: projected.top,
               left: pageBodyLeftPx - BAR_LEFT_OFFSET_PX - BAR_WIDTH_PX,
               width: BAR_WIDTH_PX,
               height: dec.frame.heightPx,

package/src/ui-tailwind/editor-surface/pm-page-break-decorations.ts

@@ -24,8 +24,10 @@
  */
 
 import { Decoration } from "prosemirror-view";
-import type { RuntimePageGraph } from "../../api/public-types.ts";
-import { resolvePageFieldDisplayText } from "../../runtime/layout/resolve-page-fields.ts";
+import {
+  type RuntimePageGraph,
+  resolvePageFieldDisplayText,
+} from "../../api/public-types.ts";
 
 export const PAGE_CHROME_DEFAULTS = {
   headerBandPx: 32,
@@ -93,7 +95,7 @@ export function buildPageBreakDecorations(
   input: PageBreakDecorationInput,
 ): Decoration[] {
   const { graph, posture, runtimeToPmOffset } = input;
-  if (!graph || graph.pages.length < 2) return [];
+  if (!graph) return [];
 
   const headerBandPx =
     input.headerBandPx ?? PAGE_CHROME_DEFAULTS.headerBandPx;
@@ -103,6 +105,15 @@ export function buildPageBreakDecorations(
 
   const decorations: Decoration[] = [];
 
+  // Inter-page boundary widgets (existing) — emitted first so
+  // `decorations[0..N-2]` remain boundary widgets for any legacy
+  // callers that index by position. Per-page content-anchor widgets
+  // (coord-11 §19) are emitted in a second pass at the end of this
+  // function.
+  if (graph.pages.length < 2) {
+    return buildPageAnchorDecorationsInto(decorations, graph, posture, runtimeToPmOffset);
+  }
+
   for (let i = 1; i < graph.pages.length; i += 1) {
     const prev = graph.pages[i - 1]!;
     const next = graph.pages[i]!;
@@ -160,6 +171,58 @@ export function buildPageBreakDecorations(
       ),
     );
   }
+  return buildPageAnchorDecorationsInto(decorations, graph, posture, runtimeToPmOffset);
+}
+
+/**
+ * Append per-page content-anchor widgets to `decorations` for coord-11
+ * §19. One zero-height anchor per non-filler page at the page's content-
+ * start offset. Chrome-preset-independent (PM widget = content layer) +
+ * markup-mode stable (document-offset-anchored, not chrome-dependent).
+ *
+ * Each anchor carries `data-page-content-wrapper` + `data-page-number`
+ * (1-based, skipping blank fillers) + `data-page-id` (from
+ * `RuntimePageNode.pageId` — stable across chrome/markup transitions).
+ * Consumed by `runtime.viewport.getPageAnchor(n)` (coord-07 §2.9) and
+ * `ui.viewport.scrollToPage(n)` (coord-10 §γ); also by the visual-
+ * fidelity harness at `test/visual-fidelity/` per coord-11 §20.
+ *
+ * Anchors use `side: 1` so they sit AFTER the document position
+ * (inside page N's content). Boundary widgets use `side: -1` so they
+ * sit BEFORE the same offset (at the end of page N-1's content + gap).
+ * Ordering places each anchor at the top of its page's content area.
+ */
+function buildPageAnchorDecorationsInto(
+  decorations: Decoration[],
+  graph: RuntimePageGraph,
+  posture: "page" | "canvas",
+  runtimeToPmOffset: ((runtimeOffset: number) => number | null) | undefined,
+): Decoration[] {
+  let contentPageOrdinal = 0;
+  for (const page of graph.pages) {
+    if (page.isBlankFiller) continue;
+    contentPageOrdinal += 1;
+    const pagePmOffset = runtimeToPmOffset
+      ? runtimeToPmOffset(page.startOffset)
+      : page.startOffset;
+    if (pagePmOffset === null || pagePmOffset === undefined) continue;
+    const anchorPageNumber = contentPageOrdinal;
+    const anchorPageId = page.pageId;
+    decorations.push(
+      Decoration.widget(
+        pagePmOffset,
+        () => buildPageAnchorWidgetDom({
+          pageNumber: anchorPageNumber,
+          pageId: anchorPageId,
+        }),
+        {
+          side: 1,
+          key: `pa-${page.pageId}-${posture}`,
+          ignoreSelection: true,
+        },
+      ),
+    );
+  }
   return decorations;
 }
 
@@ -262,6 +325,38 @@ export function __resetPageBreakWidgetCache(): void {
   widgetDomCache.clear();
 }
 
+/**
+ * Build the per-page content-anchor widget DOM for coord-11 §19.
+ *
+ * Zero-height, non-visual marker carrying `data-page-content-wrapper`,
+ * `data-page-number` (1-based), and `data-page-id` (stable across
+ * chrome preset + markup mode transitions — sourced from
+ * `RuntimePageNode.pageId`). Consumed by `runtime.viewport.getPageAnchor(n)`
+ * (coord-07 §2.9) + `ui.viewport.scrollToPage(n)` (coord-10 §γ) and by
+ * the visual-fidelity harness.
+ *
+ * Emitted as a PM widget via `buildPageBreakDecorations` so it lives
+ * on the content layer (present under chrome=none) rather than on an
+ * absolute-positioned chrome overlay.
+ */
+function buildPageAnchorWidgetDom(input: {
+  pageNumber: number;
+  pageId: string;
+}): HTMLElement {
+  const root = document.createElement("span");
+  root.setAttribute("data-kind", "page-content-anchor");
+  root.setAttribute("data-page-content-wrapper", "");
+  root.setAttribute("data-page-number", String(input.pageNumber));
+  root.setAttribute("data-page-id", input.pageId);
+  root.setAttribute("aria-hidden", "true");
+  root.contentEditable = "false";
+  root.style.display = "block";
+  root.style.height = "0";
+  root.style.width = "100%";
+  root.style.userSelect = "none";
+  return root;
+}
+
 function buildChromeWidgetDomUncached(input: ChromeWidgetInput): HTMLElement {
   const root = document.createElement("div");
   root.className = "wre-page-chrome-widget";