@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/geometry/project-fragments.ts

@@ -0,0 +1,216 @@
+/**
+ * Layer 05 — Fragment projection helpers.
+ *
+ * Owns:
+ *   - `collectLineBoxesForRegion` — synthesize line boxes for header/footer/
+ *     column/footnote-area regions (body regions carry line boxes on the page
+ *     node already). Moved from `src/runtime/layout/public-facet.ts` in
+ *     refactor/05 Slice 2b.
+ *   - `resolveRegionEntry` — map a `PublicPageRegion["kind"]` + optional
+ *     column index onto the corresponding `RuntimePageRegion` on a node.
+ *     Moved from the same origin.
+ *   - `getBlockRectsFromFrame` — walk a `RenderFrame` and collect every
+ *     block fragment rect for a given `blockId`. New in Slice 2b; the
+ *     layout facet does not currently expose block-rect lists. Required by
+ *     `v3 runtime.geometry.getBlockRects` whose adapter promotes from
+ *     `mock` to `live-with-adapter` in Slice 5.
+ *
+ * Contracts:
+ *   - G5 — rects here are frame-local pixels (`space: "frame"`) because
+ *     the underlying `RenderFrameRect` is kernel-zoomed. Consumers that
+ *     need twip coordinates re-derive from layout, not from here.
+ *   - G6 — callers must route through the `GeometryFacet`, not reach in.
+ *
+ * Slices 4–5 add caret / envelope projection in sibling files.
+ */
+
+import type {
+  RuntimePageGraph,
+  RuntimePageNode,
+  RuntimePageRegion,
+} from "../layout/page-graph.ts";
+import type { PublicPageRegion } from "../layout/public-facet.ts";
+import type { RenderFrame } from "../render/index.ts";
+import type {
+  BlockGeometry,
+  GeometryRect,
+  PageGeometry,
+} from "./geometry-types.ts";
+
+// `lineBoxes` on `RuntimePageNode` is already strongly typed; alias it
+// locally so we don't re-import the raw `RuntimeLineBox` type just to
+// declare the helper's return shape.
+export type RuntimeLineBoxAlias = RuntimePageNode["lineBoxes"][number];
+
+export const EMPTY_LINE_BOXES: readonly RuntimeLineBoxAlias[] = Object.freeze(
+  [],
+);
+
+/**
+ * Collect raw line boxes for `region` on `node`. Body returns the node's
+ * precomputed `lineBoxes`; non-body regions synthesize line boxes from the
+ * region's fragment list (one entry per fragment, stacked vertically from a
+ * zero cursor). Multi-column layouts resolve against the requested
+ * `columnIndex`; footnote-area uses the first allocated footnote region on
+ * the page.
+ */
+export function collectLineBoxesForRegion(
+  node: RuntimePageNode,
+  region: PublicPageRegion["kind"],
+  graph: RuntimePageGraph,
+  columnIndex: number | undefined,
+): readonly RuntimeLineBoxAlias[] {
+  if (region === "body") {
+    return node.lineBoxes;
+  }
+  const regionEntry = resolveRegionEntry(node, region, columnIndex);
+  if (!regionEntry || regionEntry.fragmentIds.length === 0) {
+    return EMPTY_LINE_BOXES;
+  }
+  const fragmentsById = new Map(
+    graph.fragments.map((f) => [f.fragmentId, f] as const),
+  );
+  const result: RuntimeLineBoxAlias[] = [];
+  let cursorTwips = 0;
+  let lineIndex = 0;
+  for (const fragmentId of regionEntry.fragmentIds) {
+    const fragment = fragmentsById.get(fragmentId);
+    if (!fragment) continue;
+    const heightTwips = Math.max(1, fragment.heightTwips);
+    result.push({
+      fragmentId,
+      lineIndex: lineIndex++,
+      baselineTwips: cursorTwips + heightTwips,
+      heightTwips,
+      widthTwips: regionEntry.widthTwips,
+    });
+    cursorTwips += heightTwips;
+  }
+  return result;
+}
+
+export function resolveRegionEntry(
+  node: RuntimePageNode,
+  region: PublicPageRegion["kind"],
+  columnIndex: number | undefined,
+): RuntimePageRegion | undefined {
+  switch (region) {
+    case "header":
+      return node.regions.header;
+    case "footer":
+      return node.regions.footer;
+    case "column": {
+      const columns = node.regions.columns ?? [];
+      if (columns.length === 0) return undefined;
+      const idx = columnIndex ?? 0;
+      return columns[idx];
+    }
+    case "footnote-area": {
+      // Footnote area sits at the bottom of the body region per OOXML.
+      // Returns the first footnote region when allocated (page layouts
+      // allocate one block of footnotes per page today; multi-block
+      // layouts come later).
+      const footnoteRegionList = node.regions.footnotes;
+      if (footnoteRegionList && footnoteRegionList.length > 0) {
+        return footnoteRegionList[0];
+      }
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Collect every fragment rect for `blockId` from a `RenderFrame`. A block
+ * that spans multiple pages has one rect per page. Returns rects in
+ * page order, tagged `space: "frame"`. Empty when the frame is null, has
+ * no pages, or no fragment on any page carries the target blockId.
+ *
+ * New in Slice 2b. `v3 runtime.geometry.getBlockRects` promotes from
+ * `mock` to `live-with-adapter` against this implementation in Slice 5.
+ */
+export function getBlockRectsFromFrame(
+  frame: RenderFrame | null,
+  blockId: string,
+): readonly GeometryRect[] {
+  if (!frame) return [];
+  const rects: GeometryRect[] = [];
+  for (const page of frame.pages) {
+    const regions = [
+      page.regions.body,
+      page.regions.header,
+      page.regions.footer,
+      ...(page.regions.columns ?? []),
+      ...(page.regions.footnotes ?? []),
+    ];
+    for (const region of regions) {
+      if (!region) continue;
+      for (const block of region.blocks) {
+        if (block.fragment.blockId !== blockId) continue;
+        rects.push({
+          leftPx: block.frame.leftPx,
+          topPx: block.frame.topPx,
+          widthPx: block.frame.widthPx,
+          heightPx: block.frame.heightPx,
+          space: "frame",
+        });
+      }
+    }
+  }
+  return rects;
+}
+
+/**
+ * Project a page from a `RenderFrame` into a `PageGeometry`. Accepts
+ * either a numeric `pageIndex` or a string `pageId` (the same overload
+ * the public facet's `getPage` exposes). Returns `null` when the frame
+ * is null or the target page isn't in the current frame.
+ *
+ * New in Slice 3a — chrome overlays read page 0's `frame` via the
+ * geometry facet instead of calling `getBoundingClientRect` on the
+ * overlay root, closing the G2 violation.
+ */
+export function getPageFromFrame(
+  frame: RenderFrame | null,
+  target: number | string,
+): PageGeometry | null {
+  if (!frame) return null;
+  const page =
+    typeof target === "number"
+      ? frame.pages[target]
+      : frame.pages.find((p) => p.page.pageId === target);
+  if (!page) return null;
+  return {
+    pageId: page.page.pageId,
+    pageIndex: page.page.pageIndex,
+    frame: {
+      leftPx: page.frame.leftPx,
+      topPx: page.frame.topPx,
+      widthPx: page.frame.widthPx,
+      heightPx: page.frame.heightPx,
+      space: "frame",
+    },
+  };
+}
+
+/**
+ * Project a block from a `RenderFrame` into a `BlockGeometry` — wraps
+ * `getBlockRectsFromFrame` with the block id so consumers that want a
+ * named handle don't have to thread the id alongside the rect list.
+ * Returns `null` when the frame is null or no fragment on any page
+ * carries the target blockId.
+ *
+ * New in Slice 3a — scroll-anchor reads block rects via this helper
+ * (through the geometry facet) instead of walking the `offsetTop` /
+ * `offsetParent` chain, closing the G2 violation in
+ * `src/ui-tailwind/editor-surface/scroll-anchor.ts`.
+ */
+export function getBlockGeometryFromFrame(
+  frame: RenderFrame | null,
+  blockId: string,
+): BlockGeometry | null {
+  const rects = getBlockRectsFromFrame(frame, blockId);
+  if (rects.length === 0) return null;
+  return { blockId, rects };
+}

package/src/runtime/geometry/projector.ts

@@ -0,0 +1,129 @@
+/**
+ * Layer 05 — geometry debug projector.
+ *
+ * Produces a `GeometryDebugEntry` for the debug-inspector snapshot when
+ * the `layout` telemetry channel is on. Architecture reference:
+ * `docs/architecture/05-geometry-projection.md` §"Public facet".
+ *
+ * Mirrors `src/runtime/formatting/projector.ts` in spirit — strict about
+ * cost, gated by the bus channel toggle. Consumers must call
+ * `buildGeometryDebugEntry` only when `bus.isEnabled("layout")`.
+ *
+ * Slice-6 scope: minimum-viable summary — page count, frame revision,
+ * sampled block rects, caret resolution shape. Slice 6 does NOT wire
+ * the `geometry.projected` emit site on the layout-engine-instance
+ * recompute boundary — that is an edit-path perf concern (Performance
+ * Invariant 4) and lands alongside a perf-bench pair in a follow-up.
+ */
+
+import type { GeometryFacet } from "./geometry-facet.ts";
+
+export interface GeometryDebugCatalog {
+  /** Layout revision the snapshot was taken against (0 when unknown). */
+  readonly layoutRevision: number;
+  /** Number of pages in the kernel's current frame. */
+  readonly pageCount: number;
+  /** Total block rects across all pages sampled (bounded by `sampleLimit`). */
+  readonly sampledBlockRectCount: number;
+  /** Per-block pages the first sampled block spans (0 when no sample). */
+  readonly firstBlockPageSpan: number;
+}
+
+export interface GeometryDebugSample {
+  readonly blockId: string;
+  readonly pageCount: number;
+  readonly space: "twips" | "frame" | "overlay";
+}
+
+export interface GeometryDebugEntry {
+  readonly schemaVersion: 1;
+  readonly catalog: GeometryDebugCatalog;
+  /** Up to `sampleLimit` sampled blocks for the inspector UI. */
+  readonly samples: readonly GeometryDebugSample[];
+  /** Viewport snapshot at projection time (scrollTop/scrollLeft/dpr/zoom). */
+  readonly viewport: {
+    readonly scrollLeftPx: number;
+    readonly scrollTopPx: number;
+    readonly dpr: number;
+    readonly pxPerTwip: number;
+  };
+}
+
+export interface BuildGeometryDebugEntryInputs {
+  readonly facet: GeometryFacet;
+  /**
+   * Block ids to sample. When omitted, an empty sample list is emitted —
+   * consumers are expected to supply a bounded list (e.g. the visible
+   * page range's blocks) to keep the projector's cost proportional.
+   */
+  readonly sampleBlockIds?: readonly string[];
+  /**
+   * Maximum number of sampled rects materialized. Default 16 — enough
+   * for an inspector UI, small enough to keep projection O(1) even on
+   * large documents.
+   */
+  readonly sampleLimit?: number;
+  /**
+   * Layout revision the caller is inspecting. The facet does not expose
+   * the revision directly; pass it through from the layout engine when
+   * available. Defaults to 0.
+   */
+  readonly layoutRevision?: number;
+  /** Frame page count — passed in so the projector stays facet-only. */
+  readonly pageCount?: number;
+}
+
+const DEFAULT_SAMPLE_LIMIT = 16;
+
+export function buildGeometryDebugEntry(
+  inputs: BuildGeometryDebugEntryInputs,
+): GeometryDebugEntry {
+  const {
+    facet,
+    sampleBlockIds,
+    sampleLimit = DEFAULT_SAMPLE_LIMIT,
+    layoutRevision = 0,
+    pageCount = 0,
+  } = inputs;
+
+  const samples: GeometryDebugSample[] = [];
+  let sampledRectTotal = 0;
+  let firstBlockPageSpan = 0;
+
+  if (sampleBlockIds && sampleBlockIds.length > 0) {
+    const limit = Math.max(0, Math.min(sampleBlockIds.length, sampleLimit));
+    for (let i = 0; i < limit; i += 1) {
+      const blockId = sampleBlockIds[i]!;
+      const geometry = facet.getBlock(blockId);
+      if (!geometry) continue;
+      const rectCount = geometry.rects.length;
+      sampledRectTotal += rectCount;
+      if (samples.length === 0) firstBlockPageSpan = rectCount;
+      const firstSpace = geometry.rects[0]?.space ?? "frame";
+      samples.push({
+        blockId,
+        pageCount: rectCount,
+        space: firstSpace,
+      });
+    }
+  }
+
+  const viewport = facet.getViewport();
+
+  return {
+    schemaVersion: 1,
+    catalog: {
+      layoutRevision,
+      pageCount,
+      sampledBlockRectCount: sampledRectTotal,
+      firstBlockPageSpan,
+    },
+    samples,
+    viewport: {
+      scrollLeftPx: viewport.scrollLeftPx,
+      scrollTopPx: viewport.scrollTopPx,
+      dpr: viewport.dpr,
+      pxPerTwip: viewport.pxPerTwip,
+    },
+  };
+}

package/src/runtime/geometry/replacement-envelope.ts

@@ -0,0 +1,130 @@
+/**
+ * Layer 05 — Replacement envelope projection.
+ *
+ * A **replacement envelope** answers "what rects does this scope
+ * currently occupy?" so agent-facing replacement tooling can position
+ * chrome (overlays, confirmation cards, diff highlights) and know
+ * whether the scope is still resolvable. Architecture 05 G7:
+ *
+ *   > If scope S still resolves, `getReplacementEnvelope(S)` produces a
+ *   > rect bundle describing "the area occupied by this scope right
+ *   > now". This is the geometry input to layer 08 scope bundles.
+ *
+ * Slice-5 shape: a pure helper that accepts a resolved scope shape
+ * (`{kind: "range", from, to}` or `{kind: "detached", lastKnownRange}`)
+ * plus the render frame, and produces an `EnvelopeBundle`. The facet's
+ * `getReplacementEnvelope(scopeId)` combines `resolveScope(document,
+ * scopeId)` with this helper.
+ *
+ * Slice-5 substrate notes:
+ *
+ *   - `scopeRects` routes through `resolveSelectionRects` — i.e. the
+ *     same Slice-4 path that returns the kernel's union rect for
+ *     non-collapsed ranges. When per-line anchors ship in a later
+ *     slice, `scopeRects` upgrades to one-rect-per-line automatically.
+ *   - `linesCrossed` reflects the number of rects the helper produced,
+ *     which matches the plan's semantics ("how many lines the scope
+ *     crosses") once per-line enumeration is real. For Slice 5 it's
+ *     `1` whenever the scope resolved.
+ *   - **Wrap-aware envelopes** (scope adjacent to a floating image) are
+ *     deferred — the current render frame does not expose wrap region
+ *     metadata. The plan's `replacement-envelope-wrap-aware.test.ts`
+ *     is reserved for that slice.
+ */
+
+import type {
+  GeometryRect,
+  EnvelopeBundle,
+  GeometrySpace,
+} from "./geometry-types.ts";
+import type { RenderFrame } from "../render/index.ts";
+import { resolveSelectionRects } from "./caret-geometry.ts";
+import type { EditorStoryTarget } from "../../api/public-types";
+
+/**
+ * Scope shape the helper accepts. Mirrors a subset of
+ * `EditorAnchorProjection` from the runtime API so the helper stays
+ * dependency-free and consumers can pass either the runtime's
+ * resolveScope output directly or a hand-built range.
+ */
+export type ReplacementScope =
+  | { kind: "range"; from: number; to: number }
+  | {
+      kind: "detached";
+      lastKnownRange: { from: number; to: number };
+    };
+
+/**
+ * Resolve the replacement envelope for a scope against the current
+ * render frame. Returns `null` when `frame` is null or when the range
+ * is empty and the scope is not detached (detached scopes without a
+ * lastKnownRange still return null — nothing to anchor on).
+ *
+ * The envelope's `space` carries through from the rect projection; the
+ * attachPoint uses the same space.
+ */
+export function resolveReplacementEnvelope(
+  frame: RenderFrame | null,
+  scope: ReplacementScope,
+  story?: EditorStoryTarget,
+): EnvelopeBundle | null {
+  if (!frame) return null;
+
+  if (scope.kind === "range") {
+    const { from, to } = scope;
+    if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
+    const rects = resolveSelectionRects(frame, { from, to, story });
+    if (rects.length === 0) return null;
+    return buildBundle(rects, "exact");
+  }
+
+  // Detached: project the last-known range and tag confidence as such.
+  const { from, to } = scope.lastKnownRange;
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
+  const rects = resolveSelectionRects(frame, { from, to, story });
+  if (rects.length === 0) return null;
+  return buildBundle(rects, "detached");
+}
+
+function buildBundle(
+  rects: readonly GeometryRect[],
+  confidence: EnvelopeBundle["confidence"],
+): EnvelopeBundle {
+  const first = rects[0]!;
+  const space: GeometrySpace = first.space;
+  // Slice 7b (2026-04-22): derive envelope precision from the
+  // underlying rects — when `resolveSelectionRects` returned a single
+  // union rect (wrapped range) it carries `precision: "within-
+  // tolerance"`; when it returned a caret rect (collapsed range) the
+  // rect is untagged (`"exact"` by default). The envelope's own
+  // precision is the coarsest of its rects, biased toward
+  // `"heuristic"` when the scope is detached because the last-known
+  // range is a point-in-time snapshot that may no longer match the
+  // current doc.
+  const rectPrecision = coarsestRectPrecision(rects);
+  const envelopePrecision: EnvelopeBundle["precision"] =
+    confidence === "detached" ? "heuristic" : rectPrecision;
+  return {
+    scopeRects: rects,
+    attachPoint: {
+      xPx: first.leftPx,
+      yPx: first.topPx,
+      space,
+    },
+    confidence,
+    linesCrossed: rects.length,
+    precision: envelopePrecision,
+  };
+}
+
+function coarsestRectPrecision(
+  rects: readonly GeometryRect[],
+): "exact" | "within-tolerance" | "heuristic" {
+  let worst: "exact" | "within-tolerance" | "heuristic" = "exact";
+  for (const rect of rects) {
+    const p = rect.precision ?? "exact";
+    if (p === "heuristic") return "heuristic";
+    if (p === "within-tolerance" && worst === "exact") worst = "within-tolerance";
+  }
+  return worst;
+}

package/src/runtime/geometry/viewport.ts

@@ -0,0 +1,218 @@
+/**
+ * Layer 05 — Viewport model.
+ *
+ * This module is the **only** place permitted to read DOM viewport state
+ * (`scrollTop` / `scrollLeft`) and DPR. Contract G2 in
+ * `docs/architecture/05-geometry-projection.md` forbids every other file
+ * under `src/runtime/geometry/**` from reading DOM layout; the CI guard at
+ * `scripts/ci-check-geometry-no-dom-authority.mjs` enforces this by
+ * rejecting `getBoundingClientRect`, `offsetTop/Left/Width/Height`,
+ * `clientHeight`, and `offsetParent` outside this file. Slice 3 additionally
+ * permits this module to read viewport geometry from a host-supplied
+ * editor-root element.
+ *
+ * Slice 1: stub `createViewport()` returning a frozen no-DPR value.
+ * Slice 3 (this slice): adds `createViewportFromRoot(root, { pxPerTwip })`
+ *   which attaches passive scroll + resize listeners to the root, reads
+ *   `scrollLeft` / `scrollTop` only — per G2's viewport exception — and
+ *   emits a new `Viewport` to subscribers via rAF coalescing (performance
+ *   invariant 1). The stub `createViewport()` remains for tests and for
+ *   wiring sites that have not yet flipped to a real root.
+ */
+
+import type { Viewport, ViewportListener } from "./geometry-types.ts";
+
+export interface ViewportHandle {
+  getViewport(): Viewport;
+  subscribe(listener: ViewportListener): () => void;
+  /**
+   * Tear down any DOM listeners + cancel pending rAF frames. Always safe
+   * to call; no-op on the stub handle from `createViewport()`.
+   */
+  dispose(): void;
+}
+
+const DEFAULT_VIEWPORT: Viewport = {
+  scrollLeftPx: 0,
+  scrollTopPx: 0,
+  dpr: 1,
+  pxPerTwip: 0,
+};
+
+/**
+ * Slice 1 stub — preserved for tests and for Slice-2a-wired call sites
+ * that do not yet have a live editor root. Returns a frozen viewport and
+ * a no-op subscribe/dispose.
+ */
+export function createViewport(): ViewportHandle {
+  return {
+    getViewport() {
+      return DEFAULT_VIEWPORT;
+    },
+    subscribe() {
+      return () => {};
+    },
+    dispose() {},
+  };
+}
+
+export interface CreateViewportFromRootInput {
+  /**
+   * Editor root element. `scrollLeft` / `scrollTop` are read from here on
+   * scroll and resize; no other DOM fields are read (per G2). When the
+   * argument is `null` or the element is detached, the handle falls back
+   * to the stub viewport and `subscribe` never fires — matches the
+   * degraded Slice-1 path.
+   */
+  root: HTMLElement | null;
+  /**
+   * Current `pxPerTwip` from the render kernel's zoom. The handle stores
+   * it so consumers reading `Viewport.pxPerTwip` see the zoom the kernel
+   * used for the latest frame. Update via `setPxPerTwip(next)` when the
+   * kernel emits a `zoom_changed` event.
+   */
+  pxPerTwip: number;
+}
+
+export interface RootViewportHandle extends ViewportHandle {
+  /**
+   * Push a new `pxPerTwip` value. Notifies subscribers immediately so
+   * chrome overlays re-project on zoom changes without waiting for a
+   * scroll/resize event.
+   */
+  setPxPerTwip(value: number): void;
+}
+
+/**
+ * Slice 3 — DOM-backed viewport. Listens for passive scroll + ResizeObserver
+ * resize events on `root`; rAF-coalesces reads into a single listener
+ * fan-out per animation frame (performance invariant 1). Reads only
+ * `scrollLeft` / `scrollTop`; no layout-flushing geometry reads.
+ */
+export function createViewportFromRoot(
+  input: CreateViewportFromRootInput,
+): RootViewportHandle {
+  const { root } = input;
+  if (!root) {
+    // Degraded path — behaves like the Slice-1 stub but exposes the
+    // setPxPerTwip entry point so call sites don't have to branch on
+    // whether a root was available.
+    let pxPerTwip = input.pxPerTwip;
+    const listeners = new Set<ViewportListener>();
+    const readOnce = (): Viewport => ({
+      ...DEFAULT_VIEWPORT,
+      pxPerTwip,
+    });
+    return {
+      getViewport: readOnce,
+      subscribe(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      dispose() {
+        listeners.clear();
+      },
+      setPxPerTwip(value) {
+        if (value === pxPerTwip) return;
+        pxPerTwip = value;
+        const snapshot = readOnce();
+        for (const listener of listeners) listener(snapshot);
+      },
+    };
+  }
+
+  const win = root.ownerDocument?.defaultView ?? null;
+  let pxPerTwip = input.pxPerTwip;
+  const listeners = new Set<ViewportListener>();
+  let rafHandle: number | null = null;
+  let disposed = false;
+
+  const read = (): Viewport => ({
+    // G2 exception: scroll position is a viewport input, not a document-
+    // structure input. This is the one place in `src/runtime/geometry/`
+    // that reads these fields.
+    scrollLeftPx: root.scrollLeft,
+    scrollTopPx: root.scrollTop,
+    dpr:
+      typeof win?.devicePixelRatio === "number" ? win.devicePixelRatio : 1,
+    pxPerTwip,
+  });
+
+  let current = read();
+
+  const fanOut = () => {
+    if (disposed) return;
+    const next = read();
+    if (
+      next.scrollLeftPx === current.scrollLeftPx &&
+      next.scrollTopPx === current.scrollTopPx &&
+      next.dpr === current.dpr &&
+      next.pxPerTwip === current.pxPerTwip
+    ) {
+      return;
+    }
+    current = next;
+    for (const listener of listeners) listener(next);
+  };
+
+  const schedule = () => {
+    if (disposed) return;
+    if (rafHandle !== null) return;
+    const raf = win?.requestAnimationFrame;
+    if (!raf) {
+      // Test / SSR / older jsdom — fire synchronously.
+      fanOut();
+      return;
+    }
+    rafHandle = raf.call(win, () => {
+      rafHandle = null;
+      fanOut();
+    });
+  };
+
+  const onScroll = () => schedule();
+
+  root.addEventListener("scroll", onScroll, { passive: true });
+
+  let resizeObserver: ResizeObserver | null = null;
+  const ResizeObserverCtor = (win as { ResizeObserver?: typeof ResizeObserver } | null)
+    ?.ResizeObserver;
+  if (ResizeObserverCtor) {
+    resizeObserver = new ResizeObserverCtor(() => schedule());
+    resizeObserver.observe(root);
+  }
+
+  return {
+    getViewport() {
+      return current;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      root.removeEventListener("scroll", onScroll);
+      if (resizeObserver) {
+        resizeObserver.disconnect();
+        resizeObserver = null;
+      }
+      if (rafHandle !== null && win?.cancelAnimationFrame) {
+        win.cancelAnimationFrame(rafHandle);
+        rafHandle = null;
+      }
+      listeners.clear();
+    },
+    setPxPerTwip(value) {
+      if (value === pxPerTwip) return;
+      pxPerTwip = value;
+      // Zoom change is observable immediately — bypass rAF so consumers
+      // don't see a stale pxPerTwip on the next render frame.
+      current = { ...current, pxPerTwip };
+      for (const listener of listeners) listener(current);
+    },
+  };
+}