@quario/viewer 0.3.0 → 0.5.0

package/lib/stage.js

@@ -1,23 +1,63 @@
 /**
- * The stage: the surface a report is scaled on. It owns the scroll container
- * the reader looks through, the wrapper that carries whatever extent the
- * current scale needs, and the white sheet itself — their elements, their CSS,
- * and every number relating the three.
+ * The stage: the surface the pages are painted on. It owns the scroll
+ * container the reader looks through, the wrapper that carries the gutter,
+ * and the sheet — one canvas per page of the layout list, painted by
+ * `@quario/layout`'s `paint` — their elements, their CSS, and every number
+ * relating them.
  *
- * Scaling is `transform: scale()` from the sheet's top-left corner, with the
- * wrapper sized to the scaled result: a transformed child grows no scroll
- * extent of its own, so without the wrapper a zoomed-in report would simply be
- * clipped.
+ * Zoom is a repaint, not a transform: each page canvas is sized to the
+ * percentage in CSS pixels and painted at that scale times the device pixel
+ * ratio, so text stays crisp at 200% and a screenshot at 50% is what the
+ * reader saw. The list never changes under a zoom — the preview scales and
+ * never reflows (zoom.js says why).
  *
- * What the stage does not decide is which percentage to show: `fit()` measures
- * what would make the sheet span the width available, and `zoom.js` owns the
- * policy over that answer. What is on screen, though, is the stage's own —
- * `percent()` reports it, so no caller keeps a second copy.
+ * Every page keeps its CSS size, but only the
+ * [reach](../../../CONTEXT.md#reach) carries pixels — the pages on screen and
+ * one viewport height either side. The extent the reader scrolls through is
+ * whole and synchronous whatever is painted; what comes and goes is the
+ * backing store, released by sizing a canvas to 0 × 0. A scroll or a resize
+ * runs the same arithmetic over the list's own geometry, coalesced to one
+ * pass a frame. ADR 0043 says what that is worth: painting the whole sheet
+ * asked a thousand-page report for gigabytes of backing store, and past what
+ * the browser would grant the pages simply came up blank.
+ *
+ * **A canvas on the sheet is never re-pointed at a second paint.** `paint()`
+ * awaits before it draws, so a canvas whose paint is still in flight is
+ * *retired* rather than painted over or emptied: it comes off the sheet, its
+ * pixels go back, and a fresh one stands in its place, so the superseded
+ * paint draws into an element nobody is looking at. A canvas whose paint has
+ * settled has nothing that could land late and is re-sized or emptied in
+ * place as before. Without this a zoom landing mid-paint could leave a page
+ * carrying old-scale content on a new-scale canvas, with the memo below
+ * calling it painted so that nothing repainted it again (ADR 0046).
+ *
+ * Retirement is lazy, and only the paint is guarded. A scale change sizes
+ * every page's CSS box at once but retires a page only when the repaint loop
+ * reaches it, so a page further down the reach shows its old pixels stretched
+ * into the new box until its turn comes — the ordinary look of a zoom in
+ * progress, not the artefact above. The cost is that a retired page is a
+ * replaced `role="img"` node: assistive technology reading that page sees it
+ * swapped under them. Judged acceptable because retirement only happens while
+ * that very page is mid-repaint and about to change what it shows anyway, and
+ * because the alternative — a stable wrapper element per page to announce
+ * from — is a second element per page on a sheet ADR 0043 exists to keep
+ * cheap.
+ *
+ * What the stage does not decide is which percentage to show: `fit()`
+ * measures what would make one page span the width available, and `zoom.js`
+ * owns the policy over that answer. What is on screen, though, is the
+ * stage's own — `percent()` reports it, so no caller keeps a second copy.
+ *
+ * The editor builds its own stack of pages next door, and deliberately: what
+ * the two surfaces share is the display list and the size of a point, not the
+ * sheet. Each is a canvas element, a device-pixel size and a `paint()` call
+ * around policy neither could lend the other — this one repaints under zoom
+ * and guards a superseded repaint, that one builds once per swap and lays box
+ * elements over the result.
  */
 
 import { css } from "lit";
-import { geometry } from "./check.js";
-import { FACE, angle, centres, size, span } from "./mark.js";
+import { PX_PER_POINT, paint } from "@quario/layout";
 
 /**
  * Space around the sheet, in px. Read from here and nowhere else: the stage's
@@ -26,10 +66,13 @@ import { FACE, angle, centres, size, span } from "./mark.js";
  */
 let GUTTER = 28;
 
+/** The gap between two pages, in px. */
+let GAP = 16;
+
 export let SURFACE = css`
 /* Where scrollbars take width, the gutter is held whether one is showing or
    not, which is what rules out a feedback loop in the observer \`watch()\`
-   starts: scaling sets the wrapper's height, the height is what decides
+   starts: painting sets the pages' height, the height is what decides
    whether this element needs a vertical scrollbar, and a scrollbar that came
    and went would change the width \`fit()\` measures. Reserving it permanently
    means the width fit reads cannot move in response to the height fit writes.
@@ -43,168 +86,45 @@ export let SURFACE = css`
   scrollbar-gutter: stable;
 }
 
-/* The wrapper carries the margin and the scroll extent: a margin on a scaled
-   child scales with it, and a transformed child grows no extent at all. Only
-   the vertical margin is the gutter as such — the horizontal ones centre
-   whatever slack the fit left over. */
+/* The wrapper carries the gutter. Only the vertical margin is the gutter as
+   such — the horizontal ones centre whatever slack the fit left over. */
 .qv-stage {
+  width: fit-content;
   margin: ${GUTTER}px auto;
 }
 
-/* Sheet is the containing block for on-sheet watermark stamps. */
+/* The sheet is the stack of pages. */
 .qv-sheet {
-  position: relative;
-  box-sizing: border-box;
-  transform-origin: 0 0;
-  background: #fff;
-  color: #000;
-  /* Sheet geometry only. The report text's own family comes from the shared
-     report stylesheet, which the html target ships byte-identically -- a
-     preview and an export that disagree on typeface is the bug this splits
-     apart (docs/adr/0014). */
-  font-size: 10pt;
-  line-height: 1.4;
-  box-shadow: var(--_sheet-shadow);
+  display: flex;
+  flex-direction: column;
+  gap: ${GAP}px;
 }
 
-/* Stamps live under the sheet's transform so zoom/fit scales them. Absolute
-   layer clips rotated glyphs so they never widen scroll extent or feed \`fit()\`
-   — see docs/adr/0017-the-viewer-watermarks-the-sheet.md. */
-.qv-marks {
-  position: absolute;
-  inset: 0;
-  overflow: hidden;
-  pointer-events: none;
-  user-select: none;
-  z-index: 1;
-}
-
-.qv-mark {
-  position: absolute;
-  left: 50%;
-  height: 0;
-  width: 0;
-  overflow: visible;
-  text-align: center;
-}
-
-.qv-mark span {
-  display: inline-block;
-  white-space: nowrap;
-  color: var(--_mark);
-  opacity: 0.15;
+/* One page. The painter fills it white; the background here is what a page
+   outside the reach shows, and what one inside it shows between being sized
+   and being painted. */
+.qv-page {
+  display: block;
+  background: #fff;
+  box-shadow: var(--_sheet-shadow);
 }
 `;
 
 /**
  * @typedef {{ width: number, height: number, margin: number }} PageBox
- * @typedef {{ text: string, turn: number, fontSize: number }} Face
  * @typedef {{ element: HTMLElement, fit: () => number | null,
  *   percent: () => number, scale: (percent: number) => void,
  *   resize: (geometry: PageBox) => void,
- *   swap: (fragment: string) => void,
+ *   swap: (list: any, fonts: any) => Promise<void>,
  *   watch: (changed: () => void) => () => void }} Stage
  */
 
-/** @type {(sheet: HTMLElement, text: string, pxPerPt: number) => number} */
-let measure = (sheet, text, pxPerPt) => {
-  let probe = document.createElement("span");
-  probe.style.cssText =
-    "position:absolute;visibility:hidden;white-space:nowrap;font:" +
-    FACE +
-    // The face the marking is actually drawn in, or the measurement sizes
-    // wording that will be laid out in something else.
-    "pt sans-serif";
-  probe.textContent = text;
-  sheet.append(probe);
-  let width = probe.offsetWidth / pxPerPt;
-  probe.remove();
-  return width;
-};
-
-/** @type {(sheet: HTMLElement, page: PageBox) => number} */
-let rateOf = (sheet, page) => (page.width ? sheet.offsetWidth / page.width : 0);
-
-/**
- * @param {HTMLElement} sheet
- * @param {PageBox} page
- * @param {string} text
- * @param {number} pxPerPt
- * @returns {Face}
- */
-let faceAt = (sheet, page, text, pxPerPt) => ({
-  text,
-  turn: angle(page.width, page.height),
-  fontSize: size(span(page.width, page.height), measure(sheet, text, pxPerPt)),
-});
-
-/**
- * @param {HTMLElement} sheet
- * @param {PageBox} page
- * @returns {Face | null}
- */
-let faceOf = (sheet, page) => {
-  let badge = sheet.querySelector(".q-unlicensed");
-  let pxPerPt = rateOf(sheet, page);
-  if (!badge || !(pxPerPt > 0)) return null;
-  return faceAt(sheet, page, badge.textContent ?? "", pxPerPt);
-};
-
 /**
- * @param {Face} face
- * @param {number} y
- * @returns {HTMLElement}
- */
-let stampAt = (face, y) => {
-  let mark = document.createElement("div");
-  mark.className = "qv-mark";
-  mark.style.top = y + "pt";
-  let wording = document.createElement("span");
-  wording.textContent = face.text;
-  // The same face the PDF target draws the marking in (`families.sans[0]`,
-  // Helvetica): quario's own wording, so the two must not disagree either.
-  wording.style.font = face.fontSize + "pt sans-serif";
-  wording.style.transform = "translate(-50%, -50%) rotate(" + face.turn + "deg)";
-  mark.append(wording);
-  return mark;
-};
-
-/**
- * @param {HTMLElement} sheet
- * @param {Face} face
- * @param {number} sheetPt
- * @param {number} pageHeight
- */
-let paintMarks = (sheet, face, sheetPt, pageHeight) => {
-  let layer = document.createElement("div");
-  layer.className = "qv-marks";
-  layer.setAttribute("aria-hidden", "true");
-  for (let y of centres(sheetPt, pageHeight)) layer.append(stampAt(face, y));
-  sheet.append(layer);
-};
-
-/** @type {(sheet: HTMLElement) => void} */
-let clearMarks = (sheet) => {
-  for (let node of sheet.querySelectorAll(".qv-marks")) node.remove();
-};
-
-/**
- * @param {HTMLElement} sheet
- * @param {Face} face
- * @param {PageBox} page
- */
-let placeMarks = (sheet, face, page) => {
-  let pxPerPt = rateOf(sheet, page);
-  if (!(pxPerPt > 0)) return;
-  paintMarks(sheet, face, sheet.offsetHeight / pxPerPt, page.height);
-};
-
-/**
- * Build the stage and take ownership of the sheet's scale. The element
- * renders `element` into its template; everything else about the three
- * elements stays in here. Geometry arrives through `resize` rather than
- * construction, because the `page` property can change over the element's
- * lifetime.
+ * Build the stage and take ownership of the pages' scale. The element
+ * renders `element` into its template; everything else about the elements
+ * stays in here. Geometry arrives through `resize` rather than construction,
+ * because the `page` property can change over the element's lifetime — it
+ * sizes what `fit()` measures against before a list has arrived.
  *
  * @returns {Stage}
  */
@@ -212,8 +132,8 @@ export let stage = () => {
   let scroll = document.createElement("div");
   scroll.className = "qv-scroll";
   let wrapper = document.createElement("div");
-  // The class names the part that carries the scroll extent; "the stage" in
-  // the glossary is this whole surface, the way `.qv-viewer` is one element
+  // The class names the part that carries the gutter; "the stage" in the
+  // glossary is this whole surface, the way `.qv-viewer` is one element
   // inside the viewer. The `qv-*` names are documented as stable, so the
   // narrower one keeps its name.
   wrapper.className = "qv-stage";
@@ -222,52 +142,315 @@ export let stage = () => {
   wrapper.append(sheet);
   scroll.append(wrapper);
 
-  let page = geometry(undefined);
-  /** @type {Face | null} */
-  let face = null;
+  /** The page width to fit against before a list arrives, in points. */
+  let fallback = 0;
+  /** @type {any} */
+  let list = null;
+  /** @type {any} */
+  let fonts;
+  /** The percentage currently on screen. */
+  let applied = 100;
+
+  /**
+   * What each backed page is carrying: the scale it was painted at, so a page
+   * re-entering the reach at that scale is not repainted and a scale change
+   * invalidates it, and the paint itself, so whoever asks second waits behind
+   * the paint the first caller started rather than being told it is done.
+   * Keyed by the canvas, so a swap's new pages start with nothing remembered
+   * and the pages it replaced take their entries with them — which is why the
+   * map is weak: nothing has to remember to forget them.
+   *
+   * @type {WeakMap<HTMLCanvasElement, { scale: number, painted: Promise<void> }>}
+   */
+  let backed = new WeakMap();
+
+  /**
+   * The canvases whose paint has finished. A promise's settled state is not
+   * synchronously observable and this is the one question the rule below
+   * turns on: a canvas in here has nothing left that could draw into it, so
+   * it can be emptied or re-sized in place; one that is backed but absent
+   * here is still being painted, and must be retired instead. Weak on the
+   * same key as `backed`, so a retired canvas takes its membership with it.
+   *
+   * Membership is per paint, not per canvas — `start` takes a canvas out
+   * before painting it again, or a page settled at one scale would count as
+   * settled the moment it began painting at the next.
+   *
+   * @type {WeakSet<HTMLCanvasElement>}
+   */
+  let settled = new WeakSet();
+
+  /** CSS pixels per point at the applied percentage. */
+  let ratio = () => (PX_PER_POINT * applied) / 100;
+
+  /**
+   * The canvas standing for page `i` right now. Read through here and never
+   * held: a retired page is a different element, so a canvas taken before an
+   * await may be off the sheet by the time it is used.
+   *
+   * @type {(i: number) => HTMLCanvasElement}
+   */
+  let pageAt = (i) => /** @type {HTMLCanvasElement} */ (sheet.children[i]);
 
   /**
-   * Show the marking this fragment carries, or none. Wording is the engine's
-   * on the html target's badge; stamps are presentation on the sheet (ADR 0017).
-   * `fresh` remeasures the face (swap / page change); height-only updates reuse it.
+   * Give a page's canvas its size on screen. The one answer to how big page
+   * `i` is at the applied percentage: `pageOf` builds a canvas with it and
+   * `sizeAll` writes it over the sheet after a scale change, so a page
+   * retired between the two cannot arrive sizeless and move the extent the
+   * reader is scrolling through.
    *
-   * @param {boolean} [fresh]
+   * @type {(canvas: HTMLElement, i: number, px?: number) => void}
    */
-  let marking = (fresh = true) => {
-    clearMarks(sheet);
-    if (fresh) face = null;
-    face ??= faceOf(sheet, page);
-    if (face) placeMarks(sheet, face, page);
+  let sizePage = (canvas, i, px = ratio()) => {
+    let each = list.pages[i];
+    canvas.style.width = each.width * px + "px";
+    canvas.style.height = each.height * px + "px";
   };
 
-  /** The percentage currently on screen. */
-  let applied = 100;
+  /**
+   * One page of the list as a canvas: sized on screen, carrying no pixels
+   * yet, and named for a screen reader. Every canvas on the sheet is built
+   * here — a swap's and a retirement's alike — so a replacement is the same
+   * element in every respect but identity.
+   *
+   * @type {(i: number) => HTMLCanvasElement}
+   */
+  let pageOf = (i) => {
+    let canvas = document.createElement("canvas");
+    canvas.className = "qv-page";
+    // A canvas is 300 x 150 until told otherwise, and that store counts. A
+    // page starts with none and takes one once it is inside the reach.
+    canvas.width = 0;
+    canvas.height = 0;
+    canvas.setAttribute("role", "img");
+    canvas.setAttribute("aria-label", "Page " + (i + 1) + " of " + list.pages.length);
+    sizePage(canvas, i);
+    return canvas;
+  };
+
+  /**
+   * Take page `i`'s canvas off the sheet and stand a fresh one in its place,
+   * answering with the replacement. A paint still in flight holds the old
+   * canvas's context and draws into something nobody is looking at, which is
+   * how a superseded paint is stopped here — by construction, rather than by
+   * a check the painter would have to make above its own draw (ADR 0046).
+   * The retired canvas takes its entries in `backed` and `settled` with it.
+   *
+   * Its pixels go back at once, by the same 0 × 0 idiom `release` uses: the
+   * store is what ADR 0043 rations, and leaving it to be collected whenever
+   * the superseded paint lets go of the context is the timing that ADR
+   * refuses. `paint()` does its whole `save`/draw/`restore` after its awaits,
+   * so emptying the canvas between them unbalances nothing — it just leaves
+   * every op clipped to nothing, which spares the raster work too.
+   *
+   * @type {(i: number) => HTMLCanvasElement}
+   */
+  let retire = (i) => {
+    let old = pageAt(i);
+    let fresh = pageOf(i);
+    old.replaceWith(fresh);
+    old.width = 0;
+    old.height = 0;
+    return fresh;
+  };
+
+  /**
+   * Give page `i`'s pixels back. A page whose paint has settled is emptied in
+   * place: sizing the canvas to 0 × 0 is the one idiom that frees the store
+   * synchronously in every engine the viewer runs in, and the CSS size is
+   * untouched, so the page keeps its place in the extent and shows the
+   * sheet's white. A page still painting is retired instead — emptying it
+   * would leave that paint pointed at a canvas the next pass over the reach
+   * re-sizes and re-paints.
+   *
+   * @type {(i: number) => void}
+   */
+  let release = (i) => {
+    let canvas = pageAt(i);
+    if (!backed.has(canvas)) return;
+    if (!settled.has(canvas)) return void retire(i);
+    backed.delete(canvas);
+    canvas.width = 0;
+    canvas.height = 0;
+  };
+
+  /** Device pixels per point at the applied percentage: what a page is
+   * painted at, and what its backing store is sized in. */
+  let deviceScale = () => ratio() * (globalThis.devicePixelRatio || 1);
+
+  /**
+   * Start painting page `i`, and answer with that paint. **The one place a
+   * paint begins, and the one place the rule is enforced**: a canvas whose
+   * paint is still in flight is retired here before a second one is pointed
+   * at it, so no caller can reach a live canvas with a second paint by
+   * forgetting to ask first (ADR 0046). A paint that failed is forgotten, so
+   * the next pass over the reach tries again instead of counting the page as
+   * painted; one that settles joins `settled`.
+   *
+   * @type {(i: number) => Promise<void>}
+   */
+  let start = (i) => {
+    let canvas = pageAt(i);
+    if (backed.has(canvas) && !settled.has(canvas)) canvas = retire(i);
+    settled.delete(canvas);
+    let scale = deviceScale();
+    let each = list.pages[i];
+    canvas.width = Math.round(each.width * scale);
+    canvas.height = Math.round(each.height * scale);
+    let ctx = /** @type {CanvasRenderingContext2D} */ (canvas.getContext("2d"));
+    let painted = paint(ctx, each, { scale, fonts }).then(
+      () => {
+        settled.add(canvas);
+      },
+      (failure) => {
+        backed.delete(canvas);
+        throw failure;
+      },
+    );
+    backed.set(canvas, { scale, painted });
+    return painted;
+  };
+
+  /**
+   * Paint one page and answer with that paint — or with the paint already
+   * under way at this scale, which is what makes scrolling back over ground
+   * already covered free. Answering with the paint rather than with a
+   * resolved promise is what lets two callers share one page's paint and both
+   * settle behind its pixels.
+   *
+   * Takes the index, not the canvas: the page it paints may be retired out
+   * from under a caller, so a caller that handed one in would be left holding
+   * an element that is no longer on the sheet.
+   *
+   * @type {(i: number) => Promise<void>}
+   */
+  let paintPage = (i) => {
+    let carrying = backed.get(pageAt(i));
+    if (carrying && carrying.scale === deviceScale()) return carrying.painted;
+    return start(i);
+  };
+
+  /**
+   * Bumped per repaint, so a repaint overtaken by the next stops walking.
+   * What that guards is the backing store, not the pixels: a superseded loop
+   * would paint at the *current* scale — `paintPage` reads it afresh — but
+   * onto pages the newer reach has since dropped, re-backing pages that
+   * should be blank (ADR 0043). Stale pixels are `retire`'s business, not
+   * this one, so neither guard stands in for the other.
+   *
+   * It guards repaint against repaint, and nothing else. A repaint chooses
+   * its pages once and holds that list across its awaits, so a scroll pass
+   * releasing a page mid-repaint is one this loop will paint anyway; the
+   * store that leaves behind is bounded by the reach and goes back on the
+   * next pass over it.
+   */
+  let epoch = 0;
+
+  /**
+   * Give every page its CSS size. Callers run this before writing the scroll
+   * offsets back: the extent those offsets are clamped against is this one,
+   * and the reach below is read from the offsets once they are in.
+   */
+  let sizeAll = () => {
+    if (!list) return;
+    let px = ratio();
+    for (let i = 0; i < list.pages.length; i++) sizePage(pageAt(i), i, px);
+  };
+
+  /**
+   * The indices of the pages in the reach — the ones the viewport shows, and
+   * everything within one viewport height above or below. Walked over the
+   * list's own geometry (the gutter, each page's height at the applied
+   * scale, the gap), never a layout read, so it costs nothing to ask
+   * mid-scroll — the whole list is walked because a multiply and an add per
+   * page is beneath measuring, and stopping early would be a second rule
+   * about where the reach ends. `clientHeight` is read afresh each time, so a
+   * pane that changed size changes the reach with it.
+   *
+   * @returns {number[]}
+   */
+  let inReach = () => {
+    let view = scroll.clientHeight;
+    let top = scroll.scrollTop - view;
+    let bottom = scroll.scrollTop + 2 * view;
+    let px = ratio();
+    let y = GUTTER;
+    let found = [];
+    for (let [i, each] of list.pages.entries()) {
+      let height = each.height * px;
+      if (y + height >= top && y <= bottom) found.push(i);
+      y += height + GAP;
+    }
+    return found;
+  };
+
+  /**
+   * Release every page the reach has left behind, and answer with the indices
+   * of the ones to keep, in the order they are painted in. The single
+   * definition of which pages carry pixels: the repaint below and the scroll
+   * pass both go through here, and neither holds a page the other released.
+   *
+   * Indices rather than elements, for the reason `paintPage` takes one: a
+   * page can be retired between this pass and the paint that follows it.
+   *
+   * @type {() => number[]}
+   */
+  let keep = () => {
+    let wanted = new Set(inReach());
+    let kept = [];
+    // `retire` replaces one for one, so the count is fixed across the walk.
+    for (let i = 0, total = sheet.children.length; i < total; i++) {
+      if (wanted.has(i)) kept.push(i);
+      else release(i);
+    }
+    return kept;
+  };
 
-  // Write the scale and size the wrapper against it. Both reads are layout
-  // metrics, unaffected by the transform, so the wrapper is sized from the
-  // sheet's own untransformed box — and both come before any write, so a
-  // paint costs one layout pass rather than one per measurement.
-  let paint = () => {
-    let factor = applied / 100;
-    let width = sheet.offsetWidth;
-    let height = sheet.offsetHeight;
-    sheet.style.transform = factor === 1 ? "" : "scale(" + factor + ")";
-    wrapper.style.width = width * factor + "px";
-    wrapper.style.height = height * factor + "px";
+  // Paint the reach in order, yielding between pages and giving way to any
+  // repaint that started since. Sizing is the caller's, and comes first.
+  let repaint = async () => {
+    if (!list) return;
+    let mine = ++epoch;
+    for (let i of keep()) {
+      if (mine !== epoch) return;
+      await paintPage(i);
+    }
   };
 
+  /**
+   * One reach pass a frame, however many scrolls and resizes ask for one. It
+   * keeps no epoch of its own, so a swap painting behind it is never cut off
+   * part-painted, and a page it starts is one a swap arriving at the same page
+   * waits behind rather than skips. Nothing awaits these paints here: a scroll
+   * is not a render and has no failure channel of its own, and a paint that
+   * failed is forgotten, so the next pass over the reach reports it the way
+   * any other paint does.
+   */
+  let pending = false;
+  let follow = () => {
+    if (pending) return;
+    pending = true;
+    requestAnimationFrame(() => {
+      pending = false;
+      if (!list) return;
+      for (let i of keep()) paintPage(i).catch(() => {});
+    });
+  };
+  scroll.addEventListener("scroll", follow);
+
   return {
     element: scroll,
 
     /**
-     * The percentage at which the sheet spans the width available to it, or
+     * The percentage at which one page spans the width available to it, or
      * `null` when there is nothing to measure against — a `display: none`
      * host, or a pane narrower than its own gutters. A caller with nothing to
      * compute from keeps what is on screen rather than scaling to a guess.
      */
     fit: () => {
       let usable = scroll.clientWidth - 2 * GUTTER;
-      let width = sheet.offsetWidth;
+      // The list's page width, or the geometry's before one arrives.
+      let width = (list ? list.width : fallback) * PX_PER_POINT;
       if (usable <= 0 || !width) return null;
       return (usable / width) * 100;
     },
@@ -285,6 +468,9 @@ export let stage = () => {
      * are 0 once it overflows, so the plain ratio holds wherever it can be
      * seen. The browser clamps whatever it cannot honour. An empty sheet has
      * no view to hold, which is what mounting at an authored zoom takes.
+     *
+     * Only the reach is repainted, and only where the scale actually changed,
+     * so a zoom step costs a handful of pages however long the report is.
      */
     scale: (percent) => {
       let held = sheet.firstChild && {
@@ -293,83 +479,72 @@ export let stage = () => {
         height: scroll.clientHeight,
         width: scroll.clientWidth,
       };
-      let ratio = percent / applied;
+      let ratioOf = percent / applied;
       applied = percent;
-      paint();
-      if (!held) return;
-      let middle = held.top + held.height / 2 - GUTTER;
-      scroll.scrollTop = GUTTER + middle * ratio - held.height / 2;
-      scroll.scrollLeft = (held.left + held.width / 2) * ratio - held.width / 2;
+      sizeAll();
+      if (held) {
+        let middle = held.top + held.height / 2 - GUTTER;
+        scroll.scrollTop = GUTTER + middle * ratioOf - held.height / 2;
+        scroll.scrollLeft = (held.left + held.width / 2) * ratioOf - held.width / 2;
+      }
+      void repaint();
     },
 
     /**
-     * Give the sheet its point geometry. Page points are CSS points, so the
-     * host's values transfer unit-for-unit; the wrapper re-sizes against the
-     * result so the scroll extent keeps describing what is there.
-     *
-     * The sheet is the page's shape: its width, and at least one page tall,
-     * the same rule the editor's sheet follows. A minimum rather than a
-     * height, because the sheet stays one continuous surface -- so the height
-     * goes on serving as the watermark stamp period along it too
-     * (docs/adr/0035).
+     * Give the stage its page width, for the fit an empty sheet measures
+     * against. A list that has arrived carries its own; the geometry it was
+     * laid out on is the geometry the next render uses.
      *
      * @param {PageBox} next
      */
     resize: (next) => {
-      page = next;
-      sheet.style.width = next.width + "pt";
-      sheet.style.minHeight = next.height + "pt";
-      sheet.style.padding = next.margin + "pt";
-      marking(true);
-      paint();
+      fallback = next.width;
     },
 
     /**
-     * Put a rendered fragment on the sheet, keeping the reader where they
-     * were. The order is the point of the method: the wrapper takes the new
-     * content's height before the offsets go back, so the browser clamps them
-     * against the extent they will have rather than the one they had.
+     * Put a laid-out report on the sheet, keeping the reader where they
+     * were: one canvas per page, the reach among them painted at the applied
+     * scale. The order is the point of the method: the pages come off
+     * `pageOf` already at their size, so the browser clamps the offsets going
+     * back against the extent the sheet will have rather than the one it had
+     * — and the reach is read from those offsets, so it is chosen after they
+     * are in. What the
+     * returned promise settles behind is the reach, which is what the caller's
+     * `renderComplete` means by "the pages on screen are painted".
      */
-    swap: (fragment) => {
+    swap: async (next, faces) => {
       // Reading the offsets flushes layout, so only an actual reswap pays for
       // it: on an empty sheet there is nothing scrolled to preserve.
-      let held = sheet.firstChild && { top: scroll.scrollTop, left: scroll.scrollLeft };
-      // The viewer's one markup edge. What goes in is the html target's
-      // documented output, injected the documented way. Watermark stamps are
-      // presentation synthesized after from the badge (ADR 0017) — not report
-      // content (hard constraint 4).
-      sheet.innerHTML = fragment;
-      face = null;
-      marking(true);
-      // A resize, not a zoom — the scale has not changed, so nothing
-      // recentres here or it would fight the restore below.
-      paint();
+      let held = sheet.firstChild && {
+        top: scroll.scrollTop,
+        left: scroll.scrollLeft,
+      };
+      list = next;
+      fonts = faces;
+      sheet.replaceChildren(
+        ...next.pages.map((/** @type {any} */ _, /** @type {number} */ i) => pageOf(i)),
+      );
       if (held) {
         scroll.scrollTop = held.top;
         scroll.scrollLeft = held.left;
       }
+      await repaint();
     },
 
     /**
      * Watch the box for changes the viewer learns of no other way — a
      * collapsed side panel, a resized window, a flex sibling appearing — so a
-     * fitted sheet can follow its host. Also watches sheet height so stamp
-     * density tracks layout. Returns the disposer; what rules out a fit
-     * feedback loop is the CSS above.
+     * fitted page can follow its host. Returns the disposer; what rules out a
+     * fit feedback loop is the CSS above.
      */
     watch: (changed) => {
-      let last = sheet.offsetHeight;
       let observer = new ResizeObserver(() => {
-        let height = sheet.offsetHeight;
-        if (height !== last) {
-          last = height;
-          marking(false);
-          paint();
-        }
+        // A resize that changes the fit repaints through `changed()`; one
+        // that does not still moved the viewport the reach is measured in.
+        follow();
         changed();
       });
       observer.observe(scroll);
-      observer.observe(sheet);
       return () => observer.disconnect();
     },
   };