@elabs-ai/components-viewer 4.0.0

package/src/adapters/pdf/pdf-engine.ts

@@ -0,0 +1,171 @@
+/**
+ * The pdf.js seam — one place that knows the engine exists.
+ *
+ * Everything here is deliberately NOT React. Splitting the engine wiring from
+ * the renderer keeps two things true: the dynamic `import("pdfjs-dist")` has a
+ * single call site (so `heavy-deps:check` has one edge to police), and an app
+ * can configure the worker before any file is ever opened.
+ *
+ * ## Why a worker is not optional
+ *
+ * pdf.js parses and rasterizes on a worker thread; without one it falls back to
+ * doing that on the main thread, and a 40-page document freezes the tab. The
+ * default below resolves the worker that ships INSIDE `pdfjs-dist`, via
+ * `new URL(…, import.meta.url)` — the form every modern bundler understands, so
+ * it works with no configuration in Vite/webpack/Next.
+ *
+ * ## Why an app may still have to configure it
+ *
+ * A CSP without `worker-src blob:` — or a bundler that cannot see through the
+ * `new URL` form — needs the worker served as a real asset instead. Hence
+ * {@link configurePdfEngine}: set `workerSrc` to a URL your app serves, and the
+ * default is never consulted. `cMapUrl` / `standardFontDataUrl` are the same
+ * story for CJK text and non-embedded fonts, which pdf.js fetches on demand.
+ */
+
+/** Engine wiring an app can override. Every field is optional. */
+export interface PdfEngineConfig {
+  /** URL of `pdf.worker.min.mjs`. Defaults to the copy inside `pdfjs-dist`. */
+  workerSrc?: string;
+  /** Directory of pdf.js `cmaps/`, for documents with CJK text. */
+  cMapUrl?: string;
+  /** Directory of pdf.js `standard_fonts/`, for documents that embed no fonts. */
+  standardFontDataUrl?: string;
+}
+
+let config: PdfEngineConfig = {};
+
+/**
+ * Point the PDF adapter at your own copies of the pdf.js assets.
+ *
+ * Call once at app start, before a PDF is opened. Calling it later is harmless
+ * but only affects documents opened afterwards — pdf.js reads the worker
+ * setting when a document is created.
+ */
+export function configurePdfEngine(next: PdfEngineConfig): void {
+  config = { ...config, ...next };
+}
+
+/** What the adapter will actually use, after any {@link configurePdfEngine} call. */
+export function getPdfEngineConfig(): Readonly<PdfEngineConfig> {
+  return config;
+}
+
+/**
+ * The pdf.js surface this adapter uses, declared structurally.
+ *
+ * `pdfjs-dist` is an OPTIONAL peer, so its types are not guaranteed to be
+ * installed — importing them would make this package's typecheck depend on a
+ * package a consumer may not have. Declaring the handful of members used here
+ * keeps the build honest without that coupling, and a shape change in pdf.js
+ * surfaces as a runtime failure the `parse-failed` panel already handles.
+ */
+export interface PdfPageViewport {
+  width: number;
+  height: number;
+}
+
+export interface PdfTextItem {
+  str: string;
+  transform: number[];
+  width: number;
+  height: number;
+  fontName?: string;
+}
+
+export interface PdfPage {
+  getViewport(options: { scale: number; rotation?: number }): PdfPageViewport;
+  render(options: { canvasContext: CanvasRenderingContext2D; viewport: PdfPageViewport }): {
+    promise: Promise<void>;
+    cancel(): void;
+  };
+  getTextContent(): Promise<{ items: PdfTextItem[] }>;
+  cleanup(): void;
+}
+
+export interface PdfDocument {
+  numPages: number;
+  getPage(pageNumber: number): Promise<PdfPage>;
+}
+
+/**
+ * An open document plus the one call that releases its worker.
+ *
+ * The two are separate because **the worker belongs to the LOADING TASK, not to
+ * the document**: pdf.js removed `PDFDocumentProxy.destroy()` in v5, so
+ * `document.destroy()` is not a function on the engine this package installs. It
+ * type-checked anyway — the structural `PdfDocument` interface here declared a
+ * method the real proxy does not have — and threw a `TypeError` on every unmount,
+ * leaking exactly the worker per document that `dispose()` exists to prevent.
+ * Keeping the teardown on this object rather than on `document` is what stops the
+ * mistake from being expressible.
+ */
+export interface PdfSession {
+  document: PdfDocument;
+  destroy(): Promise<void>;
+}
+
+interface PdfJsModule {
+  GlobalWorkerOptions: { workerSrc: string };
+  getDocument(options: Record<string, unknown>): {
+    promise: Promise<PdfDocument>;
+    destroy(): Promise<void>;
+  };
+}
+
+let enginePromise: Promise<PdfJsModule> | undefined;
+
+/**
+ * Load pdf.js once per page load and wire its worker.
+ *
+ * The result is cached: opening a second PDF must not re-fetch a megabyte of
+ * engine. A FAILED load is not cached, so a transient network error can be
+ * retried by the viewer's own retry button.
+ */
+export async function loadPdfEngine(): Promise<PdfJsModule> {
+  enginePromise ??= (async () => {
+    // The ONLY edge to the optional peer. A static import here would break
+    // every consumer that did not install pdfjs-dist (heavy-deps:check).
+    const pdfjs = (await import("pdfjs-dist")) as unknown as PdfJsModule;
+    pdfjs.GlobalWorkerOptions.workerSrc = config.workerSrc ?? defaultWorkerSrc();
+    return pdfjs;
+  })().catch((error: unknown) => {
+    enginePromise = undefined;
+    throw error;
+  });
+  return enginePromise;
+}
+
+/**
+ * The worker that ships with the installed `pdfjs-dist`.
+ *
+ * `new URL(…, import.meta.url)` is a *bundler instruction*, not a runtime path
+ * lookup: Vite, webpack 5 and Turbopack all rewrite it to an emitted asset URL.
+ * It is wrapped because a runtime without `import.meta.url` (a CJS test) throws
+ * here, and a missing worker should surface as "configure the worker", not as an
+ * unexplained crash.
+ */
+function defaultWorkerSrc(): string {
+  return new URL("pdfjs-dist/build/pdf.worker.min.mjs", import.meta.url).href;
+}
+
+/** Open a document from bytes. The caller owns `destroy()` — see the adapter's `dispose`. */
+export async function openPdfDocument(
+  bytes: Uint8Array,
+  signal?: AbortSignal,
+): Promise<PdfSession> {
+  const pdfjs = await loadPdfEngine();
+  const task = pdfjs.getDocument({
+    data: bytes,
+    // Defence in depth: pdf.js can evaluate font programs, and a viewer opens
+    // files the app did not write. The cost is a rare, slightly slower font
+    // path; the benefit is that a malicious PDF has no `eval` to reach for.
+    isEvalSupported: false,
+    cMapUrl: config.cMapUrl,
+    cMapPacked: true,
+    standardFontDataUrl: config.standardFontDataUrl,
+  });
+  signal?.addEventListener("abort", () => void task.destroy(), { once: true });
+  const document = await task.promise;
+  return { document, destroy: () => task.destroy() };
+}

package/src/adapters/pdf/pdf-fixture.ts

@@ -0,0 +1,27 @@
+/**
+ * A real, minimal PDF — two pages of live text, ~1 KB, generated once and frozen
+ * here so stories and tests need no network and no binary asset in the repo.
+ *
+ * It is a genuine file (catalog, page tree, content streams, xref), not a stub:
+ * the point is that pdf.js actually opens it, rasterizes a page and exposes
+ * selectable text — which a hand-waved fixture could not prove.
+ */
+export const SAMPLE_PDF_BASE64 =
+  "JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwg" +
+  "L1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUiA1IDAgUl0gL0NvdW50IDIgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUg" +
+  "L1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9G" +
+  "MSA3IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCAxMzcgPj4Kc3Ry" +
+  "ZWFtCkJUIC9GMSAyNCBUZiA3MiA3MDAgVGQgKFF1YXJ0ZXJseSByZXBvcnQgLSBwYWdlIG9uZSkgVGogRVQKQlQgL0Yx" +
+  "IDEyIFRmIDcyIDY2MCBUZCAoR2VuZXJhdGVkIGZpeHR1cmUgZm9yIHRoZSBicmFuZC11aSBmaWxlIHZpZXdlci4pIFRq" +
+  "IEVUCmVuZHN0cmVhbQplbmRvYmoKNSAwIG9iago8PCAvVHlwZSAvUGFnZSAvUGFyZW50IDIgMCBSIC9NZWRpYUJveCBb" +
+  "MCAwIDYxMiA3OTJdIC9SZXNvdXJjZXMgPDwgL0ZvbnQgPDwgL0YxIDcgMCBSID4+ID4+IC9Db250ZW50cyA2IDAgUiA+" +
+  "PgplbmRvYmoKNiAwIG9iago8PCAvTGVuZ3RoIDEyOSA+PgpzdHJlYW0KQlQgL0YxIDI0IFRmIDcyIDcwMCBUZCAoQXBw" +
+  "ZW5kaXggLSBwYWdlIHR3bykgVGogRVQKQlQgL0YxIDEyIFRmIDcyIDY2MCBUZCAoR2VuZXJhdGVkIGZpeHR1cmUgZm9y" +
+  "IHRoZSBicmFuZC11aSBmaWxlIHZpZXdlci4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKNyAwIG9iago8PCAvVHlwZSAv" +
+  "Rm9udCAvU3VidHlwZSAvVHlwZTEgL0Jhc2VGb250IC9IZWx2ZXRpY2EgPj4KZW5kb2JqCnhyZWYKMCA4CjAwMDAwMDAw" +
+  "MDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMjEgMDAwMDAg" +
+  "biAKMDAwMDAwMDI0NyAwMDAwMCBuIAowMDAwMDAwNDM1IDAwMDAwIG4gCjAwMDAwMDA1NjEgMDAwMDAgbiAKMDAwMDAw" +
+  "MDc0MSAwMDAwMCBuIAp0cmFpbGVyCjw8IC9TaXplIDggL1Jvb3QgMSAwIFIgPj4Kc3RhcnR4cmVmCjgxMQolJUVPRgo=";
+
+/** The same file as a data URI, ready to hand to `FileViewer` as a `url` source. */
+export const SAMPLE_PDF_DATA_URI = `data:application/pdf;base64,${SAMPLE_PDF_BASE64}`;

package/src/adapters/pdf/pdf-manifest.ts

@@ -0,0 +1,30 @@
+import type { AdapterManifest } from "../../core/types";
+import { PROTOCOL_VERSION } from "../../core/types";
+
+/**
+ * Eager, data-only. Split from the adapter module so `createDefaultRegistry`
+ * can answer "can this be opened, and what controls apply" without pulling
+ * pdf.js — a ~1 MB engine — into the entry chunk.
+ *
+ * `requires` is what the "install this" message names when `pdfjs-dist` is not
+ * present: the adapter is registered either way, so the reader is told what is
+ * missing instead of being told the file type is unsupported.
+ *
+ * The only adapter that declares `rect`: a PDF page has a fixed coordinate
+ * space, so a producer that knows where a passage sits on the page — an OCR
+ * pipeline, a layout-aware chunker — can address it geometrically and skip the
+ * text projection entirely.
+ */
+export const pdfManifest: AdapterManifest = {
+  id: "pdf",
+  protocol: PROTOCOL_VERSION,
+  extensions: ["pdf"],
+  mediaTypes: ["application/pdf"],
+  capabilities: {
+    pages: true,
+    zoom: true,
+    text: true,
+    highlight: ["quote", "range", "rect"],
+  },
+  requires: ["pdfjs-dist"],
+};

package/src/adapters/pdf/pdf-text.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "vitest";
+
+import type { ResolvedHighlight } from "../../core/highlight";
+import { toMarkRanges } from "../../core/highlight-marks";
+import { createTextIndexBuilder } from "../../core/text-index";
+import {
+  PDF_PAGE_SEPARATOR,
+  pageOfHighlight,
+  pageTextChunk,
+  rangeBoxes,
+  rectBoxes,
+  type PdfTextSpan,
+} from "./pdf-text";
+
+const ITEMS = [{ str: "Alpha" }, { str: "" }, { str: "Beta" }];
+
+/** The geometry the renderer derives from those items, at scale 1. */
+const SPANS: PdfTextSpan[] = [
+  { text: "Alpha", left: 72, top: 80, width: 40, fontSize: 12, item: 0 },
+  { text: "Beta", left: 72, top: 100, width: 32, fontSize: 12, item: 2 },
+];
+
+function resolved(over: Partial<ResolvedHighlight> = {}): ResolvedHighlight {
+  return {
+    id: "c1",
+    source: "citation",
+    status: "resolved",
+    address: { kind: "range", start: 0, end: 5 },
+    active: false,
+    ...over,
+  };
+}
+
+describe("pageTextChunk", () => {
+  it("joins items the way the projection does and records where each one landed", () => {
+    const chunk = pageTextChunk(ITEMS);
+    expect(chunk.text).toBe("Alpha  Beta");
+    expect(chunk.spans).toEqual([
+      { start: 0, end: 5 },
+      { start: 6, end: 6 },
+      { start: 7, end: 11 },
+    ]);
+  });
+
+  it("keeps empty items in place, so no following offset shifts", () => {
+    // The empty item still consumes its separator. Dropping it would pull "Beta"
+    // back by one character and put every mark on this page one glyph off.
+    const chunk = pageTextChunk(ITEMS);
+    expect(chunk.text.slice(7, 11)).toBe("Beta");
+    expect(chunk.spans).toHaveLength(ITEMS.length);
+  });
+
+  it("agrees with the projection the loader builds from the same call", () => {
+    const builder = createTextIndexBuilder<number>({ separator: PDF_PAGE_SEPARATOR });
+    builder.push(pageTextChunk(ITEMS).text, 1);
+    builder.push(pageTextChunk([{ str: "Gamma" }]).text, 2);
+    const index = builder.build();
+
+    expect(index.text).toBe("Alpha  Beta\n\nGamma");
+    // Page 2 begins after the page separator — the offset a citation on that
+    // page is expressed against.
+    expect(index.spans[1]).toEqual({ start: 13, end: 18, ref: 2 });
+  });
+});
+
+describe("rangeBoxes", () => {
+  const chunk = pageTextChunk(ITEMS);
+
+  it("puts a box over the item the range lands in", () => {
+    const marks = toMarkRanges([resolved({ range: [7, 11] })], 11);
+    expect(rangeBoxes(SPANS, chunk, 0, marks)).toEqual([
+      { left: 72, top: 100, width: 32, height: 12, active: false },
+    ]);
+  });
+
+  it("cuts a partial match proportionally rather than lighting the whole run", () => {
+    // "Al" of "Alpha": two of five characters of a 40-wide item.
+    const marks = toMarkRanges([resolved({ range: [0, 2] })], 11);
+    const [box] = rangeBoxes(SPANS, chunk, 0, marks);
+    expect(box?.left).toBe(72);
+    expect(box?.width).toBe(16);
+  });
+
+  it("offsets by where the page starts in the projection", () => {
+    // Same page, but it is the second one: its chunk begins at 13.
+    const marks = toMarkRanges([resolved({ range: [20, 24] })], 24);
+    const [box] = rangeBoxes(SPANS, chunk, 13, marks);
+    expect(box?.top).toBe(100);
+  });
+
+  it("marks the box the viewer is pointed at, and only that one", () => {
+    const marks = toMarkRanges(
+      [resolved({ id: "a", range: [0, 5] }), resolved({ id: "b", range: [7, 11], active: true })],
+      11,
+    );
+    expect(rangeBoxes(SPANS, chunk, 0, marks).map((box) => box.active)).toEqual([false, true]);
+  });
+
+  it("falls back to an em estimate when pdf.js reported no width", () => {
+    const spans: PdfTextSpan[] = [{ ...(SPANS[0] as PdfTextSpan), width: 0 }];
+    const marks = toMarkRanges([resolved({ range: [0, 5] })], 11);
+    // 5 characters × half of a 12pt em.
+    expect(rangeBoxes(spans, chunk, 0, marks)[0]?.width).toBe(30);
+  });
+
+  it("paints nothing when the marks are on another page", () => {
+    const marks = toMarkRanges([resolved({ range: [40, 44] })], 60);
+    expect(rangeBoxes(SPANS, chunk, 0, marks)).toEqual([]);
+  });
+});
+
+describe("rectBoxes", () => {
+  const size = { width: 600, height: 800 };
+
+  it("scales fractions to the page's CURRENT rendered size", () => {
+    const highlight = resolved({
+      address: { kind: "rect", page: 1, rects: [{ x: 0.1, y: 0.2, width: 0.5, height: 0.05 }] },
+      rects: [{ x: 0.1, y: 0.2, width: 0.5, height: 0.05 }],
+    });
+    expect(rectBoxes([highlight], size)).toEqual([
+      { left: 60, top: 160, width: 300, height: 40, active: false },
+    ]);
+  });
+
+  it("clamps a foreign document's geometry to the page", () => {
+    const rects = [{ x: -1, y: 2, width: 5, height: Number.NaN }];
+    const highlight = resolved({ address: { kind: "rect", page: 1, rects }, rects });
+    expect(rectBoxes([highlight], size)).toEqual([
+      { left: 0, top: 800, width: 600, height: 0, active: false },
+    ]);
+  });
+
+  it("draws one box per rect, because a chunk can wrap a column break", () => {
+    const rects = [
+      { x: 0, y: 0, width: 0.5, height: 0.1 },
+      { x: 0.5, y: 0.5, width: 0.5, height: 0.1 },
+    ];
+    const highlight = resolved({
+      address: { kind: "rect", page: 1, rects },
+      rects,
+      active: true,
+    });
+    const boxes = rectBoxes([highlight], size);
+    expect(boxes).toHaveLength(2);
+    expect(boxes.every((box) => box.active)).toBe(true);
+  });
+});
+
+describe("pageOfHighlight", () => {
+  const index = createTextIndexBuilder<number>({ separator: PDF_PAGE_SEPARATOR });
+  index.push("Alpha", 1);
+  index.push("Gamma", 2);
+  const built = index.build();
+
+  it("prefers what the caller said", () => {
+    expect(pageOfHighlight(resolved({ page: 4, range: [0, 5] }), built)).toBe(4);
+  });
+
+  it("looks a located range up through the document's own index", () => {
+    expect(pageOfHighlight(resolved({ range: [7, 12] }), built)).toBe(2);
+  });
+
+  it("has no answer for a range on a separator, so the pager stays put", () => {
+    expect(pageOfHighlight(resolved({ range: [5, 6] }), built)).toBeUndefined();
+  });
+
+  it("has no answer for a highlight that never resolved", () => {
+    expect(pageOfHighlight(resolved({ status: "not-found" }), built)).toBeUndefined();
+    expect(pageOfHighlight(undefined, built)).toBeUndefined();
+  });
+});

package/src/adapters/pdf/pdf-text.ts

@@ -0,0 +1,202 @@
+/**
+ * PDF text ↔ page geometry — the MAP half of the highlight funnel for a raster.
+ *
+ * A PDF page is pixels. There is no DOM text to wrap in a `<mark>`, so the paint
+ * step here is a layer of BOXES over the canvas, and this module is what turns
+ * "characters 812–847 of the projection" into those boxes.
+ *
+ * ## Why the projection is rebuilt rather than remembered
+ *
+ * `AdapterDocument.text` is assembled at LOAD time, one page at a time; the
+ * renderer re-fetches the current page's text content anyway (it needs the same
+ * items to position the selectable text layer). So both sides call
+ * {@link pageTextChunk}, and the projection and the geometry agree by
+ * construction instead of by two hand-kept copies of the same join rule.
+ *
+ * ## Why the boxes are proportional, and what that costs
+ *
+ * pdf.js reports one box per text ITEM — a run of glyphs — and no per-character
+ * geometry. When a range covers only part of an item, the box is cut
+ * proportionally by character count. That is a linear approximation of a
+ * proportional font, so it can be off by a glyph or two inside a long run; PDF
+ * items are usually a word or a line fragment, where the error is invisible.
+ *
+ * The alternative — DOM ranges over the transparent text layer — would be WORSE
+ * here, not better: that layer renders in a generic font at pdf.js's transform,
+ * so its glyph advances do not match the raster underneath it at all. The item
+ * box comes from the file itself and does.
+ */
+
+import type { DocumentRect } from "@elabs-ai/components-ui";
+
+import type { ResolvedHighlight } from "../../core/highlight";
+import { localizeRanges, type MarkRanges } from "../../core/highlight-marks";
+import { spanAt, type TextIndex } from "../../core/text-index";
+
+/** Written between two text items of the same page. */
+export const PDF_ITEM_SEPARATOR = " ";
+
+/** Written between two pages of the projection. */
+export const PDF_PAGE_SEPARATOR = "\n\n";
+
+/** The part of a pdf.js text item this module needs. */
+export interface PdfTextItemLike {
+  str: string;
+}
+
+/** Half-open `[start, end)` into the page's own chunk, one per item. */
+export interface PdfItemSpan {
+  start: number;
+  end: number;
+}
+
+/** One page's contribution to the projection, plus where each item landed in it. */
+export interface PdfPageChunk {
+  text: string;
+  /** Index-aligned with the items passed in — including the empty ones. */
+  spans: readonly PdfItemSpan[];
+}
+
+/**
+ * Join a page's text items the way the projection does, and record each item's
+ * offsets.
+ *
+ * Empty items keep their place: they still consume a separator, so an item's
+ * index into this array is the same index pdf.js handed back. Dropping them
+ * would shift every following offset by one and put every mark a character off.
+ */
+export function pageTextChunk(items: readonly PdfTextItemLike[]): PdfPageChunk {
+  const spans: PdfItemSpan[] = [];
+  const parts: string[] = [];
+  let cursor = 0;
+
+  items.forEach((item, index) => {
+    if (index > 0) cursor += PDF_ITEM_SEPARATOR.length;
+    parts.push(item.str);
+    spans.push({ start: cursor, end: cursor + item.str.length });
+    cursor += item.str.length;
+  });
+
+  return { text: parts.join(PDF_ITEM_SEPARATOR), spans };
+}
+
+/** A positioned text item, in CSS pixels relative to the rendered page. */
+export interface PdfTextSpan {
+  text: string;
+  left: number;
+  top: number;
+  /** The item's own advance width. `0` when pdf.js did not report one. */
+  width: number;
+  fontSize: number;
+  /** Index into the page's original items — the seam back to the projection. */
+  item: number;
+}
+
+/** A rectangle to paint over the page, in CSS pixels. */
+export interface PdfHighlightBox {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  /** Whether this box is the highlight the viewer is currently pointed at. */
+  active: boolean;
+}
+
+/**
+ * Fallback advance per character when pdf.js reports no width.
+ *
+ * Half an em is the rough mean advance of Latin text; it only ever decides how
+ * wide a box is drawn, never where the reader is taken.
+ */
+const FALLBACK_ADVANCE = 0.5;
+
+/**
+ * Boxes for every marked range that falls on this page.
+ *
+ * `pageStart` is where this page's chunk begins in the projection, which is what
+ * makes a whole-document offset comparable with a per-page item offset.
+ */
+export function rangeBoxes(
+  spans: readonly PdfTextSpan[],
+  chunk: PdfPageChunk,
+  pageStart: number,
+  marks: MarkRanges,
+): PdfHighlightBox[] {
+  if (marks.ranges.length === 0) return [];
+
+  const boxes: PdfHighlightBox[] = [];
+  for (const span of spans) {
+    const item = chunk.spans[span.item];
+    if (!item || item.end === item.start) continue;
+
+    const local = localizeRanges(marks, pageStart + item.start, pageStart + item.end);
+    if (local.ranges.length === 0) continue;
+
+    const length = item.end - item.start;
+    const advance = span.width > 0 ? span.width / length : span.fontSize * FALLBACK_ADVANCE;
+    local.ranges.forEach(([from, to], index) => {
+      boxes.push({
+        left: span.left + advance * from,
+        top: span.top,
+        width: advance * (to - from),
+        height: span.fontSize,
+        active: index === local.activeIndex,
+      });
+    });
+  }
+  return boxes;
+}
+
+/**
+ * Boxes for `rect` addresses, whose geometry is already the answer.
+ *
+ * Fractions rather than pixels is what makes them survive zoom and a resize: the
+ * same address is correct at 50% and at 300% because it is multiplied by the
+ * page's CURRENT rendered size every time.
+ */
+export function rectBoxes(
+  highlights: readonly ResolvedHighlight[],
+  size: { width: number; height: number },
+): PdfHighlightBox[] {
+  const boxes: PdfHighlightBox[] = [];
+  for (const highlight of highlights) {
+    for (const rect of highlight.rects ?? []) {
+      boxes.push({
+        left: clampFraction(rect.x) * size.width,
+        top: clampFraction(rect.y) * size.height,
+        width: clampFraction(rect.width) * size.width,
+        height: clampFraction(rect.height) * size.height,
+        active: highlight.active,
+      });
+    }
+  }
+  return boxes;
+}
+
+/** Keep a foreign document's geometry inside the page it claims to be on. */
+function clampFraction(value: DocumentRect["x"]): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+
+/**
+ * Which page a highlight is on, so activating it can turn to that page.
+ *
+ * A `rect` carries its own page — geometry has no range to look up. Everything
+ * else is looked up through the document's own index, because the ref type is the
+ * adapter's business and this adapter's is the page number. A caller's page HINT
+ * is deliberately not consulted: it is the resolver's job to leave it off
+ * (`ResolvedHighlight.page`), since a stale hint would turn to a page the mark is
+ * not on. A range landing on a page separator, or past the extraction cap, has no
+ * page and the pager stays put rather than jumping somewhere arbitrary.
+ */
+export function pageOfHighlight(
+  highlight: ResolvedHighlight | undefined,
+  index: TextIndex<unknown> | undefined,
+): number | undefined {
+  if (!highlight || highlight.status !== "resolved") return undefined;
+  if (highlight.page !== undefined) return highlight.page;
+  if (!highlight.range || !index) return undefined;
+  const span = spanAt(index, highlight.range[0]);
+  return typeof span?.ref === "number" ? span.ref : undefined;
+}