@beyondwork/docx-react-component 1.0.103 → 1.0.105

package/src/runtime/layout/page-graph.ts

@@ -21,6 +21,17 @@ import type {
   EditorStoryTarget,
   PageLayoutSnapshot,
 } from "../../api/public-types";
+import type {
+  BlockNode,
+  FooterDocument,
+  HeaderDocument,
+  InlineNode,
+  PreserveOnlyObjectSizing,
+} from "../../model/canonical-document.ts";
+import {
+  formatPageNumber,
+  formatPageNumberWithChapter,
+} from "../formatting/field/page-number-format.ts";
 import type {
   ResolvedPageStories,
 } from "./page-story-resolver.ts";
@@ -48,6 +59,19 @@ import type { ResolvedDocumentSection } from "../document-layout.ts";
 export type {
   RuntimePageRegions,
   RuntimePageRegion,
+  RuntimeTwipsRect,
+  RuntimeResolvedRegions,
+  RuntimeExclusionZone,
+  RuntimeLayoutDivergenceKind,
+  RuntimeLayoutDivergence,
+  RuntimePageFrame,
+  RuntimePageLocalStoryInstance,
+  RuntimeResolvedStoryField,
+  RuntimeStoryAnchoredObject,
+  RuntimeLayoutContinuationCursor,
+  RuntimeParagraphContinuationCursor,
+  RuntimeTableContinuationCursor,
+  RuntimeTableVerticalMergeCarry,
   RuntimeBlockFragment,
   RuntimeLineBox,
   RuntimeNoteAllocation,
@@ -62,11 +86,17 @@ export type {
 
 import type {
   RuntimeBlockFragment,
+  RuntimeLayoutDivergence,
   RuntimeLineBox,
   RuntimeNoteAllocation,
   RuntimePageAnchor,
+  RuntimePageFrame,
+  RuntimePageLocalStoryInstance,
   RuntimePageRegion,
   RuntimePageRegions,
+  RuntimeResolvedRegions,
+  RuntimeStoryAnchoredObject,
+  RuntimeTwipsRect,
 } from "../../model/layout/page-graph-types.ts";
 import type {
   RuntimePageGraph,
@@ -80,6 +110,19 @@ import type {
 
 let graphRevision = 0;
 
+const PAGE_INSTANCE_FIELD_FAMILIES = new Set([
+  "PAGE",
+  "NUMPAGES",
+  "SECTIONPAGES",
+]);
+
+const EMUS_PER_TWIP = 635;
+
+type HeaderFooterStoryTarget = Extract<
+  EditorStoryTarget,
+  { kind: "header" | "footer" }
+>;
+
 export function buildPageGraph(input: BuildPageGraphInput): RuntimePageGraph;
 export function buildPageGraph(
   pages: readonly DocumentPageSnapshot[],
@@ -104,6 +147,7 @@ export function buildPageGraph(
   const pages: RuntimePageNode[] = [];
   const aggregatedFragments: RuntimeBlockFragment[] = [...(input.fragments ?? [])];
   const pageIdByGlobalPageIndex = new Map<number, string>();
+  const pageFieldCounts = buildPageFieldCounts(input.pages);
   for (let index = 0; index < input.pages.length; index += 1) {
     const page = input.pages[index]!;
     pageIdByGlobalPageIndex.set(page.pageIndex, `page-${graphRevision}-${index}`);
@@ -164,6 +208,29 @@ export function buildPageGraph(
       input.noteAllocations?.get(pageId) ??
       [];
 
+    const frameId = buildPageFrameId(
+      page.pageIndex,
+      page.sectionIndex,
+      stories.displayPageNumber,
+    );
+    const regions = buildRegions(page.layout, bodyPageFragments, stories, pageNoteAllocations);
+    const frameDivergences = detectFrameDivergences(frameId, regions);
+    const builtFrame = buildPageFrame({
+      frameId,
+      pageId,
+      pageIndex: page.pageIndex,
+      sectionIndex: page.sectionIndex,
+      displayPageNumber: stories.displayPageNumber,
+      layout: page.layout,
+      stories,
+      regions,
+      divergences: frameDivergences,
+      subParts: input.subParts,
+      pageFieldCounts,
+    });
+    const divergences = builtFrame.divergences;
+    const frame = builtFrame.frame;
+
     const node: RuntimePageNode = {
       pageId,
       pageIndex: page.pageIndex,
@@ -173,7 +240,9 @@ export function buildPageGraph(
       endOffset: page.endOffset,
       layout: page.layout,
       stories,
-      regions: buildRegions(page.layout, bodyPageFragments, stories, pageNoteAllocations),
+      regions,
+      frame,
+      divergences,
       lineBoxes:
         input.lineBoxesByPageIndex?.get(page.pageIndex) ??
         input.lineBoxesByPageIndex?.get(index) ??
@@ -240,6 +309,12 @@ function buildRegions(
         originTwips: layout.pageHeight - layout.marginBottom - totalNoteHeight,
         widthTwips: Math.max(0, bodyWidth),
         heightTwips: Math.max(0, totalNoteHeight),
+        rectTwips: rect(
+          layout.marginLeft,
+          layout.pageHeight - layout.marginBottom - totalNoteHeight,
+          Math.max(0, bodyWidth),
+          Math.max(0, totalNoteHeight),
+        ),
         fragmentIds,
       };
       bodyHeight = Math.max(0, bodyHeight - totalNoteHeight);
@@ -251,6 +326,7 @@ function buildRegions(
     originTwips: layout.marginTop,
     widthTwips: Math.max(0, bodyWidth),
     heightTwips: Math.max(0, bodyHeight),
+    rectTwips: rect(layout.marginLeft, layout.marginTop, Math.max(0, bodyWidth), Math.max(0, bodyHeight)),
     fragmentIds: [...bodyFragmentIds],
   };
 
@@ -262,6 +338,12 @@ function buildRegions(
       originTwips: layout.headerMargin ?? 720,
       widthTwips: Math.max(0, bodyWidth),
       heightTwips: Math.max(0, layout.marginTop - (layout.headerMargin ?? 720)),
+      rectTwips: rect(
+        layout.marginLeft,
+        layout.headerMargin ?? 720,
+        Math.max(0, bodyWidth),
+        Math.max(0, layout.marginTop - (layout.headerMargin ?? 720)),
+      ),
       fragmentIds: [],
     };
   }
@@ -271,6 +353,12 @@ function buildRegions(
       originTwips: layout.pageHeight - layout.marginBottom,
       widthTwips: Math.max(0, bodyWidth),
       heightTwips: Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720)),
+      rectTwips: rect(
+        layout.marginLeft,
+        layout.pageHeight - layout.marginBottom,
+        Math.max(0, bodyWidth),
+        Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720)),
+      ),
       fragmentIds: [],
     };
   }
@@ -299,6 +387,12 @@ function buildRegions(
         originTwips: layout.marginTop,
         widthTwips: perColumnWidth,
         heightTwips: Math.max(0, bodyHeight),
+        rectTwips: rect(
+          layout.marginLeft + i * (perColumnWidth + gap),
+          layout.marginTop,
+          perColumnWidth,
+          Math.max(0, bodyHeight),
+        ),
         fragmentIds: perColumnIds[i]!,
       });
     }
@@ -312,6 +406,715 @@ function buildRegions(
   return regions;
 }
 
+function rect(
+  xTwips: number,
+  yTwips: number,
+  widthTwips: number,
+  heightTwips: number,
+): RuntimeTwipsRect {
+  return { xTwips, yTwips, widthTwips, heightTwips };
+}
+
+function buildPageFrame(input: {
+  frameId: string;
+  pageId: string;
+  pageIndex: number;
+  sectionIndex: number;
+  displayPageNumber: number;
+  layout: PageLayoutSnapshot;
+  stories: ResolvedPageStories;
+  regions: RuntimePageRegions;
+  divergences: readonly RuntimeLayoutDivergence[];
+  subParts?: BuildPageGraphInput["subParts"];
+  pageFieldCounts: PageFieldCounts;
+}): { frame: RuntimePageFrame; divergences: RuntimeLayoutDivergence[] } {
+  const regions: RuntimeResolvedRegions = {
+    body: input.regions.body,
+    exclusionZones: [],
+    ...(input.regions.header ? { header: input.regions.header } : {}),
+    ...(input.regions.footer ? { footer: input.regions.footer } : {}),
+    ...(input.regions.columns ? { columns: input.regions.columns } : {}),
+    ...(input.regions.footnotes ? { footnotes: input.regions.footnotes } : {}),
+  };
+  const pageLocalStoryResult = buildPageLocalStoryInstances({
+    frameId: input.frameId,
+    pageId: input.pageId,
+    pageIndex: input.pageIndex,
+    sectionIndex: input.sectionIndex,
+    displayPageNumber: input.displayPageNumber,
+    layout: input.layout,
+    stories: input.stories,
+    regions,
+    subParts: input.subParts,
+    pageFieldCounts: input.pageFieldCounts,
+  });
+  const divergences = [...input.divergences, ...pageLocalStoryResult.divergences];
+  const pageLocalStories = pageLocalStoryResult.instances;
+  const divergenceIds = divergences.map((d) => d.divergenceId);
+  return {
+    frame: {
+      frameId: input.frameId,
+      pageId: input.pageId,
+      pageIndex: input.pageIndex,
+      sectionIndex: input.sectionIndex,
+      displayPageNumber: input.displayPageNumber,
+      physicalBoundsTwips: rect(0, 0, input.layout.pageWidth, input.layout.pageHeight),
+      regions,
+      pageLocalStories,
+      divergenceIds,
+      signature: buildPageFrameSignature(input, pageLocalStories, divergenceIds),
+    },
+    divergences,
+  };
+}
+
+function buildPageLocalStoryInstances(input: {
+  frameId: string;
+  pageId: string;
+  pageIndex: number;
+  sectionIndex: number;
+  displayPageNumber: number;
+  layout: PageLayoutSnapshot;
+  stories: ResolvedPageStories;
+  regions: RuntimeResolvedRegions;
+  subParts?: BuildPageGraphInput["subParts"];
+  pageFieldCounts: PageFieldCounts;
+}): {
+  instances: RuntimePageLocalStoryInstance[];
+  divergences: RuntimeLayoutDivergence[];
+} {
+  const instances: RuntimePageLocalStoryInstance[] = [];
+  const divergences: RuntimeLayoutDivergence[] = [];
+  if (isHeaderFooterStoryTarget(input.stories.header)) {
+    const built = buildPageLocalStoryInstance(
+        input.frameId,
+        input.pageId,
+        input.pageIndex,
+        input.sectionIndex,
+        input.displayPageNumber,
+        input.layout,
+        input.stories.header,
+        input.regions.header,
+        findHeaderFooterPart(input.subParts?.headers, input.stories.header),
+        input.pageFieldCounts,
+    );
+    instances.push(built.instance);
+    divergences.push(...built.divergences);
+  }
+  if (isHeaderFooterStoryTarget(input.stories.footer)) {
+    const built = buildPageLocalStoryInstance(
+        input.frameId,
+        input.pageId,
+        input.pageIndex,
+        input.sectionIndex,
+        input.displayPageNumber,
+        input.layout,
+        input.stories.footer,
+        input.regions.footer,
+        findHeaderFooterPart(input.subParts?.footers, input.stories.footer),
+        input.pageFieldCounts,
+    );
+    instances.push(built.instance);
+    divergences.push(...built.divergences);
+  }
+  return { instances, divergences };
+}
+
+function buildPageLocalStoryInstance(
+  frameId: string,
+  pageId: string,
+  pageIndex: number,
+  sectionIndex: number,
+  displayPageNumber: number,
+  layout: PageLayoutSnapshot,
+  target: HeaderFooterStoryTarget,
+  region: RuntimePageRegion | undefined,
+  source: HeaderDocument | FooterDocument | undefined,
+  pageFieldCounts: PageFieldCounts,
+): {
+  instance: RuntimePageLocalStoryInstance;
+  divergences: RuntimeLayoutDivergence[];
+} {
+  const measuredFrameHeightTwips = region?.heightTwips ?? 0;
+  const sectionPart =
+    target.sectionIndex === undefined ? "section-unknown" : `section-${target.sectionIndex}`;
+  const instanceId = `${frameId}:${target.kind}:${target.variant}:${target.relationshipId}`;
+  const storyKey = `${target.kind}:${target.relationshipId}`;
+  const resolvedFields = source
+    ? collectResolvedStoryFields(source.blocks, {
+        storyKey,
+        pageIndex,
+        sectionIndex,
+        displayPageNumber,
+        layout,
+        pageFieldCounts,
+      })
+    : [];
+  const objectLedger = source
+    ? collectStoryAnchoredObjects(source.blocks, {
+        frameId,
+        storyKey,
+        kind: target.kind,
+        variant: target.variant,
+        relationshipId: target.relationshipId,
+      })
+    : { objects: [], divergences: [] };
+  const signature = buildPageLocalStorySignature({
+    kind: target.kind,
+    variant: target.variant,
+    relationshipId: target.relationshipId,
+    sectionPart,
+    measuredFrameHeightTwips,
+    resolvedFields,
+    anchoredObjects: objectLedger.objects,
+  });
+  return {
+    instance: {
+      instanceId,
+      storyKey,
+      pageId,
+      kind: target.kind,
+      variant: target.variant,
+      relationshipId: target.relationshipId,
+      ...(target.sectionIndex === undefined ? {} : { sectionIndex: target.sectionIndex }),
+      resolvedFields,
+      anchoredObjects: objectLedger.objects,
+      measuredFrameHeightTwips,
+      signature,
+    },
+    divergences: objectLedger.divergences,
+  };
+}
+
+function buildPageLocalStorySignature(input: {
+  kind: RuntimePageLocalStoryInstance["kind"];
+  variant: RuntimePageLocalStoryInstance["variant"];
+  relationshipId: string;
+  sectionPart: string;
+  measuredFrameHeightTwips: number;
+  resolvedFields: readonly RuntimePageLocalStoryInstance["resolvedFields"][number][];
+  anchoredObjects: readonly RuntimeStoryAnchoredObject[];
+}): string {
+  return [
+    "page-local-story",
+    input.kind,
+    input.variant,
+    input.relationshipId,
+    input.sectionPart,
+    input.measuredFrameHeightTwips,
+    ...input.resolvedFields.map((field) =>
+      [field.fieldId, field.family, field.displayText].join(":"),
+    ),
+    ...input.anchoredObjects.map((object) =>
+      [
+        object.objectId,
+        object.sourceType,
+        object.display,
+        object.extentTwips?.widthTwips ?? "",
+        object.extentTwips?.heightTwips ?? "",
+        object.relationshipIds?.join(",") ?? "",
+        object.preserveOnly ? "preserve-only" : "renderable",
+        object.divergenceIds.join(","),
+      ].join(":"),
+    ),
+  ].join("|");
+}
+
+interface PageFieldCounts {
+  contentPageCount: number;
+  sectionContentPageCountByIndex: ReadonlyMap<number, number>;
+}
+
+interface PageFieldResolutionInput {
+  storyKey: string;
+  pageIndex: number;
+  sectionIndex: number;
+  displayPageNumber: number;
+  layout: PageLayoutSnapshot;
+  pageFieldCounts: PageFieldCounts;
+}
+
+function buildPageFieldCounts(
+  pages: readonly Pick<DocumentPageSnapshot, "pageInSection" | "sectionIndex">[],
+): PageFieldCounts {
+  const sectionContentPageCountByIndex = new Map<number, number>();
+  let contentPageCount = 0;
+  for (const page of pages) {
+    if (page.pageInSection === -1) continue;
+    contentPageCount += 1;
+    sectionContentPageCountByIndex.set(
+      page.sectionIndex,
+      (sectionContentPageCountByIndex.get(page.sectionIndex) ?? 0) + 1,
+    );
+  }
+  return { contentPageCount, sectionContentPageCountByIndex };
+}
+
+function findHeaderFooterPart<T extends HeaderDocument | FooterDocument>(
+  parts: ReadonlyArray<T> | undefined,
+  target: HeaderFooterStoryTarget,
+): T | undefined {
+  return parts?.find((part) => part.relationshipId === target.relationshipId);
+}
+
+function collectResolvedStoryFields(
+  blocks: readonly BlockNode[],
+  context: PageFieldResolutionInput,
+): RuntimePageLocalStoryInstance["resolvedFields"] {
+  const fields: RuntimePageLocalStoryInstance["resolvedFields"] = [];
+  let ordinal = 0;
+
+  const visitBlock = (block: BlockNode): void => {
+    switch (block.type) {
+      case "paragraph":
+        for (const child of block.children) visitInline(child);
+        break;
+      case "table":
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            for (const child of cell.children) visitBlock(child);
+          }
+        }
+        break;
+      case "sdt":
+        for (const child of block.children) visitBlock(child);
+        break;
+      default:
+        break;
+    }
+  };
+
+  const visitInline = (inline: InlineNode): void => {
+    switch (inline.type) {
+      case "field": {
+        const family = inline.fieldFamily ?? classifyFieldInstructionLocal(inline.instruction);
+        if (PAGE_INSTANCE_FIELD_FAMILIES.has(family)) {
+          const fieldId = `${context.storyKey}:field-${ordinal}:${family}`;
+          fields.push({
+            fieldId,
+            family,
+            displayText: resolvePageInstanceFieldDisplayText(
+              family,
+              flattenInline(inline.children),
+              context,
+            ),
+          });
+          ordinal += 1;
+        }
+        break;
+      }
+      case "hyperlink":
+        for (const child of inline.children) visitInline(child);
+        break;
+      default:
+        break;
+    }
+  };
+
+  for (const block of blocks) visitBlock(block);
+  return fields;
+}
+
+interface StoryObjectContext {
+  frameId: string;
+  storyKey: string;
+  kind: "header" | "footer";
+  variant: RuntimePageLocalStoryInstance["variant"];
+  relationshipId: string;
+}
+
+function collectStoryAnchoredObjects(
+  blocks: readonly BlockNode[],
+  context: StoryObjectContext,
+): {
+  objects: RuntimeStoryAnchoredObject[];
+  divergences: RuntimeLayoutDivergence[];
+} {
+  const objects: RuntimeStoryAnchoredObject[] = [];
+  const divergences: RuntimeLayoutDivergence[] = [];
+  let ordinal = 0;
+
+  const pushObject = (
+    object: Omit<RuntimeStoryAnchoredObject, "objectId" | "divergenceIds"> & {
+      objectId?: string;
+      preserveHint?: PreserveOnlyObjectSizing;
+      wrapMode?: string;
+    },
+  ): void => {
+    const objectId =
+      object.objectId ?? `${context.storyKey}:object-${ordinal}:${object.sourceType}`;
+    const objectDivergenceIds: string[] = [];
+    const objectDisplay = object.display;
+
+    if (object.preserveOnly || object.preserveHint) {
+      const divergenceId = `${context.frameId}:preserve-only-placeholder:${objectId}`;
+      objectDivergenceIds.push(divergenceId);
+      divergences.push({
+        divergenceId,
+        kind: "preserve-only-placeholder",
+        source: "runtime",
+        severity: "info",
+        message: `Page-local ${context.kind} story contains preserve-only object ${objectId}`,
+        regionKinds: [context.kind],
+        objectIds: [objectId],
+      });
+    }
+
+    const wrapMode = object.wrapMode;
+    if (
+      objectDisplay === "floating" &&
+      wrapMode !== undefined &&
+      wrapMode !== "none" &&
+      wrapMode !== "topAndBottom"
+    ) {
+      const divergenceId = `${context.frameId}:unsupported-wrap:${objectId}:${wrapMode}`;
+      objectDivergenceIds.push(divergenceId);
+      divergences.push({
+        divergenceId,
+        kind: "unsupported-wrap",
+        source: "runtime",
+        severity: "warning",
+        message: `Page-local ${context.kind} story object ${objectId} uses unsupported wrap mode ${wrapMode}`,
+        regionKinds: [context.kind],
+        objectIds: [objectId],
+      });
+    }
+
+    const { preserveHint: _preserveHint, wrapMode: _wrapMode, ...ledger } = object;
+    objects.push({
+      ...ledger,
+      objectId,
+      divergenceIds: objectDivergenceIds,
+    });
+    ordinal += 1;
+  };
+
+  const visitBlock = (block: BlockNode): void => {
+    switch (block.type) {
+      case "paragraph":
+        for (const child of block.children) visitInline(child);
+        break;
+      case "table":
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            for (const child of cell.children) visitBlock(child);
+          }
+        }
+        break;
+      case "sdt":
+        for (const child of block.children) visitBlock(child);
+        break;
+      default:
+        break;
+    }
+  };
+
+  const visitInline = (inline: InlineNode): void => {
+    switch (inline.type) {
+      case "image": {
+        pushObject({
+          objectId: inline.mediaId,
+          sourceType: "image",
+          display: inline.display === "floating" ? "floating" : "inline",
+          preserveOnly: false,
+          wrapMode: inline.floating?.wrap,
+        });
+        break;
+      }
+      case "drawing_frame": {
+        const preserveHint = getDrawingFramePreserveHint(inline);
+        const relationshipIds = collectDrawingRelationshipIds(inline);
+        const display = inline.anchor.display;
+        pushObject({
+          objectId: getDrawingFrameObjectId(inline, context.storyKey, ordinal),
+          sourceType: "drawing-frame",
+          display,
+          extentTwips: extentTwipsFromEmu(
+            inline.anchor.extent.widthEmu,
+            inline.anchor.extent.heightEmu,
+          ),
+          ...(relationshipIds.length > 0 ? { relationshipIds } : {}),
+          preserveOnly: Boolean(preserveHint),
+          ...(preserveHint ? { preserveHint } : {}),
+          wrapMode: inline.anchor.wrapMode,
+        });
+        if (inline.content.type === "shape") {
+          for (const child of inline.content.txbxBlocks ?? []) visitBlock(child);
+        }
+        break;
+      }
+      case "chart_preview":
+      case "smartart_preview":
+      case "shape":
+      case "wordart":
+      case "vml_shape": {
+        const preserveHint = inline.preserveOnlyObject;
+        pushObject({
+          objectId: getPreserveOnlyObjectId(inline, context.storyKey, ordinal),
+          sourceType: sourceTypeForInlineObject(inline.type),
+          display: preserveHint?.display ?? "unknown",
+          ...(preserveHint?.extentEmu
+            ? {
+                extentTwips: extentTwipsFromEmu(
+                  preserveHint.extentEmu.widthEmu,
+                  preserveHint.extentEmu.heightEmu,
+                ),
+              }
+            : {}),
+          ...(preserveHint?.relationshipIds
+            ? { relationshipIds: [...preserveHint.relationshipIds] }
+            : {}),
+          preserveOnly: Boolean(preserveHint),
+          ...(preserveHint ? { preserveHint } : {}),
+        });
+        if (inline.type === "shape") {
+          for (const child of inline.txbxBlocks ?? []) visitBlock(child);
+        }
+        break;
+      }
+      case "ole_embed":
+        pushObject({
+          objectId: inline.id,
+          sourceType: "ole-embed",
+          display: "unknown",
+          relationshipIds: [inline.relationshipId],
+          preserveOnly: true,
+        });
+        break;
+      case "opaque_inline":
+        pushObject({
+          objectId: inline.fragmentId,
+          sourceType: "opaque-inline",
+          display: "unknown",
+          preserveOnly: true,
+        });
+        break;
+      case "field":
+        for (const child of inline.children) visitInline(child);
+        break;
+      case "hyperlink":
+        for (const child of inline.children) visitInline(child);
+        break;
+      default:
+        break;
+    }
+  };
+
+  for (const block of blocks) visitBlock(block);
+  return { objects, divergences };
+}
+
+function getDrawingFramePreserveHint(
+  inline: Extract<InlineNode, { type: "drawing_frame" }>,
+): PreserveOnlyObjectSizing | undefined {
+  const content = inline.content;
+  if (content.type === "picture") return undefined;
+  return content.preserveOnlyObject;
+}
+
+function collectDrawingRelationshipIds(
+  inline: Extract<InlineNode, { type: "drawing_frame" }>,
+): string[] {
+  const content = inline.content;
+  if (content.type === "picture") return [content.blipRef];
+  const preserveIds = content.preserveOnlyObject?.relationshipIds ?? [];
+  return [...preserveIds];
+}
+
+function getDrawingFrameObjectId(
+  inline: Extract<InlineNode, { type: "drawing_frame" }>,
+  storyKey: string,
+  ordinal: number,
+): string {
+  if (inline.anchor.docPr?.id) return `${storyKey}:drawing-${inline.anchor.docPr.id}`;
+  if (inline.content.type === "picture") return `${storyKey}:picture-${inline.content.blipRef}`;
+  return `${storyKey}:drawing-${ordinal}`;
+}
+
+function getPreserveOnlyObjectId(
+  inline: Extract<
+    InlineNode,
+    { type: "chart_preview" | "smartart_preview" | "shape" | "wordart" | "vml_shape" }
+  >,
+  storyKey: string,
+  ordinal: number,
+): string {
+  return inline.preserveOnlyObject?.sourceId ?? `${storyKey}:${inline.type}-${ordinal}`;
+}
+
+function sourceTypeForInlineObject(
+  type: Extract<
+    InlineNode,
+    { type: "chart_preview" | "smartart_preview" | "shape" | "wordart" | "vml_shape" }
+  >["type"],
+): RuntimeStoryAnchoredObject["sourceType"] {
+  switch (type) {
+    case "chart_preview":
+      return "chart-preview";
+    case "smartart_preview":
+      return "smartart-preview";
+    case "shape":
+      return "shape";
+    case "wordart":
+      return "wordart";
+    case "vml_shape":
+      return "vml-shape";
+  }
+}
+
+function extentTwipsFromEmu(
+  widthEmu: number,
+  heightEmu: number,
+): RuntimeStoryAnchoredObject["extentTwips"] {
+  return {
+    widthTwips: Math.max(0, Math.round(widthEmu / EMUS_PER_TWIP)),
+    heightTwips: Math.max(0, Math.round(heightEmu / EMUS_PER_TWIP)),
+  };
+}
+
+function resolvePageInstanceFieldDisplayText(
+  family: string,
+  cachedDisplayText: string,
+  context: PageFieldResolutionInput,
+): string {
+  switch (family) {
+    case "PAGE":
+      return formatPageNumberWithChapter(
+        context.displayPageNumber,
+        context.layout.pageNumbering,
+      );
+    case "NUMPAGES":
+      return formatPageNumber(
+        context.pageFieldCounts.contentPageCount,
+        context.layout.pageNumbering?.format,
+      );
+    case "SECTIONPAGES":
+      return formatPageNumber(
+        context.pageFieldCounts.sectionContentPageCountByIndex.get(context.sectionIndex) ?? 0,
+        context.layout.pageNumbering?.format,
+      );
+    default:
+      return cachedDisplayText;
+  }
+}
+
+function flattenInline(inlines: ReadonlyArray<InlineNode> | undefined): string {
+  if (!inlines) return "";
+  let buf = "";
+  for (const inline of inlines) {
+    if (inline.type === "text") buf += inline.text;
+    else if (inline.type === "hard_break" || inline.type === "tab") buf += " ";
+  }
+  return buf;
+}
+
+function classifyFieldInstructionLocal(instr: string): string {
+  const match = /^\s*(\w+)/.exec(instr);
+  return match ? match[1]!.toUpperCase() : "UNKNOWN";
+}
+
+function isHeaderFooterStoryTarget(
+  target: EditorStoryTarget | undefined,
+): target is HeaderFooterStoryTarget {
+  return target?.kind === "header" || target?.kind === "footer";
+}
+
+function buildPageFrameId(
+  pageIndex: number,
+  sectionIndex: number,
+  displayPageNumber: number,
+): string {
+  return `page-frame-${pageIndex}-section-${sectionIndex}-display-${displayPageNumber}`;
+}
+
+function buildPageFrameSignature(
+  input: {
+    pageIndex: number;
+    sectionIndex: number;
+    displayPageNumber: number;
+    layout: PageLayoutSnapshot;
+    regions: RuntimePageRegions;
+  },
+  pageLocalStories: readonly RuntimePageLocalStoryInstance[],
+  divergenceIds: readonly string[],
+): string {
+  const regionParts = collectRegions(input.regions).map((region) => {
+    const r = region.rectTwips ?? rect(0, region.originTwips, region.widthTwips, region.heightTwips);
+    return [
+      region.kind,
+      r.xTwips,
+      r.yTwips,
+      r.widthTwips,
+      r.heightTwips,
+      region.fragmentIds.length,
+    ].join(":");
+  });
+  return [
+    "page-frame",
+    input.pageIndex,
+    input.sectionIndex,
+    input.displayPageNumber,
+    input.layout.pageWidth,
+    input.layout.pageHeight,
+    ...regionParts,
+    ...pageLocalStories.map((story) => story.signature),
+    ...divergenceIds,
+  ].join("|");
+}
+
+function detectFrameDivergences(
+  frameId: string,
+  regions: RuntimePageRegions,
+): RuntimeLayoutDivergence[] {
+  const candidates = collectRegions(regions).filter((region) => region.rectTwips !== undefined);
+  const divergences: RuntimeLayoutDivergence[] = [];
+  for (let i = 0; i < candidates.length; i += 1) {
+    for (let j = i + 1; j < candidates.length; j += 1) {
+      const a = candidates[i]!;
+      const b = candidates[j]!;
+      if (!shouldDetectCollision(a, b)) continue;
+      if (!rectsOverlap(a.rectTwips!, b.rectTwips!)) continue;
+      const kinds = [a.kind, b.kind].sort();
+      divergences.push({
+        divergenceId: `${frameId}:frame-collision:${kinds.join("-")}`,
+        kind: "frame-collision",
+        source: "runtime",
+        severity: "warning",
+        message: `Resolved page regions overlap: ${kinds.join(" / ")}`,
+        regionKinds: kinds as RuntimeLayoutDivergence["regionKinds"],
+        fragmentIds: [...a.fragmentIds, ...b.fragmentIds],
+      });
+    }
+  }
+  return divergences;
+}
+
+function collectRegions(regions: RuntimePageRegions): RuntimePageRegion[] {
+  return [
+    regions.body,
+    ...(regions.header ? [regions.header] : []),
+    ...(regions.footer ? [regions.footer] : []),
+    ...(regions.columns ?? []),
+    ...(regions.footnotes ?? []),
+  ];
+}
+
+function shouldDetectCollision(a: RuntimePageRegion, b: RuntimePageRegion): boolean {
+  if (a.kind === "body" && b.kind === "column") return false;
+  if (a.kind === "column" && b.kind === "body") return false;
+  if (a.kind === "column" && b.kind === "column") return false;
+  return true;
+}
+
+function rectsOverlap(a: RuntimeTwipsRect, b: RuntimeTwipsRect): boolean {
+  return (
+    a.xTwips < b.xTwips + b.widthTwips &&
+    a.xTwips + a.widthTwips > b.xTwips &&
+    a.yTwips < b.yTwips + b.heightTwips &&
+    a.yTwips + a.heightTwips > b.yTwips
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Graph queries
 // ---------------------------------------------------------------------------
@@ -464,10 +1267,11 @@ export function spliceGraph(
   }));
 
   const contentPageCount = nextPages.filter((p) => !p.isBlankFiller).length;
+  const normalizedPages = normalizePageLocalStoryFieldsForPages(nextPages);
 
   return {
     revision: graphRevision,
-    pages: nextPages,
+    pages: normalizedPages,
     fragments: mergedFragments,
     anchors,
     sections: [...prior.sections],
@@ -475,6 +1279,77 @@ export function spliceGraph(
   };
 }
 
+function normalizePageLocalStoryFieldsForPages(
+  pages: readonly RuntimePageNode[],
+): RuntimePageNode[] {
+  const pageFieldCounts = buildPageFieldCounts(pages);
+  return pages.map((page) => {
+    const frame = page.frame;
+    if (!frame || frame.pageLocalStories.every((story) => story.resolvedFields.length === 0)) {
+      return page;
+    }
+
+    let changed = false;
+    const pageLocalStories = frame.pageLocalStories.map((story) => {
+      if (story.resolvedFields.length === 0) return story;
+      let storyChanged = false;
+      const resolvedFields = story.resolvedFields.map((field) => {
+        const displayText = resolvePageInstanceFieldDisplayText(
+          field.family,
+          field.displayText,
+          {
+            storyKey: story.storyKey,
+            pageIndex: page.pageIndex,
+            sectionIndex: page.sectionIndex,
+            displayPageNumber: page.stories.displayPageNumber,
+            layout: page.layout,
+            pageFieldCounts,
+          },
+        );
+        if (displayText === field.displayText) return field;
+        storyChanged = true;
+        changed = true;
+        return { ...field, displayText };
+      });
+      if (!storyChanged) return story;
+      const sectionPart =
+        story.sectionIndex === undefined ? "section-unknown" : `section-${story.sectionIndex}`;
+      return {
+        ...story,
+        resolvedFields,
+        signature: buildPageLocalStorySignature({
+          kind: story.kind,
+          variant: story.variant,
+          relationshipId: story.relationshipId,
+          sectionPart,
+          measuredFrameHeightTwips: story.measuredFrameHeightTwips,
+          resolvedFields,
+          anchoredObjects: story.anchoredObjects,
+        }),
+      };
+    });
+
+    if (!changed) return page;
+    const divergenceIds = frame.divergenceIds;
+    const nextFrame: RuntimePageFrame = {
+      ...frame,
+      pageLocalStories,
+      signature: buildPageFrameSignature(
+        {
+          pageIndex: frame.pageIndex,
+          sectionIndex: frame.sectionIndex,
+          displayPageNumber: frame.displayPageNumber,
+          layout: page.layout,
+          regions: page.regions,
+        },
+        pageLocalStories,
+        divergenceIds,
+      ),
+    };
+    return { ...page, frame: nextFrame };
+  });
+}
+
 /**
  * Compare two `RuntimePageNode`s by the fields that matter for
  * pagination identity — if these all match, the fresh node represents