@quario/viewer 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-07
+
+### Added
+
+- **`fonts` is validated as a host property.** It was the one the viewer never
+  checked, so a malformed record reached the target inside the render and came
+  back as a render failure about a report that was never at fault. Its shape is
+  now checked with the other host properties and named on `fonts` rather than
+  on the target's `options.fonts`. A face that will not parse, or a missing
+  parser, is still found while the report is measured and remains a render
+  failure there.
+
+### Changed
+
+- **A rejected host property reports as `host-option`.** `ViewerErrorKind`
+  gains a fourth member, so a host switching exhaustively over the kind needs
+  a case for it. A `page`, `zoom`, `filename`, `colorScheme` or `fonts` the
+  viewer rejected was reported as `mount-render` or `update-render` — a render
+  that was never attempted — and the panel said "Could not render the report",
+  which reads as the report being at fault. It now says the viewer is
+  misconfigured and that the report was not the problem.
+
+  A malformed `report` or `targets` still reports as a render failure: those
+  are refused where the render begins rather than when the property is written,
+  so nothing yet tells them apart from a render that failed.
+
 ## [0.6.0] - 2026-09-07
 
 ### Changed

package/lib/check.js

@@ -9,7 +9,7 @@
  * Pure policy, no DOM: this module is what the Node suite pins.
  */
 
-import { pageBox } from "@quario/layout";
+import { checkFonts, pageBox } from "@quario/layout";
 import { STEPS } from "./zoom.js";
 
 /** @type {(message: string) => never} */
@@ -55,6 +55,22 @@ export let geometry = (page) => {
   }
 };
 
+/**
+ * The font mapping from the `fonts` property. Only the shape reaches here: a
+ * face that will not parse, or a missing parser, is found while the report is
+ * measured and is a render failure there. The layout names the mistake; this
+ * names the property, the way `geometry` does.
+ *
+ * @param {any} fonts
+ */
+export let faces = (fonts) => {
+  try {
+    checkFonts(fonts, "fonts");
+  } catch (error) {
+    fail(/** @type {Error} */ (error).message);
+  }
+};
+
 /** @type {(mode: any, floor: number, ceiling: number) => boolean} */
 let inRange = (mode, floor, ceiling) =>
   [Number.isFinite(mode), mode >= floor, mode <= ceiling].every(Boolean);

package/lib/index.d.ts

@@ -24,16 +24,17 @@ export type ViewerFonts = LayoutFonts;
 export type ViewableReport = CompiledReport;
 
 /** Which failure an `error` event names. */
-export type ViewerErrorKind = "mount-render" | "update-render" | "export";
+export type ViewerErrorKind = "mount-render" | "update-render" | "export" | "host-option";
 
 /** The `error` event's payload. */
 export interface ViewerErrorDetail {
   /** The caught value, exactly as thrown. */
   error: unknown;
   /**
-   * Which failure occurred: `mount-render` until a render has ever landed
-   * on the sheet, `update-render` after, `export` for a download that could not
-   * be produced.
+   * Which failure occurred: `host-option` for a property the viewer rejected,
+   * which reached no render at all; otherwise `mount-render` until a render
+   * has ever landed on the sheet, `update-render` after, and `export` for a
+   * download that could not be produced.
    */
   kind: ViewerErrorKind;
 }

package/lib/index.js

@@ -26,10 +26,11 @@
  */
 import { Task, TaskStatus } from "@lit/task";
 import { LitElement, html } from "lit";
+import { Landing, failures, options } from "@quario/landing";
 import { layout } from "@quario/layout";
 import { BUTTON } from "./button.js";
 import { CHROME, progress } from "./chrome.js";
-import { exports, geometry, level, name, scheme } from "./check.js";
+import { exports, faces, geometry, level, name, scheme } from "./check.js";
 import { MENU, zoomMenu } from "./menu.js";
 import { PANEL, label, panel } from "./panel.js";
 import { SURFACE, stage } from "./stage.js";
@@ -39,12 +40,6 @@ import { wanted } from "./zoom.js";
 /** @type {(report: unknown, targets: unknown) => boolean} */
 let vacant = (report, targets) => report === undefined && targets === undefined;
 
-/** @type {(error: unknown) => unknown} */
-let said = (error) => {
-  // oxlint-disable-next-line typescript/no-base-to-string
-  return error && String(error);
-};
-
 // The properties are described once, in the hand-written public declarations,
 // and read back here — a second copy in JSDoc is a copy that drifts.
 /** @import { ViewableReport, ViewerFonts, ViewerPage } from './index.d.ts' */
@@ -89,23 +84,23 @@ export class QuarioViewer extends LitElement {
   // fails and a disconnect that does not. The template interpolates its
   // element as a node, which lit-html leaves untouched across re-renders.
   #stage = stage();
-  /** Whether a render has ever landed on the sheet — the mount/update boundary. */
-  #landed = false;
-  /** Whether the sheet stopped matching the properties while disconnected. */
-  #stale = false;
   /** @type {"fit" | number} The live zoom mode; the controls move it. */
   #mode = "fit";
   /** @type {{ width: number, height: number, margin: number }} */
   #box = geometry(undefined);
   #name = "report";
-  /** A property the host got wrong, rethrown by the task so it reports once. */
-  /** @type {unknown} */
-  #invalid;
-  /** Bumped to re-run the task when its real arguments did not change. */
-  #epoch = 0;
-  /** @type {{ label: string, error: unknown } | undefined} */
-  #failure;
-  #dismissed = false;
+  /** The option check across one update cycle: first-failure-wins, the
+   * re-validate-everything rule, and the commit gate that keeps a `filename`
+   * write from clobbering the mode a reader clicked to. */
+  #options = options();
+  /** The render boundary — landed, stale, and the epoch that re-runs the task
+   * when its real arguments did not change. */
+  #landing = new Landing(this, { abort: () => this.#task.abort() });
+  /** The panel's model, with this element's own announce policy: every
+   * failure is drawn, because the viewer only re-runs when a host property or
+   * the epoch moves, so its rate is already bounded. The panel is a state and
+   * the error event is the log. */
+  #failures = failures();
   /** Re-applies geometry and scale after the update that changed them. */
   #reapply = false;
   /** @type {Set<string>} The exports in flight; their buttons disable. */
@@ -130,7 +125,7 @@ export class QuarioViewer extends LitElement {
   // show" result: unlike the task primitive's own initial-state symbol it
   // settles `taskComplete`, which is what lets `renderComplete` always answer.
   #task = new Task(this, {
-    args: () => [this.report, this.targets, this.data, this.page, this.fonts, this.#epoch],
+    args: () => [this.report, this.targets, this.data, this.page, this.fonts, this.#landing.epoch],
     task: async ([report, targets, data, page, fonts], { signal }) => {
       if (!this.#begin(report, targets)) return null;
       // The sheet's own target: the layout list, on the host's page and
@@ -141,7 +136,7 @@ export class QuarioViewer extends LitElement {
       // The engine takes no signal, so abandonment is the guards around this
       // body; the check only spares the swap when the answer arrives after a
       // disconnect mid-render.
-      if (signal.aborted && !this.isConnected) return this.#abandon();
+      if (this.#landing.dropped(signal, this.isConnected)) return this.#landing.abandon();
       return { list, fonts };
     },
     onComplete: (result) => {
@@ -149,14 +144,12 @@ export class QuarioViewer extends LitElement {
       // The swap sizes every page before it settles, so the reader's place
       // is held; the paint it awaits is what `rendered` waits for.
       this.#painting = this.#stage.swap(result.list, result.fonts).then(() => {
-        this.#landed = true;
-        this.#stale = false;
+        this.#landing.land();
         // A render that landed on the sheet takes the panel down: the panel
         // says what is wrong with what the reader is looking at, and this is
         // the moment that stops being true. A successful export is not that
         // moment.
-        this.#failure = undefined;
-        this.#dismissed = false;
+        this.#failures.clear();
         // After the paint, so the update the task queued has already run.
         this.requestUpdate();
         this.dispatchEvent(new CustomEvent("rendered"));
@@ -164,7 +157,7 @@ export class QuarioViewer extends LitElement {
     },
     onError: (error) => {
       if (!this.isConnected) return;
-      this.#announce(error, this.#landed ? "update-render" : "mount-render");
+      this.#announce(error, this.#kindOf(error));
     },
   });
 
@@ -205,9 +198,9 @@ export class QuarioViewer extends LitElement {
   get renderComplete() {
     return this.updateComplete.then(() =>
       this.#task.status === TaskStatus.INITIAL
-        ? this.#landed
+        ? this.#landing.landed
         : this.#task.taskComplete.then(
-            () => this.#painting.then(() => this.#landed),
+            () => this.#painting.then(() => this.#landing.landed),
             () => false,
           ),
     );
@@ -227,7 +220,7 @@ export class QuarioViewer extends LitElement {
       this.#checkOptions(changed);
     // A new document is a new subject: dismissing the last failure said
     // nothing about this one.
-    if (["data", "report"].some((key) => changed.has(key))) this.#dismissed = false;
+    if (["data", "report"].some((key) => changed.has(key))) this.#failures.reopen();
   }
 
   render() {
@@ -247,7 +240,7 @@ export class QuarioViewer extends LitElement {
           })}
         </div>
         <div class="qv-body">
-          ${this.#failure && !this.#dismissed ? panel(this.#failure, () => this.#dismiss()) : ""}
+          ${this.#failures.showing ? panel(this.#failures.showing, () => this.#dismiss()) : ""}
           ${this.#stage.element}
         </div>
       </div>
@@ -276,14 +269,12 @@ export class QuarioViewer extends LitElement {
     // property write landed while disconnected. The task's arguments did not
     // change, so the epoch is what re-runs it; left alone, reparenting a
     // settled viewer costs nothing.
-    this.#wake();
   }
 
   disconnectedCallback() {
     super.disconnectedCallback();
     // Abandon in-flight work and release the observer. The properties and the
     // sheet persist: removal is destruction only in the collector's sense.
-    this.#task.abort();
     this.#unwatch?.();
     this.#unwatch = undefined;
   }
@@ -299,27 +290,13 @@ export class QuarioViewer extends LitElement {
    * @param {unknown} targets
    */
   #begin(report, targets) {
-    if (this.#invalid) throw this.#invalid;
+    if (this.#options.invalid) throw this.#options.invalid;
     if (vacant(report, targets)) return null;
-    if (!this.isConnected) return this.#abandon();
+    if (!this.isConnected) return this.#landing.abandon();
     exports(report, targets);
     return true;
   }
 
-  #abandon() {
-    this.#stale = true;
-    return null;
-  }
-
-  /** @param {() => void} run */
-  #take(run) {
-    try {
-      run();
-    } catch (error) {
-      this.#invalid ??= error;
-    }
-  }
-
   /**
    * Each property validates and commits on its own, stashing the first
    * failure: one bad property must not block a good write to another. All
@@ -336,42 +313,59 @@ export class QuarioViewer extends LitElement {
    * @param {Map<string, unknown>} changed
    */
   #checkOptions(changed) {
-    let was = this.#invalid;
-    this.#invalid = undefined;
-    this.#take(() => {
-      let box = geometry(this.page);
-      if (!this.hasUpdated || changed.has("page")) {
-        this.#box = box;
-        this.#reapply = true;
-      }
-    });
-    this.#take(() => {
-      let mode = level(this.zoom);
-      // Committed only when the host wrote `zoom`, so re-validating on a
-      // filename change cannot clobber the mode the reader clicked to.
-      if (!this.hasUpdated || changed.has("zoom")) {
-        this.#mode = mode;
-        this.#reapply = true;
-      }
-    });
-    this.#take(() => {
-      this.#name = name(this.filename);
-    });
-    this.#take(() => {
-      let used = scheme(this.colorScheme);
-      // Same gate as zoom/page: re-validate always, write the CSSOM pin only
-      // when this property changed, so a filename write does not dirty
-      // inherited color-scheme before layout.
-      if (!this.hasUpdated || changed.has("colorScheme")) this.style.colorScheme = used;
-    });
-    if (said(was) !== said(this.#invalid)) this.#epoch++;
+    let moved = this.#options.recheck(this.hasUpdated, changed, [
+      (gate) => {
+        let box = geometry(this.page);
+        if (gate("page")) {
+          this.#box = box;
+          this.#reapply = true;
+        }
+      },
+      (gate) => {
+        // Committed only when the host wrote `zoom`, so re-validating on a
+        // filename change cannot clobber the mode the reader clicked to.
+        let mode = level(this.zoom);
+        if (gate("zoom")) {
+          this.#mode = mode;
+          this.#reapply = true;
+        }
+      },
+      () => void (this.#name = name(this.filename)),
+      // Nothing to commit: the shape is the whole answer, and the faces
+      // themselves are loaded inside the render where a bad one is a render
+      // failure. Checked here so a malformed record is a mistake named on the
+      // property rather than one the target names on `options.fonts`.
+      () => faces(this.fonts),
+      (gate) => {
+        // Same gate as zoom/page: re-validate always, write the CSSOM pin only
+        // when this property changed, so a filename write does not dirty
+        // inherited color-scheme before layout.
+        let used = scheme(this.colorScheme);
+        if (gate("colorScheme")) this.style.colorScheme = used;
+      },
+    ]);
+    if (moved) this.#landing.epoch++;
   }
 
-  #wake() {
-    if (this.#stale || this.#task.status === TaskStatus.PENDING) {
-      this.#epoch++;
-      this.requestUpdate();
-    }
+  /**
+   * Which failure a throw from the task is. Identity, not a tag: `#begin`
+   * throws the very value `#checkOptions` stashed, so the one it stashed is
+   * the one host mistake this can name for certain — and a property the
+   * viewer rejected reached no render at all, so it carries no
+   * mount-versus-update distinction.
+   *
+   * `exports()`'s `report` and `targets` are host mistakes too and still
+   * report as a render: they are thrown from `#begin` rather than stashed, so
+   * nothing here tells them from a render that failed. Closing that means the
+   * task returning failures instead of throwing them, which is the channel
+   * quario-70jg.27 reworks — not worth doing twice.
+   *
+   * @param {unknown} error
+   * @returns {import('./index.d.ts').ViewerErrorKind}
+   */
+  #kindOf(error) {
+    if (error !== undefined && error === this.#options.invalid) return "host-option";
+    return this.#landing.landed ? "update-render" : "mount-render";
   }
 
   /** @param {() => void} run */
@@ -408,7 +402,7 @@ export class QuarioViewer extends LitElement {
   }
 
   #dismiss() {
-    this.#dismissed = true;
+    this.#failures.dismiss();
     this.requestUpdate();
   }
 
@@ -418,12 +412,11 @@ export class QuarioViewer extends LitElement {
    * or anything after a disconnect — never come through here.
    *
    * @param {unknown} error The caught value.
-   * @param {"mount-render" | "update-render" | "export"} kind
+   * @param {import('./index.d.ts').ViewerErrorKind} kind
    * @param {string} [format] The export format's name, for that kind alone.
    */
   #announce(error, kind, format) {
-    this.#failure = { error, label: label(kind, format) };
-    this.#dismissed = false;
+    this.#failures.announce(label(kind, format), error);
     this.requestUpdate();
     this.dispatchEvent(new CustomEvent("error", { detail: { error, kind } }));
   }

package/lib/panel.js

@@ -80,16 +80,23 @@ export let PANEL = css`
  * its length: that failure leaves the previous report on the sheet, and
  * silently stale content is the thing the panel exists to prevent.
  *
- * @param {"mount-render" | "update-render" | "export"} kind
+ * @param {import('./index.d.ts').ViewerErrorKind} kind
  * @param {string} [format] The export format's name, for that kind alone.
  * @returns {string}
  */
 export let label = (kind, format) =>
   kind === "export"
     ? "Could not export " + format
-    : kind === "update-render"
-      ? "Could not update the report — showing the previous version"
-      : "Could not render the report";
+    : kind === "host-option"
+      ? // Named apart because the panel speaks to the reader, and where that
+        // reader is a playground's visitor the panel is the product rather
+        // than chrome (CONTEXT.md, "Error panel"). Told the report could not
+        // be rendered, they read it as their own document failing. A property
+        // they cannot see and cannot fix is where that reading is wrong.
+        "This viewer is misconfigured — the report itself was not the problem."
+      : kind === "update-render"
+        ? "Could not update the report — showing the previous version"
+        : "Could not render the report";
 
 /**
  * What an error says. Not every throw is an `Error` — a host's registry

package/lib/stage.js

@@ -70,17 +70,12 @@
  */
 
 import { css } from "lit";
-import { PX_PER_POINT, paint } from "@quario/layout";
+import { GAP, GUTTER, sheet } from "@quario/landing";
+import { PX_PER_POINT } from "@quario/layout";
 
-/**
- * Space around the sheet, in px. Read from here and nowhere else: the stage's
- * margin in the CSS below, the width `fit()` measures against, and the offset
- * `scale()` converts a scroll position through.
- */
-let GUTTER = 28;
-
-/** The gap between two pages, in px. */
-let GAP = 16;
+// `GUTTER` and `GAP` come from `@quario/landing`, which walks the reach over
+// them: the CSS below and the sheet's own arithmetic have to agree about where
+// a page sits, and two copies of that is a reach that paints the wrong pages.
 
 export let SURFACE = css`
 /* Where scrollbars take width, the gutter is held whether one is showing or
@@ -150,319 +145,24 @@ export let stage = () => {
   // inside the viewer. The `qv-*` names are documented as stable, so the
   // narrower one keeps its name.
   wrapper.className = "qv-stage";
-  let sheet = document.createElement("div");
-  sheet.className = "qv-sheet";
-  wrapper.append(sheet);
+  let sheetEl = document.createElement("div");
+  sheetEl.className = "qv-sheet";
+  wrapper.append(sheetEl);
   scroll.append(wrapper);
 
   /** 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]);
-
-  /**
-   * 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.
-   *
-   * @type {(canvas: HTMLElement, i: number, px?: number) => void}
-   */
-  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";
-  };
-
-  /**
-   * 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`.
-   *
-   * **The paint this answers with never rejects**, which is the whole of why
-   * `swap` does not either. A page that could not be drawn is not a render
-   * that failed: the report laid out and the list reached the sheet, so there
-   * is nothing for the error panel to say and nothing to report through the
-   * error event. Swallowed here, the one place a paint begins, so no caller
-   * has to remember to; one bad page then costs its own pixels rather than
-   * every page after it in the reach, which this loop awaits one at a time.
-   *
-   * See the header for how little can still reach it — the layout absorbs a
-   * bad image and refuses a bad face while measuring — and why it stays
-   * anyway. A paint that failed is forgotten so the next pass over the reach
-   * tries again, which is what makes a failure for a passing reason
-   * recoverable.
-   *
-   * @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);
-      },
-      () => {
-        backed.delete(canvas);
-      },
-    );
-    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;
-  };
-
-  // 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 a page that will not paint is blank whoever asked for
-   * it — `start` settles either way, so there is nothing here to catch.
-   */
-  let pending = false;
-  let follow = () => {
-    if (pending) return;
-    pending = true;
-    requestAnimationFrame(() => {
-      pending = false;
-      if (!list) return;
-      for (let i of keep()) void paintPage(i);
-    });
-  };
-  scroll.addEventListener("scroll", follow);
-
+  /** The paged sheet: the page canvases, their backing-store lifetime, the
+   * reach and its painting, in `@quario/landing`. It asks `ratio()` afresh,
+   * so the percentage this element applies is the scale it paints at — and
+   * the elements above stay this file's, because the CSS is the viewer's own
+   * public surface. */
+  let paged = sheet(scroll, sheetEl, ratio);
   return {
     element: scroll,
 
@@ -475,7 +175,7 @@ export let stage = () => {
     fit: () => {
       let usable = scroll.clientWidth - 2 * GUTTER;
       // The list's page width, or the geometry's before one arrives.
-      let width = (list ? list.width : fallback) * PX_PER_POINT;
+      let width = (paged.width() ?? fallback) * PX_PER_POINT;
       if (usable <= 0 || !width) return null;
       return (usable / width) * 100;
     },
@@ -498,7 +198,7 @@ export let stage = () => {
      * so a zoom step costs a handful of pages however long the report is.
      */
     scale: (percent) => {
-      let held = sheet.firstChild && {
+      let held = sheetEl.firstChild && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
         height: scroll.clientHeight,
@@ -506,13 +206,13 @@ export let stage = () => {
       };
       let ratioOf = percent / applied;
       applied = percent;
-      sizeAll();
+      paged.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();
+      void paged.repaint();
     },
 
     /**
@@ -542,20 +242,15 @@ export let stage = () => {
     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 && {
+      let held = sheetEl.firstChild && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
       };
-      list = next;
-      fonts = faces;
-      sheet.replaceChildren(
-        ...next.pages.map((/** @type {any} */ _, /** @type {number} */ i) => pageOf(i)),
-      );
+      await paged.swap(next, faces);
       if (held) {
         scroll.scrollTop = held.top;
         scroll.scrollLeft = held.left;
       }
-      await repaint();
     },
 
     /**
@@ -568,7 +263,7 @@ export let stage = () => {
       let observer = new ResizeObserver(() => {
         // A resize that changes the fit repaints through `changed()`; one
         // that does not still moved the viewport the reach is measured in.
-        follow();
+        paged.follow();
         changed();
       });
       observer.observe(scroll);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/viewer",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The embeddable report viewer shell for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -44,7 +44,8 @@
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/layout": "^0.3.0",
+    "@quario/landing": "^0.1.0",
+    "@quario/layout": "^0.4.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
@@ -53,18 +54,19 @@
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
     "exceljs": "^4.4.0",
-    "quario": "^0.6.0",
+    "quario": "^0.7.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.6.0"
+    "quario": "^0.7.0"
   },
   "size-limit": [
     {
       "path": "lib/index.js",
       "ignore": [
         "quario",
+        "@quario/landing",
         "@quario/layout",
         "lit",
         "@lit/task"