@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/api/v3/runtime/layout.ts

@@ -9,6 +9,157 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata, MockPayload } from "../_layer-metadata.ts";
 import { mockPayload } from "../_mocks.ts";
+import type {
+  PublicPageFrame,
+  PublicPageLocalStoryInstance,
+  PublicPageNode,
+  PublicPageRegion,
+  PublicResolvedStoryField,
+  PublicStoryAnchoredObject,
+} from "../../../runtime/layout/public-facet.ts";
+
+export interface V3TwipsRect {
+  readonly xTwips: number;
+  readonly yTwips: number;
+  readonly widthTwips: number;
+  readonly heightTwips: number;
+}
+
+export interface V3PageFrameRegion {
+  readonly kind: "body" | "header" | "footer" | "column" | "footnote-area";
+  readonly rectTwips: V3TwipsRect;
+  readonly fragmentCount: number;
+}
+
+export type V3PageFrameCompleteness = PublicPageFrame["completeness"];
+
+export interface V3PageFrame {
+  readonly frameId: string;
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly sectionIndex: number;
+  readonly displayPageNumber: number;
+  readonly completeness: V3PageFrameCompleteness;
+  readonly physicalBoundsTwips: V3TwipsRect;
+  readonly divergenceIds: readonly string[];
+  readonly exclusionZoneCount: number;
+  readonly regions: readonly V3PageFrameRegion[];
+  readonly signature: string;
+  readonly source: "layout-public-frame" | "layout-public-facet-fallback";
+}
+
+export interface V3PageLocalStoryObject {
+  readonly objectId: string;
+  readonly sourceType:
+    | "image"
+    | "drawing-frame"
+    | "chart-preview"
+    | "smartart-preview"
+    | "shape"
+    | "wordart"
+    | "vml-shape"
+    | "ole-embed"
+    | "opaque-inline";
+  readonly display: "inline" | "floating" | "unknown";
+  readonly extentTwips?: {
+    readonly widthTwips: number;
+    readonly heightTwips: number;
+  };
+  readonly relationshipIds?: readonly string[];
+  readonly mediaIds?: readonly string[];
+  readonly preserveOnly: boolean;
+  readonly divergenceIds: readonly string[];
+}
+
+export interface V3PageLocalStoryField {
+  readonly fieldId: string;
+  readonly family: PublicResolvedStoryField["family"];
+  readonly displayText: string;
+}
+
+export interface V3PageLocalStory {
+  readonly instanceId: string;
+  readonly storyKey: string;
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly frameId: string;
+  readonly kind: "header" | "footer";
+  readonly variant: "default" | "first" | "even" | "odd";
+  readonly relationshipId: string;
+  readonly sectionIndex?: number;
+  readonly resolvedFields: readonly V3PageLocalStoryField[];
+  readonly anchoredObjects: readonly V3PageLocalStoryObject[];
+  readonly measuredFrameHeightTwips: number;
+  readonly signature: string;
+}
+
+export interface V3PageLocalStoriesResult {
+  readonly status: "available" | "unavailable";
+  readonly source: "layout-public-facet" | "layout-public-facet-unavailable";
+  readonly pageIndex: number;
+  readonly pageId?: string;
+  readonly frameId?: string;
+  readonly frameCompleteness?: V3PageFrameCompleteness;
+  readonly reason?: "layout-unavailable" | "page-not-found" | "frame-unavailable";
+  readonly stories: readonly V3PageLocalStory[];
+}
+
+export interface V3PageLocalFieldLedgerEntry extends V3PageLocalStoryField {
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly frameId: string;
+  readonly instanceId: string;
+  readonly storyKey: string;
+  readonly kind: "header" | "footer";
+  readonly variant: "default" | "first" | "even" | "odd";
+  readonly relationshipId: string;
+  readonly sectionIndex?: number;
+}
+
+export interface V3PageLocalFieldLedgerResult {
+  readonly status: "available" | "unavailable";
+  readonly source: "layout-public-facet" | "layout-public-facet-unavailable";
+  readonly pageIndex: number;
+  readonly pageId?: string;
+  readonly frameId?: string;
+  readonly frameCompleteness?: V3PageFrameCompleteness;
+  readonly reason?: "layout-unavailable" | "page-not-found" | "frame-unavailable";
+  readonly fields: readonly V3PageLocalFieldLedgerEntry[];
+}
+
+export interface V3LayoutDivergence {
+  readonly divergenceId: string;
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly frameId?: string;
+  readonly kind?: string;
+  readonly source?: string;
+  readonly severity?: string;
+  readonly message?: string;
+  readonly regionKinds?: readonly string[];
+  readonly fragmentIds?: readonly string[];
+  readonly objectIds?: readonly string[];
+  readonly detailSource: "page-divergence" | "frame-divergence-id";
+}
+
+export interface V3LayoutCompleteness {
+  readonly status: "realized" | "partial" | "unavailable";
+  readonly pageCount: number;
+  readonly framedPageCount: number;
+  readonly missingFramePageIds: readonly string[];
+  readonly frameCompleteness: {
+    readonly complete: number;
+    readonly partial: number;
+    readonly absent: number;
+  };
+  readonly regionCount: number;
+  readonly regionWithRectCount: number;
+  readonly missingRectRegionCount: number;
+  readonly unknownStoryPageCount: number;
+  readonly pageLocalStoryCount: number;
+  readonly pageLocalObjectCount: number;
+  readonly divergenceCount: number;
+}
 
 export const getPageMetadata: ApiV3FnMetadata = {
   name: "runtime.layout.getPage",
@@ -64,11 +215,179 @@ export const getBlockLayoutMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.layout.getBlockLayout. Adapter wraps facet.getMeasurement(blockId) → PublicBlockMeasurement; promotes to `live` when the v3 shape matches 1:1.",
 };
 
+export const getPageFrameMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getPageFrame",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/layout-page-frame-read-surface.test.ts",
+    commit: "refactor-07-pe2-page-frame-read-surface",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "layout-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getPageFrame. PE2 read surface over the Layer-04 public page-frame substrate. Adapter projects `PublicPageNode.frame` when populated, preserving frame ids, signatures, completeness, divergence ids, exclusion counts, and region ordering; the legacy page layout/regions composition remains an explicit degraded fallback with completeness:'absent'.",
+};
+
+export const getPageFramesMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getPageFrames",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/layout-page-frame-read-surface.test.ts",
+    commit: "refactor-07-pe2-page-frame-read-surface",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "layout-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getPageFrames. Enumerates PE2 page-frame records from the Layer-04 layout facet, preserving section filter semantics from `layout.getPages({sectionIndex})` and projecting `PublicPageNode.frame` including completeness when populated. Returns [] when the layout facet is absent.",
+};
+
+export const getPageLocalStoriesMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getPageLocalStories",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/layout-page-frame-read-surface.test.ts",
+    commit: "refactor-07-pe2-page-local-story-divergence-completeness",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "layout-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getPageLocalStories. PE2 read surface over `PublicPageFrame.pageLocalStories`, exposing page-local header/footer story instances, resolved field ledgers, anchored object ledgers, and L04 frame completeness without leaking runtime graph nodes. Returns an explicit availability envelope so empty page-local stories are distinguishable from an absent L04 frame substrate.",
+};
+
+export const getPageLocalFieldLedgerMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getPageLocalFieldLedger",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/layout-page-frame-read-surface.test.ts",
+    commit: "refactor-07-pe2-page-local-field-ledger",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "layout-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getPageLocalFieldLedger. Public v3 read over L04 `PublicPageLocalStoryInstance.resolvedFields`, keyed by page/frame/story identity and frame completeness so agents can cite page-local header/footer field realization without reaching into layout graph internals.",
+};
+
+export const getLayoutDivergencesMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getLayoutDivergences",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/layout-page-frame-read-surface.test.ts",
+    commit: "refactor-07-pe2-page-local-story-divergence-completeness",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "layout-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getLayoutDivergences. Enumerates typed `PublicPageNode.divergences` plus frame-level divergence ids from the L04 public layout facet. Frame ids without page-level details remain id-only records.",
+};
+
+export const getLayoutCompletenessMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getLayoutCompleteness",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/layout-page-frame-read-surface.test.ts",
+    commit: "refactor-07-pe2-page-local-story-divergence-completeness",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "layout-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getLayoutCompleteness. Summarizes L04 public page-frame realization, frame completeness counts, region rect coverage, page-local story/object counts, unknown story pages, and divergence ids as a lightweight PE2 layout-read health signal.",
+};
+
 export function createLayoutFamily(runtime: RuntimeApiHandle) {
   // Public-facet shape — see src/runtime/layout/public-facet.ts:376+.
   const layout = runtime.layout;
 
   return {
+    getPageFrame(pageIndex: number): V3PageFrame | null {
+      // @endStateApi — live-with-adapter. Prefer the L04 public frame
+      // substrate. The legacy composition path is kept only for older or
+      // inert facets that have not emitted page.frame yet.
+      const page = layout?.getPage(pageIndex);
+      return page ? toV3PageFrame(page) : null;
+    },
+
+    getPageFrames(options?: { sectionIndex?: number }): readonly V3PageFrame[] {
+      // @endStateApi — live-with-adapter. Mirrors layout.getPages filter
+      // semantics and projects each page into the PE2 frame read shape.
+      const pages = layout?.getPages(options);
+      return pages?.map(toV3PageFrame) ?? [];
+    },
+
+    getPageLocalStories(pageIndex: number): V3PageLocalStoriesResult {
+      // @endStateApi — live-with-adapter. Reads the L04 public page-frame
+      // story ledger. The envelope distinguishes true empty stories from
+      // a missing page-frame substrate.
+      const page = layout?.getPage(pageIndex);
+      return toV3PageLocalStoriesResult(pageIndex, page, layout === undefined);
+    },
+
+    getPageLocalFieldLedger(pageIndex: number): V3PageLocalFieldLedgerResult {
+      // @endStateApi — live-with-adapter. Projects L04 resolved page-local
+      // fields as a citation-ready ledger and keeps unavailable frames
+      // distinct from available pages with zero resolved fields.
+      const page = layout?.getPage(pageIndex);
+      return toV3PageLocalFieldLedgerResult(pageIndex, page, layout === undefined);
+    },
+
+    getLayoutDivergences(options?: {
+      pageIndex?: number;
+      sectionIndex?: number;
+    }): readonly V3LayoutDivergence[] {
+      // @endStateApi — live-with-adapter. Keeps typed page divergences and
+      // id-only frame divergences visible without inventing lower-layer detail.
+      const pages = getPagesForLayoutRead(layout, options);
+      return pages.flatMap(toV3LayoutDivergences);
+    },
+
+    getLayoutCompleteness(options?: { sectionIndex?: number }): V3LayoutCompleteness {
+      // @endStateApi — live-with-adapter. Lightweight page-frame health
+      // summary for agents/debug; does not validate Word parity.
+      const pages = layout?.getPages(options) ?? [];
+      return summarizeLayoutCompleteness(pages);
+    },
+
     getPage(pageIndex: number) {
       // @endStateApi — live-with-adapter. Wraps the facet's
       // getPage(pageIndex); promotes to `live` when the v3 shape matches
@@ -106,3 +425,428 @@ export function createLayoutFamily(runtime: RuntimeApiHandle) {
     },
   };
 }
+
+type LayoutReadFacet = NonNullable<RuntimeApiHandle["layout"]>;
+
+function toV3PageFrame(page: PublicPageNode): V3PageFrame {
+  if (page.frame) return publicFrameToV3(page.frame);
+  return legacyPageToV3PageFrame(page);
+}
+
+function publicFrameToV3(frame: PublicPageFrame): V3PageFrame {
+  const regions = frame.regionFrames.flatMap((region): V3PageFrameRegion[] => {
+    if (!region.rectTwips) return [];
+    return [
+      {
+        kind: region.kind,
+        rectTwips: cloneRect(region.rectTwips),
+        fragmentCount: region.fragmentIds.length,
+      },
+    ];
+  });
+  return {
+    frameId: frame.frameId,
+    pageId: frame.pageId,
+    pageIndex: frame.pageIndex,
+    sectionIndex: frame.sectionIndex,
+    displayPageNumber: frame.displayPageNumber,
+    completeness: frame.completeness,
+    physicalBoundsTwips: cloneRect(frame.physicalBoundsTwips),
+    divergenceIds: [...frame.divergenceIds],
+    exclusionZoneCount: frame.exclusionZoneCount,
+    regions,
+    signature: frame.signature,
+    source: "layout-public-frame",
+  };
+}
+
+function toV3PageLocalStory(
+  story: PublicPageLocalStoryInstance,
+  frame: PublicPageFrame,
+): V3PageLocalStory {
+  return {
+    instanceId: story.instanceId,
+    storyKey: story.storyKey,
+    pageId: story.pageId,
+    pageIndex: frame.pageIndex,
+    frameId: frame.frameId,
+    kind: story.kind,
+    variant: story.variant,
+    relationshipId: story.relationshipId,
+    ...(story.sectionIndex !== undefined ? { sectionIndex: story.sectionIndex } : {}),
+    resolvedFields: story.resolvedFields.map(toV3PageLocalStoryField),
+    anchoredObjects: story.anchoredObjects.map(toV3PageLocalStoryObject),
+    measuredFrameHeightTwips: story.measuredFrameHeightTwips,
+    signature: story.signature,
+  };
+}
+
+function toV3PageLocalStoriesResult(
+  pageIndex: number,
+  page: PublicPageNode | null | undefined,
+  layoutUnavailable: boolean,
+): V3PageLocalStoriesResult {
+  if (layoutUnavailable) {
+    return unavailablePageLocalStories(pageIndex, "layout-unavailable");
+  }
+  if (!page) {
+    return unavailablePageLocalStories(pageIndex, "page-not-found");
+  }
+  if (!page.frame) {
+    return unavailablePageLocalStories(pageIndex, "frame-unavailable", page);
+  }
+  return {
+    status: "available",
+    source: "layout-public-facet",
+    pageIndex,
+    pageId: page.pageId,
+    frameId: page.frame.frameId,
+    frameCompleteness: page.frame.completeness,
+    stories: page.frame.pageLocalStories.map((story) => toV3PageLocalStory(story, page.frame!)),
+  };
+}
+
+function unavailablePageLocalStories(
+  pageIndex: number,
+  reason: V3PageLocalStoriesResult["reason"],
+  page?: PublicPageNode,
+): V3PageLocalStoriesResult {
+  return {
+    status: "unavailable",
+    source: "layout-public-facet-unavailable",
+    pageIndex,
+    ...(page ? { pageId: page.pageId } : {}),
+    ...(reason === "frame-unavailable" ? { frameCompleteness: "absent" as const } : {}),
+    reason,
+    stories: [],
+  };
+}
+
+function toV3PageLocalFieldLedgerResult(
+  pageIndex: number,
+  page: PublicPageNode | null | undefined,
+  layoutUnavailable: boolean,
+): V3PageLocalFieldLedgerResult {
+  if (layoutUnavailable) {
+    return unavailablePageLocalFieldLedger(pageIndex, "layout-unavailable");
+  }
+  if (!page) {
+    return unavailablePageLocalFieldLedger(pageIndex, "page-not-found");
+  }
+  if (!page.frame) {
+    return unavailablePageLocalFieldLedger(pageIndex, "frame-unavailable", page);
+  }
+  return {
+    status: "available",
+    source: "layout-public-facet",
+    pageIndex,
+    pageId: page.pageId,
+    frameId: page.frame.frameId,
+    frameCompleteness: page.frame.completeness,
+    fields: page.frame.pageLocalStories.flatMap((story) =>
+      story.resolvedFields.map((field) => toV3PageLocalFieldLedgerEntry(field, story, page.frame!)),
+    ),
+  };
+}
+
+function unavailablePageLocalFieldLedger(
+  pageIndex: number,
+  reason: V3PageLocalFieldLedgerResult["reason"],
+  page?: PublicPageNode,
+): V3PageLocalFieldLedgerResult {
+  return {
+    status: "unavailable",
+    source: "layout-public-facet-unavailable",
+    pageIndex,
+    ...(page ? { pageId: page.pageId } : {}),
+    ...(reason === "frame-unavailable" ? { frameCompleteness: "absent" as const } : {}),
+    reason,
+    fields: [],
+  };
+}
+
+function toV3PageLocalStoryField(
+  field: PublicResolvedStoryField,
+): V3PageLocalStoryField {
+  return {
+    fieldId: field.fieldId,
+    family: field.family,
+    displayText: field.displayText,
+  };
+}
+
+function toV3PageLocalFieldLedgerEntry(
+  field: PublicResolvedStoryField,
+  story: PublicPageLocalStoryInstance,
+  frame: PublicPageFrame,
+): V3PageLocalFieldLedgerEntry {
+  return {
+    ...toV3PageLocalStoryField(field),
+    pageId: story.pageId,
+    pageIndex: frame.pageIndex,
+    frameId: frame.frameId,
+    instanceId: story.instanceId,
+    storyKey: story.storyKey,
+    kind: story.kind,
+    variant: story.variant,
+    relationshipId: story.relationshipId,
+    ...(story.sectionIndex !== undefined ? { sectionIndex: story.sectionIndex } : {}),
+  };
+}
+
+function toV3PageLocalStoryObject(
+  object: PublicStoryAnchoredObject,
+): V3PageLocalStoryObject {
+  return {
+    objectId: object.objectId,
+    sourceType: object.sourceType,
+    display: object.display,
+    ...(object.extentTwips
+      ? {
+          extentTwips: {
+            widthTwips: object.extentTwips.widthTwips,
+            heightTwips: object.extentTwips.heightTwips,
+          },
+        }
+      : {}),
+    ...(object.relationshipIds ? { relationshipIds: [...object.relationshipIds] } : {}),
+    ...(object.mediaIds ? { mediaIds: [...object.mediaIds] } : {}),
+    preserveOnly: object.preserveOnly,
+    divergenceIds: [...object.divergenceIds],
+  };
+}
+
+function getPagesForLayoutRead(
+  layout: LayoutReadFacet | undefined,
+  options: { pageIndex?: number; sectionIndex?: number } | undefined,
+): readonly PublicPageNode[] {
+  if (!layout) return [];
+  if (options?.pageIndex !== undefined) {
+    const page = layout.getPage(options.pageIndex);
+    if (!page) return [];
+    if (options.sectionIndex !== undefined && page.sectionIndex !== options.sectionIndex) return [];
+    return [page];
+  }
+  return layout.getPages(
+    options?.sectionIndex !== undefined ? { sectionIndex: options.sectionIndex } : undefined,
+  );
+}
+
+function toV3LayoutDivergences(page: PublicPageNode): V3LayoutDivergence[] {
+  const out = new Map<string, V3LayoutDivergence>();
+  const frameId = page.frame?.frameId;
+
+  for (const divergence of page.divergences ?? []) {
+    out.set(divergence.divergenceId, {
+      divergenceId: divergence.divergenceId,
+      pageId: page.pageId,
+      pageIndex: page.pageIndex,
+      ...(frameId ? { frameId } : {}),
+      kind: divergence.kind,
+      source: divergence.source,
+      severity: divergence.severity,
+      message: divergence.message,
+      ...(divergence.regionKinds ? { regionKinds: [...divergence.regionKinds] } : {}),
+      ...(divergence.fragmentIds ? { fragmentIds: [...divergence.fragmentIds] } : {}),
+      ...(divergence.objectIds ? { objectIds: [...divergence.objectIds] } : {}),
+      detailSource: "page-divergence",
+    });
+  }
+
+  for (const divergenceId of page.frame?.divergenceIds ?? []) {
+    if (out.has(divergenceId)) continue;
+    out.set(divergenceId, {
+      divergenceId,
+      pageId: page.pageId,
+      pageIndex: page.pageIndex,
+      ...(frameId ? { frameId } : {}),
+      detailSource: "frame-divergence-id",
+    });
+  }
+
+  return [...out.values()];
+}
+
+function summarizeLayoutCompleteness(pages: readonly PublicPageNode[]): V3LayoutCompleteness {
+  let framedPageCount = 0;
+  let regionCount = 0;
+  let regionWithRectCount = 0;
+  let pageLocalStoryCount = 0;
+  let pageLocalObjectCount = 0;
+  let unknownStoryPageCount = 0;
+  const frameCompleteness = {
+    complete: 0,
+    partial: 0,
+    absent: 0,
+  };
+  const missingFramePageIds: string[] = [];
+  const divergenceIds = new Set<string>();
+
+  for (const page of pages) {
+    const frame = page.frame;
+    if (!frame) {
+      missingFramePageIds.push(page.pageId);
+      unknownStoryPageCount += 1;
+      frameCompleteness.absent += 1;
+    } else {
+      framedPageCount += 1;
+      frameCompleteness[frame.completeness] += 1;
+      pageLocalStoryCount += frame.pageLocalStories.length;
+      for (const story of frame.pageLocalStories) {
+        pageLocalObjectCount += story.anchoredObjects.length;
+      }
+      for (const region of frame.regionFrames) {
+        regionCount += 1;
+        if (region.rectTwips) regionWithRectCount += 1;
+      }
+      for (const divergenceId of frame.divergenceIds) divergenceIds.add(divergenceId);
+    }
+    for (const divergence of page.divergences ?? []) divergenceIds.add(divergence.divergenceId);
+  }
+
+  const missingRectRegionCount = regionCount - regionWithRectCount;
+  return {
+    status:
+      pages.length === 0
+        ? "unavailable"
+        : missingFramePageIds.length === 0 && missingRectRegionCount === 0
+          ? "realized"
+          : "partial",
+    pageCount: pages.length,
+    framedPageCount,
+    missingFramePageIds,
+    frameCompleteness,
+    regionCount,
+    regionWithRectCount,
+    missingRectRegionCount,
+    unknownStoryPageCount,
+    pageLocalStoryCount,
+    pageLocalObjectCount,
+    divergenceCount: divergenceIds.size,
+  };
+}
+
+function legacyPageToV3PageFrame(page: PublicPageNode): V3PageFrame {
+  const regions = collectLegacyV3PageFrameRegions(page);
+  return {
+    frameId: buildFrameId(page),
+    pageId: page.pageId,
+    pageIndex: page.pageIndex,
+    sectionIndex: page.sectionIndex,
+    displayPageNumber: page.displayPageNumber,
+    completeness: "absent",
+    physicalBoundsTwips: rect(0, 0, page.layout.pageWidth, page.layout.pageHeight),
+    divergenceIds: page.divergences?.map((divergence) => divergence.divergenceId) ?? [],
+    exclusionZoneCount: legacyExclusionZoneCount(page),
+    regions,
+    signature: buildFrameSignature(page, regions),
+    source: "layout-public-facet-fallback",
+  };
+}
+
+function legacyExclusionZoneCount(page: PublicPageNode): number {
+  const carrier = page as PublicPageNode & {
+    readonly exclusionZones?: readonly unknown[];
+    readonly layout: PublicPageNode["layout"] & {
+      readonly exclusionZones?: readonly unknown[];
+    };
+  };
+  if (Array.isArray(carrier.exclusionZones)) return carrier.exclusionZones.length;
+  if (Array.isArray(carrier.layout.exclusionZones)) return carrier.layout.exclusionZones.length;
+  return 0;
+}
+
+function collectLegacyV3PageFrameRegions(page: PublicPageNode): readonly V3PageFrameRegion[] {
+  const out: V3PageFrameRegion[] = [
+    {
+      kind: "body",
+      rectTwips: rect(
+        page.layout.marginLeft,
+        page.regions.body.originTwips,
+        page.regions.body.widthTwips,
+        page.regions.body.heightTwips,
+      ),
+      fragmentCount: page.regions.body.fragmentCount,
+    },
+  ];
+  if (page.regions.header) {
+    out.push(regionAtMarginLeft(page, page.regions.header));
+  }
+  if (page.regions.footer) {
+    out.push(regionAtMarginLeft(page, page.regions.footer));
+  }
+  const columns = page.regions.columns ?? [];
+  const gap = page.layout.columnDefinitions?.[0]?.space ?? 720;
+  for (let i = 0; i < columns.length; i += 1) {
+    const column = columns[i]!;
+    out.push({
+      kind: "column",
+      rectTwips: rect(
+        page.layout.marginLeft + i * (column.widthTwips + gap),
+        column.originTwips,
+        column.widthTwips,
+        column.heightTwips,
+      ),
+      fragmentCount: column.fragmentCount,
+    });
+  }
+  for (const footnote of page.regions.footnotes ?? []) {
+    out.push(regionAtMarginLeft(page, footnote));
+  }
+  return out;
+}
+
+function cloneRect(value: V3TwipsRect): V3TwipsRect {
+  return rect(value.xTwips, value.yTwips, value.widthTwips, value.heightTwips);
+}
+
+function regionAtMarginLeft(page: PublicPageNode, region: PublicPageRegion): V3PageFrameRegion {
+  return {
+    kind: region.kind,
+    rectTwips: rect(
+      page.layout.marginLeft,
+      region.originTwips,
+      region.widthTwips,
+      region.heightTwips,
+    ),
+    fragmentCount: region.fragmentCount,
+  };
+}
+
+function rect(
+  xTwips: number,
+  yTwips: number,
+  widthTwips: number,
+  heightTwips: number,
+): V3TwipsRect {
+  return { xTwips, yTwips, widthTwips, heightTwips };
+}
+
+function buildFrameId(page: PublicPageNode): string {
+  return `page-frame-${page.pageIndex}-section-${page.sectionIndex}-display-${page.displayPageNumber}`;
+}
+
+function buildFrameSignature(
+  page: PublicPageNode,
+  regions: readonly V3PageFrameRegion[],
+): string {
+  const regionParts = regions.map((region) =>
+    [
+      region.kind,
+      region.rectTwips.xTwips,
+      region.rectTwips.yTwips,
+      region.rectTwips.widthTwips,
+      region.rectTwips.heightTwips,
+      region.fragmentCount,
+    ].join(":"),
+  );
+  return [
+    "page-frame",
+    page.pageIndex,
+    page.sectionIndex,
+    page.displayPageNumber,
+    page.layout.pageWidth,
+    page.layout.pageHeight,
+    ...regionParts,
+  ].join("|");
+}