@beyondwork/docx-react-component 1.0.110 → 1.0.111

package/src/runtime/geometry/adjacent-geometry-intake.ts

@@ -20,6 +20,20 @@ export interface AdjacentGeometryTwipsRect {
   readonly heightTwips?: number;
 }
 
+export interface AdjacentGeometryFramePxRect {
+  readonly leftPx: number;
+  readonly topPx: number;
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly coordinateSpace: "frame-px";
+}
+
+export interface AdjacentGeometryFramePxPoint {
+  readonly xPx: number;
+  readonly yPx: number;
+  readonly coordinateSpace: "frame-px";
+}
+
 export interface AdjacentGeometryPageSpan {
   readonly startPage?: number | null;
   readonly endPage?: number | null;
@@ -37,6 +51,7 @@ export interface AdjacentGeometryL04FrameProjection {
   readonly frameId?: string;
   readonly frameCompleteness?: string;
   readonly physicalBoundsTwips?: AdjacentGeometryTwipsRect;
+  readonly framePixelScale?: AdjacentGeometryFramePixelScale;
   readonly markerLane?: AdjacentGeometryTwipsRect;
   readonly textColumn?: AdjacentGeometryTwipsRect;
   readonly fieldStartAnchorTwips?: {
@@ -58,12 +73,46 @@ export interface AdjacentGeometryL04FrameProjection {
     | "missing-word-page-local-geometry";
 }
 
+export interface AdjacentGeometryFramePixelScale {
+  readonly source: "runtime-render-frame-page-rect";
+  readonly pageIndex: number;
+  readonly pageId?: string;
+  readonly frameId?: string;
+  readonly renderFrameRevision?: number;
+  readonly renderPageFrame: AdjacentGeometryFramePxRect;
+  readonly physicalBoundsTwips: AdjacentGeometryTwipsRect;
+  readonly pxPerTwipX: number;
+  readonly pxPerTwipY: number;
+  readonly zoomPxPerTwip?: number;
+}
+
+export interface AdjacentGeometryFramePixelProjection {
+  readonly pageIndex?: number;
+  readonly pageId?: string;
+  readonly frameId?: string;
+  readonly scale?: AdjacentGeometryFramePixelScale;
+  readonly markerLane?: AdjacentGeometryFramePxRect;
+  readonly textColumn?: AdjacentGeometryFramePxRect;
+  readonly fieldStartAnchorPx?: AdjacentGeometryFramePxPoint;
+  readonly fieldEndAnchorPx?: AdjacentGeometryFramePxPoint;
+  readonly fieldResultRangePx?: AdjacentGeometryFramePxRect;
+  readonly coordinateSpace: "frame-px";
+  readonly precision: "word-page-local-calibration";
+  readonly status:
+    | "projected-frame-pixels"
+    | "awaiting-l04-frame-projection"
+    | "missing-frame-pixel-scale"
+    | "missing-l04-frame-rect"
+    | "missing-l04-field-anchor";
+}
+
 interface AdjacentGeometryPageFrame {
   readonly pageId?: string;
   readonly pageIndex: number;
   readonly frameId?: string;
   readonly completeness?: string;
   readonly physicalBoundsTwips?: AdjacentGeometryTwipsRect;
+  readonly framePixelScale?: AdjacentGeometryFramePixelScale;
 }
 
 export interface AdjacentGeometryPageLocalNumberingGeometry {
@@ -75,6 +124,8 @@ export interface AdjacentGeometryPageLocalNumberingGeometry {
   readonly markerLane?: AdjacentGeometryTwipsRect;
   readonly textColumn?: AdjacentGeometryTwipsRect;
   readonly l04FrameProjection: AdjacentGeometryL04FrameProjection;
+  readonly framePixelProjection: AdjacentGeometryFramePixelProjection;
+  readonly compositorReady: boolean;
   readonly coordinateSpace: "word-page-twips";
   readonly precision: "word-page-local-calibration";
   readonly normalizationStatus:
@@ -102,6 +153,8 @@ export interface AdjacentGeometryPageLocalFieldGeometry {
     readonly y?: number;
   };
   readonly l04FrameProjection: AdjacentGeometryL04FrameProjection;
+  readonly framePixelProjection: AdjacentGeometryFramePixelProjection;
+  readonly compositorReady: boolean;
   readonly coordinateSpace: "word-page-twips";
   readonly precision: "word-page-local-calibration";
   readonly normalizationStatus:
@@ -144,6 +197,7 @@ export interface AdjacentGeometryNumberingRowSummary {
     readonly heightTwips?: number;
   };
   readonly pageLocalGeometry: AdjacentGeometryPageLocalNumberingGeometry;
+  readonly compositorReady: boolean;
   readonly rangeMappingMethod?: string;
   readonly coordinateSpace: "screen-px";
   readonly precision: "screen-space-approximate";
@@ -166,6 +220,7 @@ export interface AdjacentGeometryFieldRegionRowSummary {
     readonly endPage?: number | null;
   };
   readonly pageLocalGeometry: AdjacentGeometryPageLocalFieldGeometry;
+  readonly compositorReady: boolean;
   readonly instructionFamily?: string;
   readonly resultLineRectCount: number;
   readonly wordPlacement?: {
@@ -205,6 +260,9 @@ export interface AdjacentGeometryDocumentSummary {
   readonly numberingUiaRowsWithRuntimePageMatch: number;
   readonly numberingRowsWithL04FrameProjection: number;
   readonly numberingUiaRowsWithL04FrameProjection: number;
+  readonly numberingRowsWithFramePixelProjection: number;
+  readonly numberingUiaRowsWithFramePixelProjection: number;
+  readonly numberingCompositorReadyRows: number;
   readonly fieldRegionRows: number;
   readonly fieldRegionRowsWithRuntimeId: number;
   readonly fieldRegionResultLineRects: number;
@@ -214,10 +272,13 @@ export interface AdjacentGeometryDocumentSummary {
   readonly fieldRegionRowsWithRuntimePageContainment: number;
   readonly fieldRegionRowsWithL04FrameProjection: number;
   readonly fieldRegionUiaRowsWithL04FrameProjection: number;
+  readonly fieldRegionRowsWithFramePixelProjection: number;
+  readonly fieldRegionUiaRowsWithFramePixelProjection: number;
+  readonly fieldRegionCompositorReadyRows: number;
 }
 
 export interface AdjacentGeometryIntakeSummary {
-  readonly schemaVersion: "layer-05-adjacent-geometry-intake/v1";
+  readonly schemaVersion: "layer-05-adjacent-geometry-intake/v2";
   readonly generatedAtUtc: string;
   readonly sourceRuns: {
     readonly adjacentLiveWordJoins: string;
@@ -241,6 +302,9 @@ export interface AdjacentGeometryIntakeSummary {
     readonly numberingUiaRowsWithRuntimePageMatch: number;
     readonly numberingRowsWithL04FrameProjection: number;
     readonly numberingUiaRowsWithL04FrameProjection: number;
+    readonly numberingRowsWithFramePixelProjection: number;
+    readonly numberingUiaRowsWithFramePixelProjection: number;
+    readonly numberingCompositorReadyRows: number;
     readonly fieldRegionRows: number;
     readonly fieldRegionRowsWithRuntimeId: number;
     readonly fieldRegionResultLineRects: number;
@@ -250,6 +314,9 @@ export interface AdjacentGeometryIntakeSummary {
     readonly fieldRegionRowsWithRuntimePageContainment: number;
     readonly fieldRegionRowsWithL04FrameProjection: number;
     readonly fieldRegionUiaRowsWithL04FrameProjection: number;
+    readonly fieldRegionRowsWithFramePixelProjection: number;
+    readonly fieldRegionUiaRowsWithFramePixelProjection: number;
+    readonly fieldRegionCompositorReadyRows: number;
   };
   readonly routing: {
     readonly routedTo: "L05";
@@ -264,7 +331,10 @@ export interface AdjacentGeometryIntakeSummary {
     readonly requiredUpstreamFact: "L04 frame-to-pixel projection";
     readonly l04FrameProjectionCoordinateSpace: "l04-frame-twips";
     readonly l04FrameProjectionPrecision: "word-page-local-calibration";
-    readonly compositorReady: false;
+    readonly framePixelCoordinateSpace: "frame-px";
+    readonly framePixelPrecision: "word-page-local-calibration";
+    readonly scaleSource: "runtime-render-frame-page-rect";
+    readonly compositorReady: boolean;
   };
   readonly documents: readonly AdjacentGeometryDocumentSummary[];
   readonly numberingRows: readonly AdjacentGeometryNumberingRowSummary[];
@@ -301,7 +371,7 @@ export function summarizeAdjacentGeometryIntake(input: {
     ]),
   ].sort();
   return {
-    schemaVersion: "layer-05-adjacent-geometry-intake/v1",
+    schemaVersion: "layer-05-adjacent-geometry-intake/v2",
     generatedAtUtc: input.generatedAtUtc,
     sourceRuns: input.sourceRuns,
     totals: {
@@ -347,6 +417,15 @@ export function summarizeAdjacentGeometryIntake(input: {
       numberingUiaRowsWithL04FrameProjection: numberingRows.filter(
         (row) => hasNumberingUiaCapture(row) && hasL04FrameProjection(row),
       ).length,
+      numberingRowsWithFramePixelProjection: numberingRows.filter(
+        hasFramePixelProjection,
+      ).length,
+      numberingUiaRowsWithFramePixelProjection: numberingRows.filter(
+        (row) => hasNumberingUiaCapture(row) && hasFramePixelProjection(row),
+      ).length,
+      numberingCompositorReadyRows: numberingRows.filter(
+        (row) => row.pageLocalGeometry.compositorReady,
+      ).length,
       fieldRegionRows: fieldRegionRows.length,
       fieldRegionRowsWithRuntimeId: fieldRegionRows.filter(
         (row) => row.runtimeFieldRegionId !== undefined,
@@ -373,6 +452,15 @@ export function summarizeAdjacentGeometryIntake(input: {
       fieldRegionUiaRowsWithL04FrameProjection: fieldRegionRows.filter(
         (row) => row.resultLineRectCount > 0 && hasL04FrameProjection(row),
       ).length,
+      fieldRegionRowsWithFramePixelProjection: fieldRegionRows.filter(
+        hasFramePixelProjection,
+      ).length,
+      fieldRegionUiaRowsWithFramePixelProjection: fieldRegionRows.filter(
+        (row) => row.resultLineRectCount > 0 && hasFramePixelProjection(row),
+      ).length,
+      fieldRegionCompositorReadyRows: fieldRegionRows.filter(
+        (row) => row.pageLocalGeometry.compositorReady,
+      ).length,
     },
     routing: {
       routedTo: "L05",
@@ -387,7 +475,12 @@ export function summarizeAdjacentGeometryIntake(input: {
       requiredUpstreamFact: "L04 frame-to-pixel projection",
       l04FrameProjectionCoordinateSpace: "l04-frame-twips",
       l04FrameProjectionPrecision: "word-page-local-calibration",
-      compositorReady: false,
+      framePixelCoordinateSpace: "frame-px",
+      framePixelPrecision: "word-page-local-calibration",
+      scaleSource: "runtime-render-frame-page-rect",
+      compositorReady:
+        numberingRows.some((row) => row.pageLocalGeometry.compositorReady) ||
+        fieldRegionRows.some((row) => row.pageLocalGeometry.compositorReady),
     },
     documents: docIds.map((docId) =>
       summarizeDocument(
@@ -499,6 +592,7 @@ function summarizeNumberingRows(
         textColumn,
         pageFramesByDocId,
       });
+      const framePixelProjection = projectNumberingToFramePixels(l04FrameProjection);
       const pageLocalGeometry: AdjacentGeometryPageLocalNumberingGeometry = {
         wordPage: wordStartPage,
         normalizedWordPageIndex,
@@ -508,6 +602,8 @@ function summarizeNumberingRows(
         markerLane,
         textColumn,
         l04FrameProjection,
+        framePixelProjection,
+        compositorReady: framePixelProjection.status === "projected-frame-pixels",
         coordinateSpace: "word-page-twips",
         precision: "word-page-local-calibration",
         normalizationStatus:
@@ -555,6 +651,7 @@ function summarizeNumberingRows(
         markerLane,
         textColumn,
         pageLocalGeometry,
+        compositorReady: pageLocalGeometry.compositorReady,
         rangeMappingMethod:
           stringValue(uiaRow.rangeMappingMethod) ?? stringValue(row.rangeMappingMethod),
         coordinateSpace: "screen-px" as const,
@@ -662,6 +759,7 @@ function summarizeFieldRegionRows(
         wordPlacement,
         pageFramesByDocId,
       });
+      const framePixelProjection = projectFieldToFramePixels(l04FrameProjection);
       const pageLocalGeometry: AdjacentGeometryPageLocalFieldGeometry = {
         expectedPageSpan,
         normalizedWordPageIndexSpan,
@@ -670,6 +768,8 @@ function summarizeFieldRegionRows(
         startAnchorTwips: wordPlacement?.startXYTwips,
         endAnchorTwips: wordPlacement?.endXYTwips,
         l04FrameProjection,
+        framePixelProjection,
+        compositorReady: framePixelProjection.status === "projected-frame-pixels",
         coordinateSpace: "word-page-twips",
         precision: "word-page-local-calibration",
         normalizationStatus:
@@ -699,6 +799,7 @@ function summarizeFieldRegionRows(
         runtimePageSpan,
         expectedPageSpan,
         pageLocalGeometry,
+        compositorReady: pageLocalGeometry.compositorReady,
         instructionFamily:
           stringValue(liveJoin.instructionFamily) ??
           stringValue(targetJoin.instructionFamily),
@@ -765,6 +866,14 @@ function summarizeDocument(
     numberingUiaRowsWithL04FrameProjection: numberingRows.filter(
       (row) => hasNumberingUiaCapture(row) && hasL04FrameProjection(row),
     ).length,
+    numberingRowsWithFramePixelProjection: numberingRows.filter(
+      hasFramePixelProjection,
+    ).length,
+    numberingUiaRowsWithFramePixelProjection: numberingRows.filter(
+      (row) => hasNumberingUiaCapture(row) && hasFramePixelProjection(row),
+    ).length,
+    numberingCompositorReadyRows: numberingRows.filter((row) => row.compositorReady)
+      .length,
     fieldRegionRows: fieldRegionRows.length,
     fieldRegionRowsWithRuntimeId: fieldRegionRows.filter(
       (row) => row.runtimeFieldRegionId !== undefined,
@@ -791,6 +900,14 @@ function summarizeDocument(
     fieldRegionUiaRowsWithL04FrameProjection: fieldRegionRows.filter(
       (row) => row.resultLineRectCount > 0 && hasL04FrameProjection(row),
     ).length,
+    fieldRegionRowsWithFramePixelProjection: fieldRegionRows.filter(
+      hasFramePixelProjection,
+    ).length,
+    fieldRegionUiaRowsWithFramePixelProjection: fieldRegionRows.filter(
+      (row) => row.resultLineRectCount > 0 && hasFramePixelProjection(row),
+    ).length,
+    fieldRegionCompositorReadyRows: fieldRegionRows.filter((row) => row.compositorReady)
+      .length,
   };
 }
 
@@ -800,6 +917,12 @@ function hasL04FrameProjection(
   return row.pageLocalGeometry.l04FrameProjection.status === "projected-l04-frame";
 }
 
+function hasFramePixelProjection(
+  row: AdjacentGeometryNumberingRowSummary | AdjacentGeometryFieldRegionRowSummary,
+): boolean {
+  return row.pageLocalGeometry.framePixelProjection.status === "projected-frame-pixels";
+}
+
 function hasNumberingUiaCapture(row: AdjacentGeometryNumberingRowSummary): boolean {
   return (
     row.paragraphLineRectCount > 0 ||
@@ -822,12 +945,28 @@ function collectPageFramesByDocId(
       if (pageIndex === undefined) continue;
       const frame = record(page.frame);
       const physicalBoundsTwips = normalizeTwipsRect(frame.physicalBoundsTwips);
+      const renderFrame = record(page.renderFrame);
+      const renderPageFrame = normalizeFramePxRect(renderFrame.frame);
+      const renderFrameRevision = numberValue(renderFrame.revision);
+      const zoomPxPerTwip =
+        numberValue(record(page.renderZoom).pxPerTwip) ??
+        numberValue(renderFrame.zoomPxPerTwip);
+      const frameId = stringValue(frame.frameId);
       const pageFrame: AdjacentGeometryPageFrame = {
         pageId: stringValue(page.pageId),
         pageIndex,
-        frameId: stringValue(frame.frameId),
+        frameId,
         completeness: stringValue(frame.completeness),
         physicalBoundsTwips,
+        framePixelScale: buildFramePixelScale({
+          pageIndex,
+          pageId: stringValue(page.pageId),
+          frameId,
+          physicalBoundsTwips,
+          renderPageFrame,
+          renderFrameRevision,
+          zoomPxPerTwip,
+        }),
       };
       let docFrames = byDocId.get(docId);
       if (!docFrames) {
@@ -840,6 +979,48 @@ function collectPageFramesByDocId(
   return byDocId;
 }
 
+function buildFramePixelScale(input: {
+  readonly pageIndex: number;
+  readonly pageId?: string;
+  readonly frameId?: string;
+  readonly physicalBoundsTwips?: AdjacentGeometryTwipsRect;
+  readonly renderPageFrame?: AdjacentGeometryFramePxRect;
+  readonly renderFrameRevision?: number;
+  readonly zoomPxPerTwip?: number;
+}): AdjacentGeometryFramePixelScale | undefined {
+  const physicalBounds = input.physicalBoundsTwips;
+  const renderPageFrame = input.renderPageFrame;
+  if (!physicalBounds || !renderPageFrame) return undefined;
+  if (
+    physicalBounds.xTwips === undefined ||
+    physicalBounds.yTwips === undefined ||
+    physicalBounds.widthTwips === undefined ||
+    physicalBounds.heightTwips === undefined ||
+    physicalBounds.widthTwips <= 0 ||
+    physicalBounds.heightTwips <= 0
+  ) {
+    return undefined;
+  }
+  const pxPerTwipX = renderPageFrame.widthPx / physicalBounds.widthTwips;
+  const pxPerTwipY = renderPageFrame.heightPx / physicalBounds.heightTwips;
+  if (!isFinitePositive(pxPerTwipX) || !isFinitePositive(pxPerTwipY)) {
+    return undefined;
+  }
+  return {
+    source: "runtime-render-frame-page-rect",
+    pageIndex: input.pageIndex,
+    pageId: input.pageId,
+    frameId: input.frameId,
+    renderFrameRevision: input.renderFrameRevision,
+    renderPageFrame,
+    physicalBoundsTwips: physicalBounds,
+    pxPerTwipX,
+    pxPerTwipY,
+    zoomPxPerTwip:
+      input.zoomPxPerTwip === undefined ? undefined : roundNumber(input.zoomPxPerTwip),
+  };
+}
+
 function collectNumberingRuntimeReadbacks(
   artifacts: readonly unknown[],
 ): Map<string, Record<string, unknown>> {
@@ -911,6 +1092,7 @@ function projectNumberingToL04Frame(input: {
     frameId: frame.frameId,
     frameCompleteness: frame.completeness,
     physicalBoundsTwips: frame.physicalBoundsTwips,
+    framePixelScale: frame.framePixelScale,
     markerLane: addFrameOrigin(input.markerLane, frame.physicalBoundsTwips),
     textColumn: addFrameOrigin(input.textColumn, frame.physicalBoundsTwips),
     coordinateSpace: "l04-frame-twips",
@@ -957,6 +1139,7 @@ function projectFieldToL04Frame(input: {
     frameId: frame.frameId,
     frameCompleteness: frame.completeness,
     physicalBoundsTwips: frame.physicalBoundsTwips,
+    framePixelScale: frame.framePixelScale,
     fieldStartAnchorTwips: addFrameOriginToPoint(
       input.wordPlacement.startXYTwips,
       frame.physicalBoundsTwips,
@@ -971,6 +1154,65 @@ function projectFieldToL04Frame(input: {
   };
 }
 
+function projectNumberingToFramePixels(
+  projection: AdjacentGeometryL04FrameProjection,
+): AdjacentGeometryFramePixelProjection {
+  if (projection.status !== "projected-l04-frame") {
+    return baseFramePixelProjection("awaiting-l04-frame-projection", projection);
+  }
+  const scale = projectionScale(projection);
+  if (!scale) return baseFramePixelProjection("missing-frame-pixel-scale", projection);
+  const markerLane = l04FrameTwipsRectToFramePx(projection.markerLane, scale);
+  const textColumn = l04FrameTwipsRectToFramePx(projection.textColumn, scale);
+  if (!markerLane) {
+    return baseFramePixelProjection("missing-l04-frame-rect", projection, scale);
+  }
+  return {
+    pageIndex: projection.pageIndex,
+    pageId: projection.pageId,
+    frameId: projection.frameId,
+    scale,
+    markerLane,
+    textColumn,
+    coordinateSpace: "frame-px",
+    precision: "word-page-local-calibration",
+    status: "projected-frame-pixels",
+  };
+}
+
+function projectFieldToFramePixels(
+  projection: AdjacentGeometryL04FrameProjection,
+): AdjacentGeometryFramePixelProjection {
+  if (projection.status !== "projected-l04-frame") {
+    return baseFramePixelProjection("awaiting-l04-frame-projection", projection);
+  }
+  const scale = projectionScale(projection);
+  if (!scale) return baseFramePixelProjection("missing-frame-pixel-scale", projection);
+  const fieldStartAnchorPx = l04FrameTwipsPointToFramePx(
+    projection.fieldStartAnchorTwips,
+    scale,
+  );
+  const fieldEndAnchorPx = l04FrameTwipsPointToFramePx(
+    projection.fieldEndAnchorTwips,
+    scale,
+  );
+  if (!fieldStartAnchorPx || !fieldEndAnchorPx) {
+    return baseFramePixelProjection("missing-l04-field-anchor", projection, scale);
+  }
+  return {
+    pageIndex: projection.pageIndex,
+    pageId: projection.pageId,
+    frameId: projection.frameId,
+    scale,
+    fieldStartAnchorPx,
+    fieldEndAnchorPx,
+    fieldResultRangePx: rangeRectFromPoints(fieldStartAnchorPx, fieldEndAnchorPx),
+    coordinateSpace: "frame-px",
+    precision: "word-page-local-calibration",
+    status: "projected-frame-pixels",
+  };
+}
+
 function baseFrameProjection(
   status: AdjacentGeometryL04FrameProjection["status"],
   pageIndex?: number,
@@ -983,6 +1225,22 @@ function baseFrameProjection(
   };
 }
 
+function baseFramePixelProjection(
+  status: AdjacentGeometryFramePixelProjection["status"],
+  projection: AdjacentGeometryL04FrameProjection,
+  scale?: AdjacentGeometryFramePixelScale,
+): AdjacentGeometryFramePixelProjection {
+  return {
+    pageIndex: projection.pageIndex,
+    pageId: projection.pageId,
+    frameId: projection.frameId,
+    scale,
+    coordinateSpace: "frame-px",
+    precision: "word-page-local-calibration",
+    status,
+  };
+}
+
 function pageFrameFor(
   pageFramesByDocId: ReadonlyMap<string, ReadonlyMap<number, AdjacentGeometryPageFrame>>,
   docId: string,
@@ -991,6 +1249,12 @@ function pageFrameFor(
   return pageIndex === undefined ? undefined : pageFramesByDocId.get(docId)?.get(pageIndex);
 }
 
+function projectionScale(
+  projection: AdjacentGeometryL04FrameProjection,
+): AdjacentGeometryFramePixelScale | undefined {
+  return projection.framePixelScale;
+}
+
 function addFrameOrigin(
   rect: AdjacentGeometryTwipsRect | undefined,
   frame: AdjacentGeometryTwipsRect,
@@ -1027,6 +1291,77 @@ function addFrameOriginToPoint(
   };
 }
 
+function l04FrameTwipsRectToFramePx(
+  rect: AdjacentGeometryTwipsRect | undefined,
+  scale: AdjacentGeometryFramePixelScale,
+): AdjacentGeometryFramePxRect | undefined {
+  if (
+    !rect ||
+    rect.xTwips === undefined ||
+    rect.yTwips === undefined ||
+    rect.widthTwips === undefined ||
+    rect.heightTwips === undefined ||
+    scale.physicalBoundsTwips.xTwips === undefined ||
+    scale.physicalBoundsTwips.yTwips === undefined
+  ) {
+    return undefined;
+  }
+  return {
+    leftPx: roundNumber(
+      scale.renderPageFrame.leftPx +
+        (rect.xTwips - scale.physicalBoundsTwips.xTwips) * scale.pxPerTwipX,
+    ),
+    topPx: roundNumber(
+      scale.renderPageFrame.topPx +
+        (rect.yTwips - scale.physicalBoundsTwips.yTwips) * scale.pxPerTwipY,
+    ),
+    widthPx: roundNumber(Math.max(0, rect.widthTwips * scale.pxPerTwipX)),
+    heightPx: roundNumber(Math.max(0, rect.heightTwips * scale.pxPerTwipY)),
+    coordinateSpace: "frame-px",
+  };
+}
+
+function l04FrameTwipsPointToFramePx(
+  point: { readonly x?: number; readonly y?: number } | undefined,
+  scale: AdjacentGeometryFramePixelScale,
+): AdjacentGeometryFramePxPoint | undefined {
+  if (
+    !point ||
+    point.x === undefined ||
+    point.y === undefined ||
+    scale.physicalBoundsTwips.xTwips === undefined ||
+    scale.physicalBoundsTwips.yTwips === undefined
+  ) {
+    return undefined;
+  }
+  return {
+    xPx: roundNumber(
+      scale.renderPageFrame.leftPx +
+        (point.x - scale.physicalBoundsTwips.xTwips) * scale.pxPerTwipX,
+    ),
+    yPx: roundNumber(
+      scale.renderPageFrame.topPx +
+        (point.y - scale.physicalBoundsTwips.yTwips) * scale.pxPerTwipY,
+    ),
+    coordinateSpace: "frame-px",
+  };
+}
+
+function rangeRectFromPoints(
+  start: AdjacentGeometryFramePxPoint,
+  end: AdjacentGeometryFramePxPoint,
+): AdjacentGeometryFramePxRect {
+  const leftPx = Math.min(start.xPx, end.xPx);
+  const topPx = Math.min(start.yPx, end.yPx);
+  return {
+    leftPx,
+    topPx,
+    widthPx: roundNumber(Math.abs(end.xPx - start.xPx)),
+    heightPx: roundNumber(Math.abs(end.yPx - start.yPx)),
+    coordinateSpace: "frame-px",
+  };
+}
+
 function classifyPageIndex(
   normalizedWordPageIndex: number | undefined,
   runtimePageIndex: number | undefined,
@@ -1098,6 +1433,31 @@ function normalizeRect(raw: unknown): AdjacentGeometryRect | undefined {
   };
 }
 
+function normalizeFramePxRect(
+  raw: unknown,
+): AdjacentGeometryFramePxRect | undefined {
+  const rect = record(raw);
+  const leftPx = numberValue(rect.leftPx);
+  const topPx = numberValue(rect.topPx);
+  const widthPx = numberValue(rect.widthPx);
+  const heightPx = numberValue(rect.heightPx);
+  if (
+    leftPx === undefined ||
+    topPx === undefined ||
+    widthPx === undefined ||
+    heightPx === undefined
+  ) {
+    return undefined;
+  }
+  return {
+    leftPx: roundNumber(leftPx),
+    topPx: roundNumber(topPx),
+    widthPx: roundNumber(widthPx),
+    heightPx: roundNumber(heightPx),
+    coordinateSpace: "frame-px",
+  };
+}
+
 function normalizeTwipsRect(raw: unknown):
   | {
       readonly xTwips?: number;
@@ -1256,6 +1616,14 @@ function numberValue(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
+function isFinitePositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+function roundNumber(value: number): number {
+  return Number.parseFloat(value.toFixed(6));
+}
+
 function nullableNumberValue(value: unknown): number | null | undefined {
   return value === null ? null : numberValue(value);
 }