@quario/viewer 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ 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
+
+- **Numbers presented through `format` now show a fixed two fraction digits**,
+  the same as every other target: `1,000.00` where the preview showed `1,000`,
+  `21.00%` where it showed `21%`, and a currency's own minor units in place of
+  a universal two. The digits come from the engine, so a page on screen and
+  the PDF of it agree. A formatted cell is also up to three characters wider,
+  so a line that just fitted can wrap and move a page break.
+
+### Fixed
+
+- **A page the browser cannot fully paint no longer fails the render.** An
+  image whose pixel data is corrupt past the size in its header left that page
+  blank _and_ rejected `renderComplete`, so a host awaiting it saw an unhandled
+  rejection instead of an answer, and every page after it on screen went
+  unpainted too. Such an image is now drawn as nothing and the page is drawn
+  around it, marking and all; `renderComplete` resolves `true`, `rendered`
+  fires, and no `error` event is raised. It never rejects for this reason
+  again: a page that cannot be drawn is blank, not a failed render.
+
 ## [0.5.0] - 2026-09-05
 
 ### Changed

package/README.md

@@ -97,13 +97,20 @@ non-bubbling, like `<img>`'s. Listen on the element. (Because the event is named
 inline `onerror` attribute on the element would fire too; `window.onerror` never sees it.)
 
 `renderComplete` awaits the newest render settling: `true` when it landed on the sheet with the pages
-on screen painted, `false` when it failed or there was nothing to render. It never rejects; failures
-arrive on the `error` event. `rendered` fires at that same moment. Like every outcome here, it
-answers for the newest render only. A superseded render's failure is reported to no one.
+on screen finished trying to paint, `false` when it failed or there was nothing to render. It never
+rejects; failures arrive on the `error` event. `rendered` fires at that same moment. Like every
+outcome here, it answers for the newest render only. A superseded render's failure is reported to no
+one.
 
-Your own mistakes surface on the same channel: a report that is not compiled, a missing
-`"html"` target, or a malformed option property becomes a `TypeError` naming the property, on
-the `error` event and the [error panel](#errors).
+An image the browser cannot decode — pixel data corrupt past the size in its header, which is all
+the engine reads — is drawn as nothing, and the page is drawn around it. That is not a render
+failure: `renderComplete` answers `true`, `rendered` fires, and no `error` event is raised. A face in
+`fonts` is a different story: it is parsed while the report is measured, so bytes that will not parse
+are a render error with a panel.
+
+Your own mistakes surface on the same channel: a report that is not compiled, or a malformed
+option property, becomes a `TypeError` naming the property, on the `error` event and the
+[error panel](#errors). No particular target is required — the sheet is the layout's own.
 
 ## Lifecycle
 
@@ -250,7 +257,8 @@ export marks every page: it rides on the layout, so what you see is what the doc
 licensed render carries none.
 
 While a render is in flight a thin indeterminate bar sits on the toolbar's bottom edge, and the
-viewer reads `aria-busy="true"`. It reports that the viewer is working, not how far along. The
+viewer's inner container — the `.qv-viewer` div in its shadow root, not the element itself —
+reads `aria-busy="true"`. It reports that the viewer is working, not how far along. The
 engine streams events and cannot know how many are still coming.
 
 There is no Print button, because the sheet is the wrong thing to print. Your page's stylesheets do
@@ -261,9 +269,9 @@ document, the same bytes the PDF export hands over. A host that wants its own Pr
 two lines:
 
 ```js
-// `pdfTarget` is the pdf() from the quick start above, and `data` whatever you
-// last rendered — so what prints is exactly what the PDF export would produce.
-const bytes = await rpt.render(pdfTarget, data);
+// The same compiled report and data the element holds, through the pdf()
+// target from the quick start — so what prints is exactly the PDF export.
+const bytes = await view.report.render(pdf(), view.data);
 window.open(URL.createObjectURL(new Blob([bytes], { type: "application/pdf" })));
 ```
 
@@ -273,7 +281,7 @@ the export is, watermark and all.
 ## Errors
 
 When a render or an export fails, the viewer says so on the **error panel**, a strip across the top
-of the sheet carrying a short label and the error's own message. It replaces rather than stacks, is
+of the sheet carrying a short label — "Could not render the report", "Could not update the report — showing the previous version", or "Could not export PDF" — and the error's own message. It replaces rather than stacks, is
 dismissed by its own button, and is cleared by the next render that lands on the sheet. A successful
 export leaves it up, because the panel describes what you are looking at and a download says
 nothing about that.

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;
 }
@@ -97,10 +98,11 @@ export class QuarioViewer extends LitElement {
   colorScheme: "light" | "dark" | "auto" | undefined;
   /**
    * The newest render settling: `true` when it landed on the sheet with the
-   * pages on screen painted, `false` when it failed or there was nothing to
-   * render. Never rejects — failures are the `error` event's — and like every
-   * outcome here it answers for the newest render only. `rendered` fires at
-   * that same moment.
+   * pages on screen finished trying to paint, `false` when it failed or there
+   * was nothing to render. A page the browser could not draw is blank and the
+   * render still landed. Never rejects — failures are the
+   * `error` event's — and like every outcome here it answers for the newest
+   * render only. `rendered` fires at that same moment.
    */
   get renderComplete(): Promise<boolean>;
 

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,30 +84,36 @@ 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. */
   #exporting = new Set();
   /** @type {(() => void) | undefined} */
   #unwatch;
-  /** @type {Promise<void>} The newest swap's paint, which `renderComplete` waits behind. */
+  /**
+   * The newest swap's paint, which `renderComplete` waits behind. Bare, with
+   * no catch of its own: the stage settles a page it cannot draw rather than
+   * rejecting, so the chain below is reached whatever the pixels did.
+   *
+   * @type {Promise<void>}
+   */
   #painting = Promise.resolve();
 
   // The whole async pipeline: keyed on the render properties, re-run when one
@@ -124,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
@@ -135,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) => {
@@ -143,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"));
@@ -158,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));
     },
   });
 
@@ -186,19 +185,22 @@ export class QuarioViewer extends LitElement {
   }
 
   /**
-   * The newest render settling: `true` when it landed on the sheet, `false`
-   * when it failed or there was nothing to render. It never rejects — a
-   * failed render is handled, on the panel and through the error event — and
-   * like every outcome here it answers for the newest render only.
+   * The newest render settling: `true` when it landed on the sheet — after
+   * its pages have finished trying to paint — `false` when it failed or there
+   * was nothing to render. A page the browser could not draw is blank and the
+   * render still landed, so `true` promises the sheet is done changing, not
+   * that every page carries pixels. It never rejects — a failed
+   * render is handled, on the panel and through the error event — and like
+   * every outcome here it answers for the newest render only.
    *
    * @returns {Promise<boolean>}
    */
   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,
           ),
     );
@@ -218,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() {
@@ -238,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>
@@ -267,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;
   }
@@ -290,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
@@ -327,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 */
@@ -399,7 +402,7 @@ export class QuarioViewer extends LitElement {
   }
 
   #dismiss() {
-    this.#dismissed = true;
+    this.#failures.dismiss();
     this.requestUpdate();
   }
 
@@ -409,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

@@ -21,6 +21,19 @@
  * asked a thousand-page report for gigabytes of backing store, and past what
  * the browser would grant the pages simply came up blank.
  *
+ * **A page the browser will not paint is blank, not a failure.** `start`
+ * swallows and nothing here rejects: the report laid out and the list reached
+ * the sheet, which is all a render promised, so the surfaces have no channel
+ * for it and deliberately grow none.
+ *
+ * Little reaches it. An image that will not decode is the layout's own to
+ * absorb — `paint` draws it as nothing and draws the page around it — and a
+ * face is parsed with fontkit while the report is measured, so bytes that will
+ * not parse are a render error long before the sheet. What is left is the face
+ * fontkit accepted and the browser refuses, which the browser suite drives by
+ * making `FontFace.prototype.load` reject under a record handed straight to
+ * `swap`.
+ *
  * **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
@@ -57,17 +70,12 @@
  */
 
 import { css } from "lit";
-import { PX_PER_POINT, paint } 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;
+import { GAP, GUTTER, sheet } from "@quario/landing";
+import { PX_PER_POINT } from "@quario/layout";
 
-/** 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
@@ -137,307 +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`.
-   *
-   * @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;
-  };
-
-  // 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);
-
+  /** 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,
 
@@ -450,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;
     },
@@ -473,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,
@@ -481,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();
     },
 
     /**
@@ -510,25 +235,22 @@ export let stage = () => {
      * — 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".
+     * `renderComplete` means by "the pages on screen have finished trying to
+     * paint" — and **it never rejects**, because `start` swallows a page the
+     * browser will not draw and the reach walks on past it.
      */
     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();
     },
 
     /**
@@ -541,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.5.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.2.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.5.0",
+    "quario": "^0.7.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.5.0"
+    "quario": "^0.7.0"
   },
   "size-limit": [
     {
       "path": "lib/index.js",
       "ignore": [
         "quario",
+        "@quario/landing",
         "@quario/layout",
         "lit",
         "@lit/task"