@elabs-ai/components-viewer 4.0.0

package/src/core/types.ts

@@ -0,0 +1,285 @@
+/**
+ * The adapter protocol — what a format plugin declares, what it produces, and
+ * what renders it.
+ *
+ * ## The two halves, and why they are split
+ *
+ * A registry entry is an eager {@link AdapterManifest} plus a lazy loader. The
+ * manifest is plain data available the moment the registry is created, so the
+ * chrome can decide which controls to show and whether a file is openable at all
+ * **without downloading a parser**. The loader is a `() => import(…)` that pulls
+ * the parser AND its renderer together, only once a file of that kind is opened.
+ *
+ * ## Adapters emit DATA, not HTML (ADR 0024 §3)
+ *
+ * An adapter's `load()` returns an {@link AdapterDocument} — a model — and ships
+ * a `Renderer` that draws it with brand-ui components. No adapter returns an
+ * HTML string, so no adapter can smuggle a colour, a font or a border past the
+ * token layer. This is the single decision that keeps the viewer themeable.
+ */
+
+import type {
+  DocumentAddressKind,
+  FileCategory,
+  ProseHeadingLevel,
+  ResolvedFileSource,
+} from "@elabs-ai/components-ui";
+import type { ComponentType } from "react";
+
+import type { ResolvedHighlight } from "./highlight";
+import type { TextIndex } from "./text-index";
+
+/**
+ * The adapter protocol version. Bumped only when the shapes below change in a
+ * way an existing adapter would not survive; an adapter declaring a different
+ * version is rejected with a named error rather than crashing at render.
+ */
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * A quarter-turn clockwise rotation applied to the whole document.
+ *
+ * Document-level, not per-page: turning one page of a scan and leaving the rest
+ * is an AUTHORING act (it changes the file), and this package reads files.
+ */
+export type DocumentRotation = 0 | 90 | 180 | 270;
+
+/** Scale the content to a dimension of the viewport instead of to a fixed number. */
+export type ZoomFit = "fit-width" | "fit-page";
+
+/** One page's size at scale 1, in CSS pixels. */
+export interface PageSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * What the chrome asks a renderer to draw at.
+ *
+ * A fit mode is a REQUEST, not a scale: only the renderer knows how wide its own
+ * viewport is and how big the page is, so it resolves the request and reports the
+ * number back through {@link AdapterRendererProps.onZoomResolved}. Resolving it
+ * in the provider would mean the shell measuring a box it does not own.
+ */
+export type ZoomLevel = number | ZoomFit;
+
+/** What the chrome may offer for a format, known before any parser is fetched. */
+export interface AdapterCapabilities {
+  /** The document is paginated — show the pager. */
+  pages?: boolean;
+  /** The rendered content can be scaled — show the zoom control. */
+  zoom?: boolean;
+  /** The rendered content can be rotated. */
+  rotate?: boolean;
+  /**
+   * The document exposes text that can be searched.
+   *
+   * An OVERRIDE, not the source of truth: the shell offers find-in-document
+   * whenever a format has both a text projection and a text-based
+   * {@link AdapterCapabilities.highlight} kind, and reads this only when an
+   * adapter says otherwise. Left as the source of truth it would deny the find
+   * box to PDF — the format readers most expect it on — purely because that
+   * manifest predates the feature and never declared the flag.
+   *
+   * It overrides in the OFF direction only, so a declared `true` is inert: it
+   * cannot grant find to a format with no text or no range-painting renderer,
+   * because the box would then have nothing to show for a match.
+   */
+  search?: boolean;
+  /**
+   * Which {@link DocumentAddress} kinds this adapter's `Renderer` can actually
+   * paint. Absent means none.
+   *
+   * On the EAGER manifest on purpose: an app can decide whether to show a
+   * "jump to the cited passage" affordance before it downloads pdf.js.
+   *
+   * It is a promise the renderer has to keep — `pnpm viewer-highlight:check`
+   * fails a manifest that declares a kind its adapter never exercises.
+   */
+  highlight?: readonly DocumentAddressKind[];
+  /** The document has an outline/table of contents for the sidebar. */
+  outline?: boolean;
+  /** The document can produce page thumbnails for the sidebar. */
+  thumbnails?: boolean;
+  /** A plain-text projection exists — enables the raw/source toggle and copy. */
+  text?: boolean;
+}
+
+/**
+ * What an adapter can open. At least one of `extensions` / `mediaTypes` /
+ * `categories` must be present, or nothing will ever route to it.
+ */
+export interface AdapterManifest {
+  /**
+   * Stable identity and the OVERRIDE key: registering a different loader under
+   * an existing id replaces it, which is how a consumer swaps a built-in.
+   */
+  id: string;
+  /** Must equal {@link PROTOCOL_VERSION}. */
+  protocol: number;
+  /**
+   * Tie-break when several adapters claim the same file. Built-ins are `0`;
+   * register above it to win, below it to act only as a fallback.
+   */
+  priority?: number;
+  /** Extensions claimed, lowercase and without the dot. The most specific match. */
+  extensions?: string[];
+  /** MIME types claimed. A trailing slash makes it a prefix (`"image/"`). */
+  mediaTypes?: string[];
+  /** Coarse categories claimed. The broadest match — a catch-all fallback. */
+  categories?: FileCategory[];
+  /** Which chrome controls apply. Absent keys are `false`. */
+  capabilities?: AdapterCapabilities;
+  /**
+   * Optional peer packages this adapter dynamically imports. Purely
+   * informational to the registry — it is what the "install this to open that"
+   * message names when the import fails to resolve.
+   */
+  requires?: string[];
+}
+
+/**
+ * An adapter's parsed output. Adapters EXTEND this with their own payload; the
+ * fields here are the parts the shell itself understands, so it can drive the
+ * pager, the search box and the raw toggle without knowing the format.
+ */
+export interface AdapterDocument {
+  /** Adapter-defined discriminant, matched by that adapter's own `Renderer`. */
+  readonly kind: string;
+  /** Page count for a paginated document. Omit for single-surface formats. */
+  readonly pageCount?: number;
+  /**
+   * Each page's size at scale 1, in document order.
+   *
+   * What lets a continuously-scrolling renderer reserve the right height for a
+   * page it has not drawn yet, so the scrollbar means something from the first
+   * frame instead of growing as pages arrive. May be SHORTER than
+   * {@link AdapterDocument.pageCount} — measuring 900 pages up front costs 900
+   * round-trips to a worker, so an adapter is free to describe the pages it
+   * already touched and let the renderer assume the rest match.
+   */
+  readonly pageSizes?: readonly PageSize[];
+  /** Plain-text projection, when the format has one. Powers search, copy and the raw view. */
+  readonly text?: string;
+  /**
+   * Whether {@link AdapterDocument.text} is CAPPED rather than complete.
+   *
+   * Changes what "we couldn't find that passage" means: absent from the whole
+   * document, or simply past the part we previewed. Those deserve different
+   * sentences, and only the adapter knows which one is true.
+   */
+  readonly textTruncated?: boolean;
+  /**
+   * The map from {@link AdapterDocument.text} back into this adapter's own
+   * model, so a character range can become a block, a page or a cell.
+   *
+   * The `ref` type is the adapter's business — its own `Renderer` is the only
+   * thing that reads it, which is why it is `unknown` here.
+   */
+  readonly textIndex?: TextIndex<unknown>;
+}
+
+/** Everything an adapter is given while loading a document. */
+export interface AdapterLoadContext {
+  /** Cancels the load — always honour it; a stale parse must not win a race. */
+  signal?: AbortSignal;
+  /** Report determinate progress in `0..1` where the format allows it. */
+  onProgress?: (fraction: number) => void;
+}
+
+/** A parser instance. One per document — adapters may hold per-document state. */
+export interface FileAdapter {
+  load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<AdapterDocument>;
+  /** Release anything the document holds (workers, object URLs, decoded buffers). */
+  dispose?(): void;
+}
+
+/** Props every adapter `Renderer` receives. */
+export interface AdapterRendererProps {
+  /** The value this adapter's own `load()` returned — narrow it by `kind`. */
+  document: AdapterDocument;
+  /** The source, for identity, `alt` text and download actions. */
+  source: ResolvedFileSource;
+  className?: string;
+  /**
+   * The heading rung a document's own top-level heading renders at.
+   *
+   * A viewed file carries its OWN heading tree, and that tree has to be
+   * relative to the page hosting it: a README's `#` inside an app that already
+   * has an `<h1>` would otherwise put two `h1`s in a screen reader's flat
+   * heading list. `FileViewerContent` passes the provider's value; an adapter
+   * that renders headings offsets by it (`clampHeadingLevel(own + base - 1)`),
+   * and one that renders none ignores it. Same seam as
+   * `@elabs-ai/components-ai`'s `MarkdownView baseHeadingLevel`.
+   *
+   * Optional, so adding it is not a `PROTOCOL_VERSION` change.
+   */
+  baseHeadingLevel?: ProseHeadingLevel;
+  /**
+   * The parts of the document to mark, already located — citations from the
+   * app and the viewer's own find-in-document matches, in document order.
+   *
+   * The shell has done LOCATE (a quote is now a character range); the renderer
+   * does MAP and PAINT, because only it knows that offsets 812–847 are the
+   * second half of block 14. An adapter renders only the entries whose `status`
+   * is `"resolved"` and whose `address.kind` it declared, and ignores the rest
+   * — the shell is what tells the reader about a miss.
+   *
+   * Optional, so adding it is not a `PROTOCOL_VERSION` change.
+   */
+  highlights?: readonly ResolvedHighlight[];
+  /**
+   * Which highlight the viewer is pointed at. The renderer scrolls it into
+   * view, pages to it if the format paginates, and draws it distinctly.
+   *
+   * Also present as `active` on the entry itself; this is the shortcut for a
+   * renderer that only needs to know whether anything changed.
+   */
+  activeHighlightId?: string | null;
+  /**
+   * Which page the reader is on, 1-based — the provider's, not the renderer's.
+   *
+   * Page, zoom and rotation are PROVIDER state (ADR 0026) so a control can live
+   * anywhere: the shell's own toolbar, an app's page header, a deep link. While
+   * these were `useState` inside each renderer nothing outside the canvas could
+   * read or drive them.
+   *
+   * Uncontrolled when absent — a renderer used outside a `FileViewerProvider`
+   * keeps its own page, so it still works standalone. Optional, so adding it is
+   * not a `PROTOCOL_VERSION` change.
+   */
+  pageNumber?: number;
+  /**
+   * Report a page the RENDERER navigated to on its own — turning to a cited
+   * page, or (once pages scroll continuously) the page scrolled into view. The
+   * provider is what keeps the pager's number honest.
+   */
+  onPageChange?: (page: number) => void;
+  /** The scale, or a fit mode to resolve. Absent means the renderer's own default. */
+  zoom?: ZoomLevel;
+  /**
+   * Report the scale a {@link ZoomFit} actually resolved to.
+   *
+   * Only a renderer knows this — it is the one measuring its viewport. Without
+   * it the chrome cannot show a percentage for a fitted page, and the reader's
+   * next "zoom in" would step from the last fixed stop rather than from what is
+   * on screen. A renderer that never resolves a fit mode never calls it.
+   */
+  onZoomResolved?: (scale: number) => void;
+  /** Quarter-turns clockwise. Ignored by renderers whose manifest omits `rotate`. */
+  rotation?: DocumentRotation;
+}
+
+/**
+ * What an adapter module exports. `manifest` is re-declared here so the registry
+ * can verify the loaded module is the one the eager manifest promised.
+ */
+export interface AdapterModule {
+  manifest: AdapterManifest;
+  /** Fresh instance per document — never a shared singleton. */
+  create(): FileAdapter;
+  Renderer: ComponentType<AdapterRendererProps>;
+}
+
+/** A lazy adapter loader. Always `() => import("…")` so nothing heavy is eager. */
+export type AdapterLoader = () => Promise<AdapterModule | { default: AdapterModule }>;

package/src/core/use-highlight-scroll.ts

@@ -0,0 +1,59 @@
+"use client";
+
+/**
+ * Bring the current highlight into view.
+ *
+ * Pointing at a passage is only half the job — a mark 4,000 lines down that
+ * nobody scrolls to is the same as no mark at all. Every text-ish renderer needs
+ * this, so it is written once here rather than per adapter.
+ *
+ * The current highlight is found by the stable `data-slot` selector its painter
+ * emits, not by a ref: both painters produce their elements from a list — marks
+ * inside `MatchHighlight`, boxes inside a page overlay — so the renderer has no
+ * handle on the individual element and should not grow one just for scrolling.
+ */
+
+import { useEffect, type RefObject } from "react";
+
+import { useReducedMotion } from "@elabs-ai/components-tokens";
+
+/**
+ * How the current highlight identifies itself in the DOM, whichever way it was
+ * painted: a `<mark>` in flowing text, a box over a page raster, or a whole
+ * block plated because the format can only be addressed that coarsely.
+ */
+export const ACTIVE_HIGHLIGHT_SELECTOR =
+  '[data-slot="match-highlight-mark"][data-active],[data-slot="highlight-rect"][data-active],' +
+  '[data-slot="highlight-block"][data-active]';
+
+/**
+ * Scroll the current highlight inside `containerRef` into view whenever the
+ * viewer is pointed somewhere new.
+ *
+ * `block: "center"` rather than `"nearest"`: a cited passage should land where a
+ * reader looks, with its surrounding context visible, not flush against the top
+ * edge of the pane. Smooth scrolling is skipped under a reduced-motion
+ * preference — an imperative scroll is invisible to the CSS media query, so the
+ * check has to be explicit.
+ *
+ * `paintKey` is anything whose change means the highlights were repainted — a
+ * page's box list, a re-tokenized document. A renderer that paints
+ * asynchronously (a PDF fetches the page's text after the raster) has no element
+ * to scroll to at the moment the active id changes, so it passes the thing it
+ * was waiting for and the scroll runs once that arrives.
+ */
+export function useScrollActiveHighlightIntoView(
+  containerRef: RefObject<HTMLElement | null>,
+  activeHighlightId: string | null | undefined,
+  paintKey?: unknown,
+): void {
+  const reducedMotion = useReducedMotion();
+
+  useEffect(() => {
+    if (!activeHighlightId) return;
+    const target = containerRef.current?.querySelector(ACTIVE_HIGHLIGHT_SELECTOR);
+    // jsdom ships no `scrollIntoView`; a viewer must not throw in a test run.
+    if (!(target instanceof HTMLElement) || typeof target.scrollIntoView !== "function") return;
+    target.scrollIntoView({ block: "center", behavior: reducedMotion ? "auto" : "smooth" });
+  }, [containerRef, activeHighlightId, paintKey, reducedMotion]);
+}

package/src/core/use-page-control.ts

@@ -0,0 +1,47 @@
+"use client";
+
+/**
+ * The page half of the renderer contract, as one hook.
+ *
+ * `AdapterRendererProps.pageNumber` is optional on purpose: inside a
+ * `FileViewerProvider` the shell owns the page so a control can live anywhere,
+ * but a `Renderer` mounted on its own — a test, an embed that wants nothing but
+ * the canvas — must still be able to turn a page. That is the ordinary
+ * controlled/uncontrolled trio (`component-api.md`), and both paginated adapters
+ * need exactly the same six lines of it.
+ */
+
+import { useCallback, useState } from "react";
+
+/**
+ * @param pageNumber The controlled page, or `undefined` for uncontrolled.
+ * @param onPageChange Reported on every navigation, controlled or not.
+ * @param pageCount Upper bound. `0` while the count is not known yet.
+ * @returns The page to render, and the function that navigates to another.
+ */
+export function usePageControl(
+  pageNumber: number | undefined,
+  onPageChange: ((page: number) => void) | undefined,
+  pageCount: number,
+): readonly [number, (page: number) => void] {
+  const controlled = pageNumber !== undefined;
+  const [own, setOwn] = useState(1);
+
+  // Clamped on READ, not on write: a controlled owner that has not yet heard
+  // about a shorter document would otherwise render page 40 of 12 and blank the
+  // canvas, and clamping its prop back at it would fight the owner.
+  const raw = controlled ? pageNumber : own;
+  const current = pageCount > 0 ? Math.min(Math.max(1, raw), pageCount) : Math.max(1, raw);
+
+  const goToPage = useCallback(
+    (page: number) => {
+      const next = pageCount > 0 ? Math.min(Math.max(1, page), pageCount) : Math.max(1, page);
+      // Mirroring the platform: a controlled value is never written locally.
+      if (!controlled) setOwn(next);
+      onPageChange?.(next);
+    },
+    [controlled, onPageChange, pageCount],
+  );
+
+  return [current, goToPage] as const;
+}

package/src/core/use-paged-scroll.ts

@@ -0,0 +1,194 @@
+"use client";
+
+/**
+ * Continuous scrolling for a paginated document, over the shell's own viewport.
+ *
+ * ## Why the pages are virtualized
+ *
+ * A 900-page PDF is 900 canvases, 900 text layers and 900 rasterization jobs. A
+ * plain stack would allocate all of them before the first page appeared. Only the
+ * pages near the viewport are mounted, so the cost is a function of the WINDOW,
+ * not of the document.
+ *
+ * ## Why the virtualizer scrolls someone else's element
+ *
+ * `FileViewerContent` is the one scroll boundary (`viewer-components.md`), so the
+ * list is a CHILD of the scrolling box rather than being one. That is what
+ * `scrollMargin` is for: every measurement is offset by where the list starts
+ * inside the pane, which is the pane's own padding.
+ *
+ * ## The page number is a two-way binding, and that is the whole difficulty
+ *
+ * The shell owns `pageNumber` (ADR 0026), so it flows two ways: the reader
+ * scrolls and the pager must follow; the reader types "7" and the document must
+ * scroll. Naively wiring both makes them fight — a scroll reports page 3, the
+ * prop becomes 3, and the "the prop changed, scroll to it" effect snaps the
+ * reader back to the top of page 3 mid-gesture. Each direction therefore
+ * remembers what it last said, and ignores an echo of its own words.
+ */
+
+import { useVirtualizer, type Virtualizer } from "@tanstack/react-virtual";
+import { useEffect, useLayoutEffect, useRef, useState, type RefObject } from "react";
+
+import { findScrollHost } from "./scroll-host";
+
+/**
+ * Slack under the viewport's top edge, in CSS pixels.
+ *
+ * Without it the page whose last pixel row is still visible counts as the page
+ * being read, so the pager flickers back a page at every boundary.
+ */
+const EDGE_SLACK = 8;
+
+export interface PagedScrollOptions {
+  /** Pages in the document. `0` disables the virtualizer entirely. */
+  count: number;
+  /**
+   * The element the pages are laid out in. Must be a descendant of the scroll
+   * host — its `offsetTop` is what `scrollMargin` is derived from.
+   */
+  listRef: RefObject<HTMLElement | null>;
+  /** The page the shell wants shown, 1-based. */
+  pageNumber: number;
+  /** Report the page the reader scrolled to, 1-based. */
+  goToPage: (page: number) => void;
+  /** Height of page `index` at the current scale, in CSS pixels. */
+  estimateSize: (index: number) => number;
+  /**
+   * A value that changes whenever EVERY page's size changes — the scale, in
+   * practice. Every cached measurement is thrown away and the reader is put back
+   * where they were reading, at the new size.
+   */
+  sizeKey?: unknown;
+}
+
+/**
+ * @returns The virtualizer. Render `getVirtualItems()` inside `listRef`'s
+ * element, sized to `getTotalSize()`, translated by `start - scrollMargin`.
+ */
+export function usePagedScroll({
+  count,
+  listRef,
+  pageNumber,
+  goToPage,
+  estimateSize,
+  sizeKey,
+}: PagedScrollOptions): Virtualizer<HTMLElement, Element> {
+  // Resolved after mount rather than passed in: a renderer may be composed into
+  // the shell, into a consumer's own frame, or mounted bare in a test, and only
+  // the DOM knows which. State (not a ref) so the virtualizer re-reads it.
+  const [host, setHost] = useState<HTMLElement | null>(null);
+  const [scrollMargin, setScrollMargin] = useState(0);
+  useEffect(() => {
+    const list = listRef.current;
+    const found = findScrollHost(list) ?? list?.parentElement ?? null;
+    setHost(found);
+    if (!list || !found) return;
+    // Deliberately geometric rather than `offsetTop`: `offsetTop` is measured
+    // from the nearest POSITIONED ancestor, and the scrolling pane is not one —
+    // so it would report the distance to some outer frame and put every page at
+    // the wrong offset. This is the list's true start inside the scrolled
+    // content, which is the pane's own padding.
+    setScrollMargin(
+      list.getBoundingClientRect().top - found.getBoundingClientRect().top + found.scrollTop,
+    );
+  }, [listRef]);
+
+  const virtualizer = useVirtualizer({
+    count,
+    getScrollElement: () => host,
+    estimateSize,
+    overscan: 1,
+    scrollMargin,
+    measureElement: (element, entry, instance) => {
+      const measured =
+        entry?.borderBoxSize?.[0]?.blockSize ?? element.getBoundingClientRect().height;
+      // A hidden pane measures zero, and so does a layout-less environment.
+      // Recording that would collapse the page to nothing and — because the
+      // measurement is cached — leave it collapsed after the pane is shown
+      // again. Keeping the estimate is the same guard `useViewportSize` carries,
+      // for the same reason.
+      if (measured > 0) return measured;
+      const index = Number(element.getAttribute("data-index"));
+      return Number.isNaN(index) ? 0 : instance.options.estimateSize(index);
+    },
+  });
+
+  const items = virtualizer.getVirtualItems();
+  const scrollOffset = virtualizer.scrollOffset ?? 0;
+
+  // The page under the viewport's top edge — the one a reader would name if you
+  // asked what page they are on.
+  const top = items.find((item) => item.start + item.size > scrollOffset + EDGE_SLACK);
+  const active = top ? top.index + 1 : 1;
+
+  // Where the reader is WITHIN that page, so a scale change can put them back.
+  // Recorded on every scroll rather than captured at the moment of the change:
+  // by then the measurements have already been reset.
+  const anchor = useRef({ index: 0, fraction: 0 });
+  useEffect(() => {
+    if (!top || top.size <= 0) return;
+    // Deliberately NOT clamped at the low end. At the very top of a document the
+    // reader is ABOVE page 1's start — the pane's own padding sits between them —
+    // and flooring that to 0 would scroll the padding away the first time the
+    // scale resolves, so simply opening a file nudges the view.
+    const fraction = (scrollOffset - top.start) / top.size;
+    anchor.current = { index: top.index, fraction: Math.min(fraction, 1) };
+  }, [top, scrollOffset]);
+
+  // ── The page number, in both directions ──────────────────────────────────
+  // Both start at 0 — a page number that cannot occur — so the FIRST value of
+  // `pageNumber` still counts as something the shell asked for. A shell that
+  // mounts already pointing at page 140 (a deep link, a citation restored from a
+  // URL) has made a request that nothing has honoured yet.
+  const reported = useRef(0);
+  const requested = useRef(0);
+
+  const lastActive = useRef(active);
+  useEffect(() => {
+    // Only a CHANGE in the page under the top edge is news. Reporting the
+    // initial value would answer the deep link above with "you are on page 1"
+    // before the scroll that honours it has even been attempted.
+    if (count === 0 || active === lastActive.current) return;
+    lastActive.current = active;
+    if (active === pageNumber) return;
+    reported.current = active;
+    goToPage(active);
+  }, [active, pageNumber, count, goToPage]);
+
+  useEffect(() => {
+    // `host` is resolved in an effect, so the first pass through here has
+    // nothing to scroll — and virtual-core silently drops a scroll with no
+    // element. Waiting for it is what makes the mount-time request land.
+    if (!host || count === 0 || requested.current === pageNumber) return;
+    requested.current = pageNumber;
+    // Our own report coming back around. Scrolling here would fight the gesture
+    // that produced it.
+    if (pageNumber === reported.current || pageNumber === active) return;
+    virtualizer.scrollToIndex(pageNumber - 1, { align: "start" });
+  }, [host, pageNumber, active, count, virtualizer]);
+
+  // ── Re-anchor after a scale change ───────────────────────────────────────
+  const lastSizeKey = useRef(sizeKey);
+  useLayoutEffect(() => {
+    if (lastSizeKey.current === sizeKey) return;
+    lastSizeKey.current = sizeKey;
+    if (count === 0) return;
+
+    // Measured heights describe the OLD scale, so keeping them would place every
+    // page at the wrong offset until it happened to be re-measured.
+    virtualizer.measure();
+
+    const { index, fraction } = anchor.current;
+    // At the very top there is no reading position to preserve, and scrolling to
+    // page 1's own start would scroll the pane's top padding away — so simply
+    // opening a file and letting its fit resolve would nudge the view.
+    if (index === 0 && fraction <= 0) return;
+    const start = virtualizer.getOffsetForIndex(index, "start")?.[0];
+    if (start === undefined) return;
+    const size = virtualizer.measurementsCache[index]?.size ?? 0;
+    virtualizer.scrollToOffset(start + fraction * size, { align: "start" });
+  }, [sizeKey, count, virtualizer]);
+
+  return virtualizer;
+}

package/src/core/use-viewport-size.ts

@@ -0,0 +1,54 @@
+"use client";
+
+/**
+ * The size of the box a renderer scrolls inside, kept current.
+ *
+ * Needed because a fit-to-width scale is a function of the VIEWPORT, not of the
+ * document: only the renderer can compute it, and only by measuring. Measures
+ * the container rather than the window (`window.innerWidth` would be wrong the
+ * moment a viewer sits in a resizable pane, a dialog or a split workspace).
+ */
+
+import { useEffect, useState, type RefObject } from "react";
+
+import { findScrollHost } from "./scroll-host";
+
+export interface ViewportSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * @param ref An element inside the scrolling box — typically the renderer's root.
+ * @returns The scroll host's content size, or `undefined` until it is measured.
+ */
+export function useViewportSize(ref: RefObject<HTMLElement | null>): ViewportSize | undefined {
+  const [size, setSize] = useState<ViewportSize>();
+
+  useEffect(() => {
+    const host = findScrollHost(ref.current) ?? ref.current?.parentElement ?? ref.current;
+    if (!host || typeof ResizeObserver === "undefined") return;
+
+    const measure = () => {
+      const { clientWidth: width, clientHeight: height } = host;
+      // A hidden pane measures zero. Re-fitting to a zero-width viewport would
+      // rasterize a zero-width page and clear the canvas — and nothing would
+      // measure again when the pane is shown, because its size did not change
+      // from the observer's point of view. Ignoring the reading keeps the last
+      // good one. (The guard extend-hq/ui's `useElementWidth` carries too.)
+      if (width === 0 || height === 0) return;
+      setSize((current) =>
+        current && Math.abs(current.width - width) < 1 && Math.abs(current.height - height) < 1
+          ? current
+          : { width, height },
+      );
+    };
+
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(host);
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return size;
+}