@quario/viewer 0.2.0 → 0.4.0

package/lib/stage.js

@@ -1,23 +1,41 @@
 /**
- * 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
+ * [band](../../../CONTEXT.md#band) 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.
+ *
+ * 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 +44,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 +64,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 band 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 +110,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 +120,201 @@ 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 band 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();
 
   /**
-   * 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 pixels back. Sizing the canvas to 0 × 0 is the one idiom
+   * that frees the store synchronously in every engine the viewer runs in;
+   * the CSS size is untouched, so the page keeps its place in the extent and
+   * shows the sheet's white.
    *
-   * @param {boolean} [fresh]
+   * @type {(canvas: HTMLCanvasElement) => void}
    */
-  let marking = (fresh = true) => {
-    clearMarks(sheet);
-    if (fresh) face = null;
-    face ??= faceOf(sheet, page);
-    if (face) placeMarks(sheet, face, page);
+  let release = (canvas) => {
+    if (!backed.has(canvas)) return;
+    backed.delete(canvas);
+    canvas.width = 0;
+    canvas.height = 0;
   };
 
-  /** The percentage currently on screen. */
-  let applied = 100;
+  /** The page width the fit measures against: the list's, or the geometry's
+   * before one arrives. */
+  let pageWidth = () => (list ? list.width : fallback);
+
+  /** CSS pixels per point at the applied percentage. */
+  let ratio = () => (PX_PER_POINT * applied) / 100;
+
+  /**
+   * 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 reach the same page and both
+   * settle behind its pixels. A paint that failed is forgotten, so the next
+   * pass over the band tries again instead of counting the page as painted.
+   *
+   * @type {(canvas: HTMLCanvasElement, i: number) => Promise<void>}
+   */
+  let paintPage = (canvas, i) => {
+    let scale = ratio() * (globalThis.devicePixelRatio || 1);
+    let carrying = backed.get(canvas);
+    if (carrying && carrying.scale === scale) return carrying.painted;
+    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 }).catch((failure) => {
+      backed.delete(canvas);
+      throw failure;
+    });
+    backed.set(canvas, { scale, painted });
+    return painted;
+  };
+
+  /** Bumped per repaint, so a repaint overtaken by the next stops painting. */
+  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 band below is read from the offsets once they are in.
+   */
+  let sizeAll = () => {
+    if (!list) return;
+    let px = ratio();
+    for (let [i, each] of list.pages.entries()) {
+      let canvas = /** @type {HTMLElement} */ (sheet.children[i]);
+      canvas.style.width = each.width * px + "px";
+      canvas.style.height = each.height * px + "px";
+    }
+  };
+
+  /**
+   * The indices of the pages in the band — 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 band ends. `clientHeight` is read afresh each time, so a
+   * pane that changed size changes the band with it.
+   *
+   * @returns {number[]}
+   */
+  let inBand = () => {
+    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 band has left behind, and answer with the ones to
+   * keep, each with its index — 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.
+   *
+   * @type {() => [number, HTMLCanvasElement][]}
+   */
+  let keep = () => {
+    let wanted = new Set(inBand());
+    let kept = [];
+    for (let i = 0; i < sheet.children.length; i++) {
+      let canvas = /** @type {HTMLCanvasElement} */ (sheet.children[i]);
+      if (wanted.has(i)) kept.push(/** @type {[number, HTMLCanvasElement]} */ ([i, canvas]));
+      else release(canvas);
+    }
+    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 band 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, canvas] of keep()) {
+      if (mine !== epoch) return;
+      await paintPage(canvas, i);
+    }
+  };
+
+  /**
+   * The band pass a scroll or a resize runs. 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 reaching 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 band reports it the way any other paint does.
+   */
+  let sync = () => {
+    if (!list) return;
+    for (let [i, canvas] of keep()) paintPage(canvas, i).catch(() => {});
+  };
+
+  /** One band pass a frame, however many scrolls and resizes ask for one. */
+  let pending = false;
+  let follow = () => {
+    if (pending) return;
+    pending = true;
+    requestAnimationFrame(() => {
+      pending = false;
+      sync();
+    });
+  };
+  scroll.addEventListener("scroll", follow);
+
+  /** @type {(i: number, total: number) => HTMLCanvasElement} */
+  let pageOf = (i, total) => {
+    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 when the band reaches it.
+    canvas.width = 0;
+    canvas.height = 0;
+    canvas.setAttribute("role", "img");
+    canvas.setAttribute("aria-label", "Page " + (i + 1) + " of " + total);
+    return canvas;
   };
 
   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;
+      let width = pageWidth() * PX_PER_POINT;
       if (usable <= 0 || !width) return null;
       return (usable / width) * 100;
     },
@@ -285,6 +332,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 band 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 +343,71 @@ 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 band among them painted at the applied
+     * scale. The order is the point of the method: the pages take their size
+     * before the offsets go back, so the browser clamps them against the
+     * extent they will have rather than the one they had — and the band is
+     * read from those offsets, so it is chosen after they are in. What the
+     * returned promise settles behind is the band, 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();
+      list = next;
+      fonts = faces;
+      sheet.replaceChildren(
+        ...next.pages.map((/** @type {any} */ _, /** @type {number} */ i) =>
+          pageOf(i, next.pages.length),
+        ),
+      );
+      sizeAll();
       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 band is measured in.
+        follow();
         changed();
       });
       observer.observe(scroll);
-      observer.observe(sheet);
       return () => observer.disconnect();
     },
   };