@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/runtime/scopes/semantic-scope-types.ts

@@ -257,6 +257,19 @@ export interface AIIssueSummary {
   readonly severity: "info" | "warning" | "error";
   readonly status: "open" | "resolved";
   readonly createdAtUtc?: string;
+  readonly statusUpdatedAtUtc?: string;
+  readonly resolvedAtUtc?: string;
+  readonly resolvedBy?: string;
+  readonly reopenedAtUtc?: string;
+  readonly reopenedBy?: string;
+  readonly lastTransition?: {
+    readonly action: "resolve" | "reopen";
+    readonly actorId: string;
+    readonly at: string;
+    readonly origin: string;
+    readonly fromStatus: "open" | "resolved";
+    readonly toStatus: "open" | "resolved";
+  };
 }
 
 export interface ScopeBundleEvidence {
@@ -264,6 +277,37 @@ export interface ScopeBundleEvidence {
   readonly reviewItemIds?: readonly string[];
   readonly overlappingWorkflowScopeIds?: readonly string[];
   readonly compatibilityFlags?: readonly string[];
+  /**
+   * Layout evidence projected from L04/L05 join surfaces when present.
+   * Missing layout truth is represented explicitly; Layer 08 does not infer
+   * page slices, continuation, or divergence rows from content or DOM state.
+   */
+  readonly layout?: ScopeLayoutEvidence;
+  /**
+   * Geometry envelope evidence projected from Layer 05 when a geometry facet
+   * is wired. Missing/cold geometry is represented explicitly as
+   * `requires-rehydration` or `unavailable`; Layer 08 never fabricates rects.
+   */
+  readonly geometry?: ScopeGeometryEvidence;
+  /**
+   * Presentation hint only. Consumers may use this to choose a cheap inline
+   * treatment for field-like scopes versus a broader overlay treatment for
+   * everything else, but it is not layout or geometry authority.
+   */
+  readonly visualization?: ScopeVisualizationHint;
+  /**
+   * Current action capability verdicts for this scope. These are evidence
+   * only: they explain what the shipped compiler/runtime can lower today
+   * without broadening the mutation surface.
+   */
+  readonly capabilities?: ScopeCapabilities;
+  /**
+   * Content-control / SDT overlap evidence. These are preserve-first wrapper
+   * facts: when present on a target scope, replacement capability verdicts and
+   * validation must surface blockers instead of treating the wrapper like
+   * ordinary editable text.
+   */
+  readonly contentControls?: ScopeContentControlEvidence;
   /**
    * Agent-authored explanations on this scope, read back from Layer-06
    * metadata entries keyed by `metadataId: "ai.explanation"`. Adversarial-
@@ -279,6 +323,192 @@ export interface ScopeBundleEvidence {
   readonly aiIssues?: readonly AIIssueSummary[];
 }
 
+export type ScopeEvidenceAvailability =
+  | "available"
+  | "partial"
+  | "degraded"
+  | "requires-rehydration"
+  | "unavailable";
+
+export interface ScopeLayoutContinuationEvidence {
+  readonly pageIds?: readonly string[];
+  readonly pageCount?: number;
+  readonly crossesPageBoundary?: boolean;
+  readonly continuedFromPreviousPage?: boolean;
+  readonly continuesToNextPage?: boolean;
+}
+
+export interface ScopeTableFramePageEvidence {
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly fragmentId: string;
+  readonly rowRange?: {
+    readonly from: number;
+    readonly to: number;
+    readonly totalRows: number;
+  };
+  readonly continuesFromPreviousPage?: boolean;
+  readonly continuesToNextPage?: boolean;
+  readonly repeatedHeaderRowIndexes?: readonly number[];
+  readonly splitRowCarry?: readonly {
+    readonly rowIndex: number;
+    readonly continuesFromPreviousPage: boolean;
+    readonly continuesToNextPage: boolean;
+  }[];
+  readonly verticalMergeCarry?: readonly {
+    readonly columnIndex: number;
+    readonly restartRowIndex: number;
+  }[];
+}
+
+export interface ScopeTableFrameEvidence {
+  readonly source: "runtime.layout.table-frame-continuation";
+  readonly blockId: string;
+  readonly scopeKind: "table" | "table-row" | "table-cell";
+  readonly rowIndex?: number;
+  readonly cellIndex?: number;
+  readonly pageIds?: readonly string[];
+  readonly pageSliceIds?: readonly string[];
+  readonly layoutObjectIds?: readonly string[];
+  readonly rowRangesByPage?: readonly ScopeTableFramePageEvidence[];
+  readonly repeatedHeaderRowIndexes?: readonly number[];
+  readonly splitRowCarry?: readonly {
+    readonly rowIndex: number;
+    readonly continuesFromPreviousPage: boolean;
+    readonly continuesToNextPage: boolean;
+  }[];
+  readonly verticalMergeCarry?: readonly {
+    readonly columnIndex: number;
+    readonly restartRowIndex: number;
+  }[];
+}
+
+export interface ScopeLayoutEvidence {
+  readonly status: ScopeEvidenceAvailability;
+  readonly completeness:
+    | "complete"
+    | "partial"
+    | "degraded"
+    | "requires-rehydration"
+    | "unavailable";
+  readonly reason?: string;
+  readonly pageSliceIds?: readonly string[];
+  readonly layoutObjectIds?: readonly string[];
+  readonly continuationState?: ScopeLayoutContinuationEvidence;
+  readonly divergenceIds?: readonly string[];
+  readonly tableFrame?: ScopeTableFrameEvidence;
+}
+
+export type ScopeGeometryEvidenceStatus =
+  | "available"
+  | "requires-rehydration"
+  | "unavailable";
+
+export type ScopeGeometryEvidencePrecision =
+  | "exact"
+  | "within-tolerance"
+  | "heuristic";
+
+export interface ScopeGeometryEvidenceRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly space: "twips" | "frame" | "overlay";
+  readonly precision?: ScopeGeometryEvidencePrecision;
+}
+
+export interface ScopeGeometryEvidence {
+  readonly status: ScopeGeometryEvidenceStatus;
+  readonly requiresRehydration: boolean;
+  readonly reason?: string;
+  readonly pageIds?: readonly string[];
+  readonly confidence?: "exact" | "medium" | "detached";
+  readonly precision?: ScopeGeometryEvidencePrecision;
+  readonly rects?: readonly ScopeGeometryEvidenceRect[];
+  readonly attachPoint?: {
+    readonly x: number;
+    readonly y: number;
+    readonly space: "twips" | "frame" | "overlay";
+  };
+  readonly linesCrossed?: number;
+  readonly continuationState?: ScopeLayoutContinuationEvidence;
+  readonly sourceIdentity?: {
+    readonly storyKey?: string;
+    readonly blockPath?: string;
+    readonly tableKey?: string;
+    readonly rowKey?: string;
+    readonly cellKey?: string;
+    readonly scopeKey?: string;
+    readonly scopeId?: string;
+    readonly objectKey?: string;
+    readonly inlinePath?: string;
+    readonly objectKind?: string;
+    readonly editPosture?: string;
+    readonly joinKind?: string;
+  };
+}
+
+export type ScopeVisualizationClass = "field" | "broad";
+
+export interface ScopeVisualizationHint {
+  readonly class: ScopeVisualizationClass;
+  readonly reason: string;
+}
+
+export type ScopeCapabilityStatus =
+  | "supported"
+  | "blocked"
+  | "unsupported"
+  | "degraded";
+
+/**
+ * Action posture for compiler consumers that need to distinguish "warn and
+ * proceed" from a real refusal. L08 must prefer `warn-and-proceed` whenever
+ * the mutation can be lowered without losing preserved truth or fabricating
+ * layout/geometry. `hard-refusal` means the action must not dispatch.
+ */
+export type ScopeActionPosture =
+  | "supported"
+  | "warn-and-proceed"
+  | "hard-refusal";
+
+export interface ScopeCapabilityVerdict {
+  readonly supported: boolean;
+  readonly status: ScopeCapabilityStatus;
+  readonly posture?: ScopeActionPosture;
+  readonly reason?: string;
+  readonly blockers?: readonly string[];
+  readonly warnings?: readonly string[];
+}
+
+export interface ScopeCapabilities {
+  readonly canReplaceText: ScopeCapabilityVerdict;
+  readonly canReplaceFragment: ScopeCapabilityVerdict;
+  readonly canInsertBefore: ScopeCapabilityVerdict;
+  readonly canInsertAfter: ScopeCapabilityVerdict;
+  readonly canApplyFormatting: ScopeCapabilityVerdict;
+  readonly canClearFormattingLayer: ScopeCapabilityVerdict;
+  readonly canAttachMetadata: ScopeCapabilityVerdict;
+}
+
+export type ScopeContentControlEvidenceStatus = "none" | "present";
+
+export interface ScopeContentControlEvidenceEntry {
+  readonly evidenceId: string;
+  readonly blockIndex: number;
+  readonly sdtType?: string;
+  readonly alias?: string;
+  readonly tag?: string;
+  readonly lock?: string;
+}
+
+export interface ScopeContentControlEvidence {
+  readonly status: ScopeContentControlEvidenceStatus;
+  readonly count: number;
+  readonly entries: readonly ScopeContentControlEvidenceEntry[];
+}
+
 export interface ScopeBundle {
   readonly scope: SemanticScope;
   readonly neighborhood: ScopeBundleNeighborhood;
@@ -286,11 +516,19 @@ export interface ScopeBundle {
   readonly generatedAtUtc: string;
 }
 
-export type ReplacementOperationKind =
+export type ScopeReplacementOperationKind =
   | "replace"
   | "insert-before"
-  | "insert-after"
-  | "split"
+  | "insert-after";
+
+/**
+ * Compiler-internal proposal operation. Public replacement surfaces accept
+ * `ScopeReplacementOperationKind`; `annotate` is retained only for metadata
+ * write audit records (`ai.attachExplanation` / `ai.createIssue`) that reuse
+ * the `ScopeActionAudit` shape without going through text replacement.
+ */
+export type ReplacementOperationKind =
+  | ScopeReplacementOperationKind
   | "annotate";
 
 export interface ReplacementPreservePolicy {
@@ -426,6 +664,7 @@ export interface ValidationApproval {
  */
 export interface ValidationResult {
   readonly safe: boolean;
+  readonly posture?: ScopeActionPosture;
   readonly blockedReasons: readonly string[];
   readonly warnings: readonly ValidationIssue[];
   readonly approval?: ValidationApproval;

package/src/runtime/scopes/visualization.ts

@@ -0,0 +1,28 @@
+/**
+ * Scope visualization hint projection.
+ *
+ * This is deliberately evidence, not geometry. Layer 08 can tell consumers
+ * whether a scope is structurally field-like or broad; Layer 05 remains the
+ * authority for rects, line spans, and overlay envelopes.
+ */
+
+import type {
+  ScopeVisualizationHint,
+  SemanticScope,
+} from "./semantic-scope-types.ts";
+
+export function deriveScopeVisualization(
+  scope: SemanticScope,
+): ScopeVisualizationHint {
+  if (scope.kind === "field") {
+    return {
+      class: "field",
+      reason: "kind:field",
+    };
+  }
+
+  return {
+    class: "broad",
+    reason: `kind:${scope.kind}`,
+  };
+}

package/src/runtime/surface-projection.ts

@@ -149,7 +149,7 @@ export interface SurfaceProjectionOptions {
    * if you call `createEditorSurfaceSnapshot` directly, normalize first.
    */
   viewportBlockRanges?: readonly { start: number; end: number }[] | null;
-  /** @deprecated use `viewportBlockRanges`. Kept for back-compat; wrapped into a 1-element array when supplied alone. */
+  /** @deprecated use `viewportBlockRanges`. Kept for back-compat; remove after the next published API pin refresh. */
   viewportBlockRange?: { start: number; end: number } | null;
   /**
    * Active markup mode. When set together with the document's
@@ -444,7 +444,9 @@ function createSurfaceBlock(
   }
 
   if (block.type === "sdt") {
-    const descriptor = describeStructuredWrapperBlock(block);
+    const descriptor = describeStructuredWrapperBlock(block, {
+      projectVisibleTocContentControls: true,
+    });
     if (descriptor) {
       const blockId = `sdt-wrapper-${counters.sdt}`;
       counters.sdt += 1;
@@ -1086,6 +1088,12 @@ function createSdtBlock(
   const children: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
   let innerCursor = cursor;
+  const descriptor = describeStructuredWrapperBlock(block);
+  const recursableBlockedReasonCode = descriptor
+    ? isBlockedImportFeatureKey(descriptor.featureKey)
+      ? "workflow_blocked_import"
+      : "workflow_preserve_only"
+    : getRecursableSdtBlockedReasonCode(block);
 
   for (const child of block.children) {
     const result = createSurfaceBlock(
@@ -1112,11 +1120,21 @@ function createSdtBlock(
       ...(block.properties.alias ? { alias: block.properties.alias } : {}),
       ...(block.properties.tag ? { tag: block.properties.tag } : {}),
       ...(block.properties.lock ? { lock: block.properties.lock } : {}),
+      ...(recursableBlockedReasonCode
+        ? { blockedReasonCode: recursableBlockedReasonCode }
+        : {}),
       ...(block.properties.checkbox ? { checkboxChecked: block.properties.checkbox.checked } : {}),
       ...(block.properties.datePicker?.fullDate ? { dateValue: block.properties.datePicker.fullDate } : {}),
       ...(block.properties.dropdownList ? { dropdownItems: block.properties.dropdownList } : {}),
       ...(block.properties.comboBox ? { comboBoxItems: block.properties.comboBox } : {}),
       ...(block.properties.showingPlcHdr ? { showingPlcHdr: true } : {}),
+      ...(descriptor
+        ? {
+            label: descriptor.label,
+            detail: descriptor.detail,
+            featureKey: descriptor.featureKey,
+          }
+        : {}),
       children,
     },
     lockedFragmentIds,
@@ -1124,6 +1142,24 @@ function createSdtBlock(
   };
 }
 
+function getRecursableSdtBlockedReasonCode(
+  block: Mutable<SdtNode>,
+): "workflow_preserve_only" | null {
+  const searchText = [
+    block.properties.alias,
+    block.properties.tag,
+    block.properties.sdtType,
+    block.properties.propertiesXml,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+
+  return searchText.includes("table of contents") || /\btoc\b/u.test(searchText)
+    ? "workflow_preserve_only"
+    : null;
+}
+
 function createParagraphBlock(
   paragraphIndex: number,
   paragraph: Mutable<ParagraphNode>,
@@ -1562,6 +1598,7 @@ function appendInlineSegments(
         });
         return { nextCursor: start + 1, lockedFragmentIds: [] };
       }
+      const objectAnchor = surfaceAnchorFromGeometry(node.anchor);
       if (c.type === "chart_preview") {
         const parsedChartId = registerParsedChartPreview(c, document);
         return appendComplexPreviewSegment(
@@ -1573,7 +1610,7 @@ function appendInlineSegments(
           {
             previewMediaId: c.previewMediaId,
             parsedChartId,
-            anchor: surfaceAnchorFromGeometry(node.anchor),
+            ...(objectAnchor ? { anchor: objectAnchor } : {}),
           },
         );
       }
@@ -1586,7 +1623,7 @@ function appendInlineSegments(
           `DrawingFrame smartart_preview (${node.anchor.wrapMode}).`,
           {
             previewMediaId: c.previewMediaId,
-            anchor: surfaceAnchorFromGeometry(node.anchor),
+            ...(objectAnchor ? { anchor: objectAnchor } : {}),
           },
         );
       }
@@ -1596,7 +1633,9 @@ function appendInlineSegments(
         start,
         "Drawing frame",
         `DrawingFrame ${c.type} (${node.anchor.wrapMode}).`,
-        { anchor: surfaceAnchorFromGeometry(node.anchor) },
+        {
+          ...(objectAnchor ? { anchor: objectAnchor } : {}),
+        },
       );
     }
     case "symbol":

package/src/runtime/telemetry/perf-probe.ts

@@ -0,0 +1,216 @@
+export type PerfProbeKind =
+  | "typing"
+  | "typing.predicted"
+  | "typing.reconcile"
+  | "typing.divergence"
+  | "selection"
+  | "runtime.create"
+  | "loadSession.laycacheProbe"
+  | "loadSession.compatReportCached"
+  | "snapshot.surface"
+  | "snapshot.compatibility"
+  | "snapshot.navigation"
+  | "pm.rebuild"
+  | "pm.decorations"
+  | "pm.decorations.apply"
+  | "pm.decorations.comments"
+  | "pm.decorations.revisions"
+  | "pm.decorations.workflow"
+  | "pm.mount"
+  | "shell.render"
+  | "workspace.chrome"
+  | "selection.sync"
+  | "layout.incremental"
+  | "layout.full"
+  | "render.frame_build"
+  | "render.frame_diff"
+  | "render.decoration_resolve"
+  | "chrome.overlay_reposition"
+  | "chrome.hit_test"
+  | "rail.segment_project";
+
+/**
+ * Counter names the FastTextEditLane emits via `incrementInvalidationCounter`.
+ * Expose them as a const so integrators can read the shape without duplicating
+ * strings.
+ */
+export const PREDICTED_LANE_COUNTERS = {
+  applied: "predictions.applied",
+  equivalent: "predictions.equivalent",
+  adjusted: "predictions.adjusted",
+  rejected: "predictions.rejected",
+  rollback: "predictions.rollback",
+  structuralDivergence: "predictions.structuralDivergence",
+  bailBeforePredict: "predictions.bailBeforePredict",
+  refreshSelectionOnly: "predictions.refresh.selectionOnly",
+  refreshLocalTextEquivalent: "predictions.refresh.localTextEquivalent",
+  refreshSurfaceOnly: "predictions.refresh.surfaceOnly",
+  refreshFullProjection: "predictions.refresh.fullProjection",
+  refreshBlocked: "predictions.refresh.blocked",
+} as const;
+
+export interface PerfProbeSample {
+  token: string;
+  kind: PerfProbeKind;
+  durationMs: number;
+  recordedAt: number;
+}
+
+interface PendingProbe {
+  kind: PerfProbeKind;
+  startedAt: number;
+}
+
+interface PerfProbeState {
+  enabled?: boolean;
+  nextToken?: number;
+  pending?: Record<string, PendingProbe>;
+  samples?: PerfProbeSample[];
+  maxSamples?: number;
+  invalidationCounts?: Record<string, number>;
+}
+
+export interface PerfProbeSummary {
+  samples: PerfProbeSample[];
+  latest: Partial<Record<PerfProbeKind, PerfProbeSample | null>>;
+  invalidationCounts: Record<string, number>;
+}
+
+declare global {
+  interface Window {
+    __DOCX_REACT_PERF_PROBE__?: PerfProbeState;
+  }
+}
+
+export function startPerfProbe(kind: PerfProbeKind): string | null {
+  const state = getEnabledState();
+  if (!state) {
+    return null;
+  }
+
+  const token = `${kind}-${state.nextToken ?? 0}`;
+  state.nextToken = (state.nextToken ?? 0) + 1;
+  state.pending ??= {};
+  state.pending[token] = {
+    kind,
+    startedAt: performance.now(),
+  };
+  return token;
+}
+
+export function finishPerfProbe(token: string | null | undefined): PerfProbeSample | null {
+  if (!token) {
+    return null;
+  }
+  const state = getEnabledState();
+  if (!state?.pending?.[token]) {
+    return null;
+  }
+
+  const pending = state.pending[token];
+  delete state.pending[token];
+
+  const sample: PerfProbeSample = {
+    token,
+    kind: pending.kind,
+    durationMs: performance.now() - pending.startedAt,
+    recordedAt: Date.now(),
+  };
+
+  pushSample(state, sample);
+
+  return sample;
+}
+
+export function recordPerfSample(
+  kind: PerfProbeKind,
+  durationMs = 0,
+): PerfProbeSample | null {
+  const state = getEnabledState();
+  if (!state) {
+    return null;
+  }
+
+  const token = `${kind}-${state.nextToken ?? 0}`;
+  state.nextToken = (state.nextToken ?? 0) + 1;
+  const sample: PerfProbeSample = {
+    token,
+    kind,
+    durationMs,
+    recordedAt: Date.now(),
+  };
+  pushSample(state, sample);
+  return sample;
+}
+
+export function incrementInvalidationCounter(
+  counter: string,
+  amount = 1,
+): number {
+  const state = getEnabledState();
+  if (!state) {
+    return 0;
+  }
+
+  state.invalidationCounts ??= {};
+  state.invalidationCounts[counter] =
+    (state.invalidationCounts[counter] ?? 0) + amount;
+  return state.invalidationCounts[counter]!;
+}
+
+export function getLatestPerfSummary(): PerfProbeSummary | null {
+  const state = getEnabledState();
+  const samples = state?.samples ?? [];
+  if (!state || samples.length === 0) {
+    return null;
+  }
+
+  return {
+    samples: [...samples],
+    latest: buildLatestSampleMap(samples),
+    invalidationCounts: { ...(state.invalidationCounts ?? {}) },
+  };
+}
+
+export function resetPerfProbeState(): void {
+  const state = getEnabledState();
+  if (!state) {
+    return;
+  }
+  state.nextToken = 0;
+  state.pending = {};
+  state.samples = [];
+  state.invalidationCounts = {};
+}
+
+function getEnabledState(): PerfProbeState | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  const state = window.__DOCX_REACT_PERF_PROBE__;
+  if (!state?.enabled) {
+    return null;
+  }
+  return state;
+}
+
+function pushSample(state: PerfProbeState, sample: PerfProbeSample): void {
+  state.samples ??= [];
+  state.samples.push(sample);
+  const maxSamples = state.maxSamples ?? 20;
+  if (state.samples.length > maxSamples) {
+    state.samples.splice(0, state.samples.length - maxSamples);
+  }
+}
+
+function buildLatestSampleMap(
+  samples: PerfProbeSample[],
+): Partial<Record<PerfProbeKind, PerfProbeSample | null>> {
+  const latest: Partial<Record<PerfProbeKind, PerfProbeSample | null>> = {};
+  for (const sample of [...samples].reverse()) {
+    if (latest[sample.kind] === undefined) {
+      latest[sample.kind] = sample;
+    }
+  }
+  return latest;
+}

package/src/runtime/virtualized-rendering.ts

@@ -35,6 +35,21 @@ export interface VirtualizedViewport {
   overscanHeight?: number;
 }
 
+export interface VirtualizedBlockGeometryProvider {
+  getBlock(blockId: string): { rects: readonly { topPx: number }[] } | null;
+}
+
+export interface ComputeVirtualizedWindowOptions {
+  /**
+   * Optional L05 geometry source. When present, `offsetTop` is derived from
+   * `GeometryFacet.getBlock(firstVisibleBlockId).rects[0].topPx` instead of
+   * the synthetic virtualization estimate. This keeps DOM-free consumers on
+   * geometry truth while preserving the legacy estimate for unwired tests and
+   * pre-paint sessions.
+   */
+  geometryFacet?: VirtualizedBlockGeometryProvider;
+}
+
 export interface VirtualizedWindow {
   startIndex: number;
   endIndex: number;
@@ -121,6 +136,7 @@ export function createVirtualizedRenderingSession(
 export function computeVirtualizedWindow(
   session: VirtualizedRenderingSession,
   viewport: VirtualizedViewport,
+  options: ComputeVirtualizedWindowOptions = {},
 ): VirtualizedWindow {
   if (session.metrics.length === 0) {
     return {
@@ -145,19 +161,38 @@ export function computeVirtualizedWindow(
   const safeEndIndex = Math.max(startIndex + 1, endIndexExclusive);
   const visibleMetrics = session.metrics.slice(startIndex, safeEndIndex);
   const visibleBlocks = session.blocks.slice(startIndex, safeEndIndex);
+  const firstMetric = visibleMetrics[0];
+  const firstBlock = visibleBlocks[0];
   const lastMetric = visibleMetrics[visibleMetrics.length - 1]!;
 
   return {
     startIndex,
     endIndex: safeEndIndex,
     totalHeight: session.totalHeight,
-    offsetTop: visibleMetrics[0]?.top ?? 0,
+    offsetTop: resolveWindowOffsetTop(
+      firstBlock?.blockId ?? firstMetric?.blockId,
+      firstMetric,
+      options,
+    ),
     offsetBottom: Math.max(0, session.totalHeight - lastMetric.bottom),
     visibleBlocks,
     visibleMetrics,
   };
 }
 
+function resolveWindowOffsetTop(
+  blockId: string | undefined,
+  fallbackMetric: VirtualizedRenderingMetrics | undefined,
+  options: ComputeVirtualizedWindowOptions,
+): number {
+  const geometryTop = blockId
+    ? options.geometryFacet?.getBlock(blockId)?.rects[0]?.topPx
+    : undefined;
+  return typeof geometryTop === "number" && Number.isFinite(geometryTop)
+    ? geometryTop
+    : (fallbackMetric?.top ?? 0);
+}
+
 function findFirstVisibleIndex(
   metrics: VirtualizedRenderingMetrics[],
   top: number,