@quario/viewer 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,15 +1,75 @@
-# Changelog
-
-All notable changes to @quario/viewer are documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.6.0] - 2026-09-07
-
-### Changed
+# @quario/viewer
+
+## 0.8.0
+
+### Minor Changes
+
+- **An image's box is now as wide as the container it sits in.** A
+  `background` or `border*` on an image item hugged the picture and now spans
+  the content width, or the slot's share inside a split; the picture itself
+  does not move. See the `@quario/layout` changelog for the rule and for what
+  it costs a report that relied on a border hugging a logo.
+- **Only the pages you can see are on the sheet.** A page outside the reach
+  used to be an empty canvas holding its place; now it has no element at all,
+  and the sheet carries the document's extent itself — its height and width are
+  written from the layout, and it paints the page silhouettes. The stretch a
+  reader scrolls through is exactly what it was, and a scale change no longer
+  costs the browser a relayout of every page: that was around 10 microseconds a
+  page, so a five-thousand-page report paid roughly 50 ms of it each time.
+
+  This changes the sheet's markup, which matters if you style it. `.qv-page` is
+  now absolutely positioned inside `.qv-sheet`, and is present only for the pages
+  on screen and one viewport height either side. A rule that gave a page a
+  margin, or that relied on the pages being a flow of siblings, no longer
+  applies — the sheet places its own pages, and does it with inline styles a
+  stylesheet rule cannot override. `--qv-sheet-shadow` is unchanged.
+
+  One cost, stated: a page outside the reach has no `role="img"` node, so
+  assistive technology sees the few images of the reach renumbering as the
+  reader scrolls rather than a document of named pages.
+
+### Patch Changes
+
+- **Every published README says where the documentation is.** Each package now
+  carries a Documentation section pointing at the reference, at the report schema
+  that normatively specifies what a report may declare, and at the package's own
+  API. The paragraphs that used to end on an unstated contract — the event
+  stream's field semantics, the style vocabulary, page columns, the Content
+  Security Policy a fragment with images needs, the formula mangling, and each
+  target's own contract — link the page that states it. Every link is an absolute
+  URL, so it resolves from the npm package page as readily as from an installed
+  copy.
+- Updated dependencies
+  - @quario/layout@0.5.0
+  - @quario/landing@0.2.0
+  - quario@0.8.0
+
+## 0.7.0
+
+### Minor Changes
+
+- **`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.
+- **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
+
+### Minor Changes
 
 - **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`,
@@ -17,9 +77,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
@@ -29,29 +86,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+## 0.5.0
 
-### Changed
+### Minor Changes
 
 - **Previewing with `fonts` now needs `fontkit`, not `@pdf-lib/fontkit`.**
   Install `fontkit` instead. The viewer measures host TrueType faces through
   `@quario/layout`, whose optional parser this is; the old package crashed on
   any OpenType face needing a shaping state machine, so those faces now
   preview where they used to throw.
-
 - **The bar's controls are drawn icons.** The zoom trigger, the menu's check
   and the error panel's dismiss are drawn from Lucide's set rather than by
   hand, at one weight and one grid, and the dismiss no longer relies on the
   host's font to draw a multiplication sign. They paint in `currentColor`, so
   `--qv-icon` and `--qv-icon-active` still recolour them.
-
 - **An export button names its format in words.** Each one is a download icon
   with `PDF`, `XLSX` or `CSV` beside it, in place of the sheet drawing that
   lettered the format inside itself. The buttons are wider; the accessible
   name is unchanged.
-
-### Fixed
-
 - **A zoom no longer leaves a page part-drawn.** Changing the zoom while a
   page was still painting could leave that page carrying content at the old
   scale on a canvas sized for the new one — the rest of it blank — and nothing
@@ -59,27 +111,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   whose paint is still in flight is now replaced rather than reused, so the
   superseded paint has nowhere to land.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Added
+### Minor Changes
 
 - **`fonts`.** The font mapping a host passes to `pdf({ fonts })`, so the
   preview measures and draws in the same TrueType faces the document embeds.
-
-### Changed
-
 - **`renderComplete` and `rendered` settle once the pages on screen are
   painted.** Both already answered for the newest render reaching the sheet;
   what that means is now stated: the pages the reader can see carry their
   pixels, and the pages further down the report do not hold the promise up.
   A screenshot or a pixel-reading test taken at that moment sees what the
   reader sees.
-
 - **A split slot's box now fills the split's height.** A slot's background and
   border stopped at that slot's own content and now take the split's height,
   the way a table cell's take their row's. See the `@quario/layout` changelog
   for the rule and for what it costs a report that relied on the short box.
-
 - **The sheet has pages, and they break where the PDF's do.** The viewer
   depends on `@quario/layout` and paints the same display list the pdf target
   writes, one canvas per page, in the faces the document itself uses.
@@ -89,9 +136,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `page` change re-lays the report out rather than resizing a sheet. The
   unlicensed marking is painted per page from the list; the `--qv-mark`
   token is gone with the DOM stamps.
-
-### Fixed
-
 - **A long report no longer asks for a backing store per page.** The viewer
   paints the pages near the viewport — the ones on screen and one screenful
   either side — and keeps every other page sized but blank. A report of a
@@ -102,23 +146,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the first frame, and a zoom step now repaints a handful of pages instead of
   walking the document.
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Changed
+### Minor Changes
 
 - **Report and group containers are flex columns.** Adjacent authored
   `spaceBefore` / `spaceAfter` margins add rather than collapse, matching
   the html reference stylesheet.
-
-### Fixed
-
 - **The adopted sheet occupies a line and preserves authored newlines.**
   Same `min-height: 1lh` and `white-space: pre-line` the html reference
   stylesheet now carries on `.q-item`, and `pre-line` on table cells.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Changed
+### Minor Changes
 
 - **The sheet is now page-shaped, so short reports reserve a full page.**
   `page` sized the sheet's width and padding and ignored its height, so a
@@ -137,9 +178,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **The adopted sheet's baseline face moved onto `.q-report`.** It was on
   `.q-item` and `.q-table`, where a direct rule would have beaten a report's
   own declared family. Same look; the fragment's new root is what carries it.
-
-### Fixed
-
 - **The sheet no longer draws report text in the platform's own face.** It
   hard-coded `system-ui`, which is SF Pro on macOS, Segoe UI on Windows and
   Roboto on Android — so the same report showed a different typeface to every
@@ -148,9 +186,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   resolves to Helvetica. The viewer's own chrome keeps `system-ui`, which is
   what a toolbar should do.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **An embeddable `<quario-viewer>`.** Assign a compiled report, the targets
   to render with, and data; it shows the HTML report on a continuous sheet,

package/README.md

@@ -314,6 +314,13 @@ reference seam, not a frozen vocabulary: backdrop and bar (`--qv-backdrop`, `--q
 The report itself is paint, not markup: there is no report stylesheet to restyle, because what
 you see is the layout the PDF target writes.
 
+## Documentation
+
+[The quario documentation](https://getquario.com/docs/) is the reference.
+The [report schema](https://getquario.com/docs/reference/report-schema/) is the normative
+specification of what a report may declare, and
+[`@quario/viewer`](https://getquario.com/docs/reference/viewer/) is this element's own API.
+
 ## License
 
 Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer

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/icons.js

@@ -4,7 +4,7 @@
  * default, 14px in the gutter and the menu's tick slot — because `x` appears
  * in two contexts at once (ADR 0044).
  *
- * Generated by `scripts/icons.mjs` from lucide 1.40.0. Do not edit:
+ * Generated by `scripts/icons.mjs` from lucide 1.42.0. Do not edit:
  * `npm run icons` rewrites it, and `npm run check` regenerates it into a
  * temp directory and compares.
  *

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * and the sheet — the layout list's whole extent, with a canvas for each page
+ * of the reach painted by `@quario/layout`'s `paint` — their elements, their
+ * CSS, and every number relating them.
  *
  * 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
@@ -11,15 +11,17 @@
  * reader saw. The list never changes under a zoom — the preview scales and
  * never reflows (zoom.js says why).
  *
- * Every page keeps its CSS size, but only the
- * [reach](../../../CONTEXT.md#reach) carries pixels — the pages on screen and
- * one viewport height either side. The extent the reader scrolls through is
- * whole and synchronous whatever is painted; what comes and goes is the
- * backing store, released by sizing a canvas to 0 × 0. A scroll or a resize
- * runs the same arithmetic over the list's own geometry, coalesced to one
- * pass a frame. ADR 0043 says what that is worth: painting the whole sheet
- * asked a thousand-page report for gigabytes of backing store, and past what
- * the browser would grant the pages simply came up blank.
+ * The sheet carries the whole list's extent, but only the
+ * [reach](../../../CONTEXT.md#reach) carries elements and pixels — the pages
+ * on screen and one viewport height either side. The extent the reader scrolls
+ * through is whole and synchronous whatever is standing, because the sheet is
+ * given its height and width inline and paints the page silhouettes itself; a
+ * page leaving the reach is removed, which takes its backing store with it
+ * (ADR 0065). 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 the reach is
+ * worth: painting the whole sheet asked a thousand-page report for gigabytes of
+ * backing store, and past what the browser would grant the pages simply came up
+ * blank.
  *
  * **A 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
@@ -39,13 +41,14 @@
  * *retired* rather than painted over or emptied: it comes off the sheet, its
  * pixels go back, and a fresh one stands in its place, so the superseded
  * paint draws into an element nobody is looking at. A canvas whose paint has
- * settled has nothing that could land late and is re-sized or emptied in
- * place as before. Without this a zoom landing mid-paint could leave a page
+ * settled has nothing that could land late and is re-sized in place as before;
+ * a page leaving the reach is removed either way, which takes its pixels with
+ * it whether that paint has landed or not. Without this a zoom landing mid-paint could leave a page
  * carrying old-scale content on a new-scale canvas, with the memo below
  * calling it painted so that nothing repainted it again (ADR 0046).
  *
- * Retirement is lazy, and only the paint is guarded. A scale change sizes
- * every page's CSS box at once but retires a page only when the repaint loop
+ * Retirement is lazy, and only the paint is guarded. A scale change sizes the
+ * reach's CSS boxes at once but retires a page only when the repaint loop
  * reaches it, so a page further down the reach shows its old pixels stretched
  * into the new box until its turn comes — the ordinary look of a zoom in
  * progress, not the artefact above. The cost is that a retired page is a
@@ -70,17 +73,14 @@
  */
 
 import { css } from "lit";
-import { PX_PER_POINT, paint } from "@quario/layout";
+import { 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` comes from `@quario/landing`, which walks the reach over it: 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. The gap
+// between pages is that package's too, and is not named here at all — the sheet
+// positions its own pages now, so this file has nothing to space.
 
 export let SURFACE = css`
 /* Where scrollbars take width, the gutter is held whether one is showing or
@@ -106,16 +106,17 @@ export let SURFACE = css`
   margin: ${GUTTER}px auto;
 }
 
-/* The sheet is the stack of pages. */
-.qv-sheet {
-  display: flex;
-  flex-direction: column;
-  gap: ${GAP}px;
-}
-
-/* One page. The painter fills it white; the background here is what a page
-   outside the reach shows, and what one inside it shows between being sized
-   and being painted. */
+/* The sheet is the whole document's extent, and the pages of the reach are
+   positioned inside it. It has no rule here because it has no look: its
+   position, its height, its width and its page silhouettes are all written
+   inline by \`@quario/landing\` from the list's own geometry, which is the one
+   place any of them is decided (ADR 0065). A page outside the reach has no
+   element, so what shows there is the sheet's own paint.
+
+   One page of the reach, at the size and offset the sheet gives it. The
+   painter fills it white; the background here is what it shows between being
+   placed and being painted, and the shadow is what lifts it off the sheet —
+   the two this file does decide. */
 .qv-page {
   display: block;
   background: #fff;
@@ -150,319 +151,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 +181,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;
     },
@@ -491,14 +197,17 @@ export let stage = () => {
      * offset; horizontally the wrapper is centred by auto margins while it
      * fits — which is exactly when `scrollLeft` is 0 anyway — and its margins
      * 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.
+     * seen. The browser clamps whatever it cannot honour. A sheet with no list
+     * on it has no view to hold, which is what mounting at an authored zoom
+     * takes. Asked of the list rather than of the sheet's children, which
+     * since ADR 0065 are the reach's and can be none of them while a list is
+     * standing — and it saves a DOM read besides.
      *
      * Only the reach is repainted, and only where the scale actually changed,
      * so a zoom step costs a handful of pages however long the report is.
      */
     scale: (percent) => {
-      let held = sheet.firstChild && {
+      let held = paged.count() > 0 && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
         height: scroll.clientHeight,
@@ -506,13 +215,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();
     },
 
     /**
@@ -528,12 +237,12 @@ export let stage = () => {
 
     /**
      * Put a laid-out report on the sheet, keeping the reader where they
-     * were: one canvas per page, the reach among them painted at the applied
-     * scale. The order is the point of the method: the pages come off
-     * `pageOf` already at their size, so the browser clamps the offsets going
-     * back against the extent the sheet will have rather than the one it had
-     * — and the reach is read from those offsets, so it is chosen after they
-     * are in. What the
+     * were: the extent whole at once, with the reach's pages painted at the
+     * applied scale. The order is the point of the method: the sheet takes its
+     * height from the list before anything else, so the browser clamps the
+     * offsets going back against the extent the sheet will have rather than
+     * the one it had — and the reach is read from those offsets, so it is
+     * chosen after they are in. What the
      * returned promise settles behind is the reach, which is what the caller's
      * `renderComplete` means by "the pages on screen have finished trying to
      * paint" — and **it never rejects**, because `start` swallows a page the
@@ -541,21 +250,16 @@ 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 && {
+      // it: with no list standing there is nothing scrolled to preserve.
+      let held = paged.count() > 0 && {
         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 +272,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.8.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.2.0",
+    "@quario/layout": "^0.5.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.8.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.6.0"
+    "quario": "^0.8.0"
   },
   "size-limit": [
     {
       "path": "lib/index.js",
       "ignore": [
         "quario",
+        "@quario/landing",
         "@quario/layout",
         "lit",
         "@lit/task"