@quario/viewer 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-05
+
+### Changed
+
+- **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
+  repainted it afterwards: scrolling away and back left it as it was. A page
+  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
 
 ### Added

package/README.md

@@ -41,8 +41,11 @@ view.filename = "sales";
 ```
 
 with `<quario-viewer></quario-viewer>` in your markup, sized by your own CSS. The element is
-`display: block`. Importing `@quario/viewer` defines nothing: the main entry exports the
-`QuarioViewer` class and is side-effect-free, and `@quario/viewer/register` performs the one-line
+`display: block`, and its chrome is laid out to fit a width of **320px** — a phone-width embed is
+the narrowest the bar is designed for. Narrower than that and the export buttons push the zoom
+control off the left of the bar, quietly: the bar does not wrap or scroll. Importing
+`@quario/viewer` defines nothing: the main entry exports the `QuarioViewer` class and is
+side-effect-free, and `@quario/viewer/register` performs the one-line
 `customElements.define("quario-viewer", QuarioViewer)`. A host that wants its own tag imports the
 class and defines it itself. The repository ships this wiring as a runnable page at
 `example/viewer.js`.
@@ -84,16 +87,16 @@ out.
 ```js
 view.addEventListener("rendered", () => {});
 view.addEventListener("error", ({ detail: { error, kind } }) => {});
-await view.renderComplete; // true when the newest render reached the sheet
+await view.renderComplete; // true when the newest render landed on the sheet
 ```
 
-`rendered` fires each time a render reaches the sheet; `error` fires for every failure you should
+`rendered` fires each time a render lands on the sheet; `error` fires for every failure you should
 know about, with `detail.kind` naming which: `"mount-render"` until a render has ever landed,
 `"update-render"` after, `"export"` for a download that could not be produced. Both events are
 non-bubbling, like `<img>`'s. Listen on the element. (Because the event is named `error`, an
 inline `onerror` attribute on the element would fire too; `window.onerror` never sees it.)
 
-`renderComplete` awaits the newest render settling: `true` when it reached the sheet with the pages
+`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.
@@ -271,7 +274,7 @@ the export is, watermark and all.
 
 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
-dismissed by its own button, and is cleared by the next render that reaches the sheet. A successful
+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/button.js

@@ -18,6 +18,11 @@ export let BUTTON = css`
     border-radius: 5px;
     background: transparent;
     color: var(--_icon);
+    /* A form control does not inherit \`font\`, so the chrome's own 13px/1.4
+     system-ui stops at every button unless it is restated here. The shorthand
+     rather than \`font-family\` alone: the UA sets the shorthand, so restating
+     one longhand leaves size and line-height at the UA's. */
+    font: inherit;
     cursor: pointer;
   }
 
@@ -63,9 +68,11 @@ let fallback = (value, otherwise) => value ?? otherwise;
  * @param {{ title: string, label?: string, disabled?: boolean, name?: string,
  *   popover?: string, click?: () => void,
  *   content?: import('lit').TemplateResult }} control
- *   `label` is visible text for the controls that read as words; `content`
- *   is the icon template the zoom trigger and the export buttons pass
- *   instead. `name` marks an export button with the target it downloads, and
+ *   `content` is the icon a control draws and `label` the visible text it
+ *   reads as; an export button carries both, the zoom trigger and the panel's
+ *   dismiss the icon alone. Neither is ever the accessible name — `title` is,
+ *   which is why the icons are `aria-hidden`. `name` marks an export button
+ *   with the target it downloads, and
  *   `popover` names the menu this button opens — the platform then owns the
  *   opening and the invoker's own `aria-expanded`, which is why such a button
  *   needs no click of its own.
@@ -83,6 +90,6 @@ export let button = ({ title, label, disabled, name, popover, click, content })
     ?disabled=${disabled}
     @click=${click}
   >
-    ${fallback(label, content)}
+    ${content ?? nothing}${label ?? nothing}
   </button>
 `;

package/lib/check.js

@@ -94,8 +94,9 @@ export let name = (filename) => {
   return base;
 };
 
-/** @type {Record<string, string>} */
-let SCHEME = { light: "light", dark: "dark", auto: "light dark" };
+/** The schemes the property accepts. Two are their own CSS value; `auto` is
+ * the one that is not, so it is the only wording written here. */
+let SCHEMES = ["light", "dark", "auto"];
 
 /**
  * The used `color-scheme` from the `colorScheme` property. Light is the
@@ -108,6 +109,6 @@ let SCHEME = { light: "light", dark: "dark", auto: "light dark" };
  */
 export let scheme = (colorScheme) => {
   let pin = colorScheme ?? "light";
-  if (!Object.hasOwn(SCHEME, pin)) fail('colorScheme: expected "light", "dark", or "auto"');
-  return SCHEME[pin];
+  if (!SCHEMES.includes(pin)) fail('colorScheme: expected "light", "dark", or "auto"');
+  return pin === "auto" ? "light dark" : pin;
 };

package/lib/chrome.js

@@ -166,6 +166,25 @@ export let CHROME = css`
     display: flex;
     gap: 2px;
   }
+
+  /* An export button reads as a drawn download and the format in words, so it
+   takes the width its text needs rather than the icon-only box. */
+  .qv-exports .qv-button {
+    gap: 5px;
+    width: auto;
+    padding: 0 9px;
+  }
+
+  /* The base icon size, once per package rather than once per control: an
+   inline <svg> carrying a viewBox and no width falls back to 300x150, and
+   nothing in the chrome wants that. 18px is 0.75 of Lucide's 24 grid, which
+   puts its stroke 2 at 1.5px beside 13px text. The narrower selectors that
+   drop to 14px live with the controls they belong to — the menu's tick slot
+   in menu.js (ADR 0044). */
+  .qv-viewer svg {
+    width: 18px;
+    height: 18px;
+  }
 `;
 
 /**

package/lib/icons.js

@@ -0,0 +1,25 @@
+/**
+ * The icons @quario/viewer draws, vendored from Lucide: one export per icon,
+ * finished templates that carry no size. Chrome CSS decides that — 18px by
+ * 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:
+ * `npm run icons` rewrites it, and `npm run check` regenerates it into a
+ * temp directory and compares.
+ *
+ * Lucide is ISC licensed. Copyright (c) 2026 Lucide Icons and Contributors.
+ */
+import { html, svg } from "lit";
+
+/** Upstream's grid and stroke, written once. */
+/** @type {(paths: import('lit').SVGTemplateResult) => import('lit').TemplateResult} */
+let icon = (paths) =>
+  html`<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths}</svg>`;
+
+export let check = icon(svg`<path d="M20 6 9 17l-5-5"/>`);
+export let download = icon(
+  svg`<path d="M12 15V3"/><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="m7 10 5 5 5-5"/>`,
+);
+export let search = icon(svg`<path d="m21 21-4.34-4.34"/><circle cx="11" cy="11" r="8"/>`);
+export let x = icon(svg`<path d="M18 6 6 18"/><path d="m6 6 12 12"/>`);

package/lib/index.d.ts

@@ -31,8 +31,8 @@ export interface ViewerErrorDetail {
   /** The caught value, exactly as thrown. */
   error: unknown;
   /**
-   * Which failure occurred: `mount-render` until a render has ever reached
-   * the sheet, `update-render` after, `export` for a download that could not
+   * 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.
    */
   kind: ViewerErrorKind;
@@ -96,7 +96,7 @@ export class QuarioViewer extends LitElement {
    */
   colorScheme: "light" | "dark" | "auto" | undefined;
   /**
-   * The newest render settling: `true` when it reached the sheet with the
+   * 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
@@ -128,7 +128,7 @@ export class QuarioViewer extends LitElement {
 
 /** The element's events. Both are non-bubbling, like `<img>`'s. */
 export interface QuarioViewerEventMap {
-  /** A render reached the sheet — the mount and every update. */
+  /** A render landed on the sheet — the mount and every update. */
   rendered: CustomEvent<undefined>;
   /** A failure the host should know about; `detail.kind` says which. */
   error: CustomEvent<ViewerErrorDetail>;

package/lib/index.js

@@ -33,7 +33,7 @@ import { exports, 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";
-import { EXPORTS, download, exportGroup } from "./toolbar.js";
+import { EXPORTS, exportGroup, saveAs } from "./toolbar.js";
 import { wanted } from "./zoom.js";
 
 /** @type {(report: unknown, targets: unknown) => boolean} */
@@ -89,7 +89,7 @@ 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 reached the sheet — the mount/update boundary. */
+  /** 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;
@@ -135,7 +135,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 (this.#drop(signal)) return this.#abandon();
+      if (signal.aborted && !this.isConnected) return this.#abandon();
       return { list, fonts };
     },
     onComplete: (result) => {
@@ -145,7 +145,7 @@ export class QuarioViewer extends LitElement {
       this.#painting = this.#stage.swap(result.list, result.fonts).then(() => {
         this.#landed = true;
         this.#stale = false;
-        // A render that reached the sheet takes the panel down: the panel
+        // 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.
@@ -186,7 +186,7 @@ export class QuarioViewer extends LitElement {
   }
 
   /**
-   * The newest render settling: `true` when it reached the sheet, `false`
+   * 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.
@@ -238,7 +238,7 @@ export class QuarioViewer extends LitElement {
           })}
         </div>
         <div class="qv-body">
-          ${this.#panel()}
+          ${this.#failure && !this.#dismissed ? panel(this.#failure, () => this.#dismiss()) : ""}
           ${this.#stage.element}
         </div>
       </div>
@@ -259,7 +259,9 @@ export class QuarioViewer extends LitElement {
     super.connectedCallback();
     // A fitted sheet follows the host's box; the observer is released on
     // disconnect, so reconnection takes it again.
-    this.#watchStage();
+    this.#unwatch ??= this.#stage.watch(() => {
+      if (this.#mode === "fit" && this.#wanted() !== this.#stage.percent()) this.#apply();
+    });
     // Reconnect re-renders from the current properties — but only when the
     // sheet stopped matching them: a render was abandoned mid-flight, or a
     // property write landed while disconnected. The task's arguments did not
@@ -295,11 +297,6 @@ export class QuarioViewer extends LitElement {
     return true;
   }
 
-  /** @param {AbortSignal} signal */
-  #drop(signal) {
-    return signal.aborted && !this.isConnected;
-  }
-
   #abandon() {
     this.#stale = true;
     return null;
@@ -361,18 +358,6 @@ export class QuarioViewer extends LitElement {
     if (said(was) !== said(this.#invalid)) this.#epoch++;
   }
 
-  #panel() {
-    return this.#failure && !this.#dismissed ? panel(this.#failure, () => this.#dismiss()) : "";
-  }
-
-  #onResize() {
-    if (this.#mode === "fit" && this.#wanted() !== this.#stage.percent()) this.#apply();
-  }
-
-  #watchStage() {
-    this.#unwatch ??= this.#stage.watch(() => this.#onResize());
-  }
-
   #wake() {
     if (this.#stale || this.#task.status === TaskStatus.PENDING) {
       this.#epoch++;
@@ -442,12 +427,13 @@ export class QuarioViewer extends LitElement {
    * @param {any} target
    */
   async #export(target) {
-    let { type, label: format } = EXPORTS[target.name];
+    let type = EXPORTS[target.name];
+    let format = target.name.toUpperCase();
     this.#exporting.add(target.name);
     this.requestUpdate();
     try {
       let body = await /** @type {any} */ (this.report).render(target, this.data);
-      this.#ifConnected(() => download(body, this.#name + "." + target.name, type));
+      this.#ifConnected(() => saveAs(body, this.#name + "." + target.name, type));
     } catch (error) {
       this.#ifConnected(() => this.#announce(error, "export", format));
     } finally {

package/lib/menu.js

@@ -1,5 +1,5 @@
 /**
- * The zoom menu: the magnifier trigger in the bar and the popover it opens —
+ * The zoom menu: the search trigger in the bar and the popover it opens —
  * "Fit page" above a separator, then the percentages `zoom.js` offers. It is
  * the whole zoom control; the live percentage is never drawn, it is what the
  * trigger is named after ("Zoom, 62%"), so the bar carries one icon rather
@@ -29,6 +29,7 @@
  */
 import { css, html } from "lit";
 import { button } from "./button.js";
+import { check, search } from "./icons.js";
 import { STEPS } from "./zoom.js";
 
 /** The popover's id, scoped to the shadow root, so two viewers never collide. */
@@ -85,12 +86,22 @@ export let MENU = css`
   }
 
   /* The check's slot is held whether or not a check is in it, so the labels
-   line up down the menu. */
+   line up down the menu. 14px rather than 13: the small icon size serves this
+   slot and the editor's gutter alike, which is one size fewer than buying a
+   third for one glyph (ADR 0044). */
   .qv-tick {
     display: inline-flex;
     flex: none;
-    width: 13px;
-    height: 13px;
+    width: 14px;
+    height: 14px;
+  }
+
+  /* Narrower than the chrome's 18px base on specificity, not on where this
+   sheet sits in \`static styles\` — reordering that array must not silently
+   put the tick back to 18px. */
+  .qv-viewer .qv-tick svg {
+    width: 14px;
+    height: 14px;
   }
 
   .qv-separator {
@@ -100,30 +111,6 @@ export let MENU = css`
   }
 `;
 
-/** @type {import('lit').TemplateResult} */
-let magnifier = html`
-  <svg viewBox="0 0 20 20" width="19" height="19" aria-hidden="true">
-    <g fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round">
-      <circle cx="8.75" cy="8.75" r="5.25"></circle>
-      <path d="M12.6 12.6 16.4 16.4"></path>
-    </g>
-  </svg>
-`;
-
-/** @type {import('lit').TemplateResult} */
-let tick = html`
-  <svg viewBox="0 0 16 16" width="13" height="13" aria-hidden="true">
-    <path
-      d="M3.4 8.4 6.4 11.4 12.6 4.8"
-      fill="none"
-      stroke="currentColor"
-      stroke-width="1.9"
-      stroke-linecap="round"
-      stroke-linejoin="round"
-    ></path>
-  </svg>
-`;
-
 /**
  * The button that opens this menu, found by the invoker relationship itself
  * rather than by where it sits: a wrapper added for layout, or a second
@@ -276,7 +263,7 @@ let row = (label, value, checked, choose) => html`
     data-zoom=${String(value)}
     @click=${pick(value, choose)}
   >
-    <span class="qv-tick">${checked ? tick : ""}</span>
+    <span class="qv-tick">${checked ? check : ""}</span>
     ${label}
   </button>
 `;
@@ -298,7 +285,7 @@ export let zoomMenu = ({ mode, percent, choose }) => html`
     ${button({
       title: "Zoom, " + percent + "%",
       popover: ID,
-      content: magnifier,
+      content: search,
     })}
     <div
       id=${ID}

package/lib/panel.js

@@ -19,6 +19,7 @@
  */
 import { css, html } from "lit";
 import { button } from "./button.js";
+import { x } from "./icons.js";
 
 export let PANEL = css`
   /* Positioned rather than laid out, for the reason the progress strip is: a
@@ -121,6 +122,6 @@ export let panel = (failure, dismiss) => html`
       <p class="qv-error-label">${failure.label}</p>
       <p class="qv-error-message">${wording(failure.error)}</p>
     </div>
-    ${button({ title: "Dismiss", label: "×", click: dismiss })}
+    ${button({ title: "Dismiss", content: x, click: dismiss })}
   </div>
 `;

package/lib/stage.js

@@ -12,7 +12,7 @@
  * never reflows (zoom.js says why).
  *
  * Every page keeps its CSS size, but only the
- * [band](../../../CONTEXT.md#band) carries pixels — the pages on screen and
+ * [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
@@ -21,6 +21,28 @@
  * asked a thousand-page report for gigabytes of backing store, and past what
  * the browser would grant the pages simply came up blank.
  *
+ * **A canvas on the sheet is never re-pointed at a second paint.** `paint()`
+ * awaits before it draws, so a canvas whose paint is still in flight is
+ * *retired* rather than painted over or emptied: it comes off the sheet, its
+ * pixels go back, and a fresh one stands in its place, so the superseded
+ * paint draws into an element nobody is looking at. A canvas whose paint has
+ * settled has nothing that could land late and is re-sized or emptied in
+ * place as before. Without this a zoom landing mid-paint could leave a page
+ * carrying old-scale content on a new-scale canvas, with the memo below
+ * calling it painted so that nothing repainted it again (ADR 0046).
+ *
+ * Retirement is lazy, and only the paint is guarded. A scale change sizes
+ * every page's CSS box at once but retires a page only when the repaint loop
+ * reaches it, so a page further down the reach shows its old pixels stretched
+ * into the new box until its turn comes — the ordinary look of a zoom in
+ * progress, not the artefact above. The cost is that a retired page is a
+ * replaced `role="img"` node: assistive technology reading that page sees it
+ * swapped under them. Judged acceptable because retirement only happens while
+ * that very page is mid-repaint and about to change what it shows anyway, and
+ * because the alternative — a stable wrapper element per page to announce
+ * from — is a second element per page on a sheet ADR 0043 exists to keep
+ * cheap.
+ *
  * What the stage does not decide is which percentage to show: `fit()`
  * measures what would make one page span the width available, and `zoom.js`
  * owns the policy over that answer. What is on screen, though, is the
@@ -79,7 +101,7 @@ export let SURFACE = css`
 }
 
 /* One page. The painter fills it white; the background here is what a page
-   outside the band shows, and what one inside it shows between being sized
+   outside the reach shows, and what one inside it shows between being sized
    and being painted. */
 .qv-page {
   display: block;
@@ -131,7 +153,7 @@ export let stage = () => {
 
   /**
    * What each backed page is carrying: the scale it was painted at, so a page
-   * re-entering the band at that scale is not repainted and a scale change
+   * 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
@@ -143,84 +165,211 @@ export let stage = () => {
   let backed = new WeakMap();
 
   /**
-   * Give a page's pixels back. Sizing the canvas to 0 × 0 is the one idiom
-   * that frees the store synchronously in every engine the viewer runs in;
-   * the CSS size is untouched, so the page keeps its place in the extent and
-   * shows the sheet's white.
+   * 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 {(canvas: HTMLCanvasElement) => void}
+   * @type {(i: number) => HTMLCanvasElement}
    */
-  let release = (canvas) => {
+  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;
   };
 
-  /** The page width the fit measures against: the list's, or the geometry's
-   * before one arrives. */
-  let pageWidth = () => (list ? list.width : fallback);
-
-  /** CSS pixels per point at the applied percentage. */
-  let ratio = () => (PX_PER_POINT * applied) / 100;
+  /** 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);
 
   /**
-   * Paint one page and answer with that paint — or with the paint already
-   * under way at this scale, which is what makes scrolling back over ground
-   * already covered free. Answering with the paint rather than with a
-   * resolved promise is what lets two callers reach the same page and both
-   * settle behind its pixels. A paint that failed is forgotten, so the next
-   * pass over the band tries again instead of counting the page as painted.
+   * 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 {(canvas: HTMLCanvasElement, i: number) => Promise<void>}
+   * @type {(i: number) => Promise<void>}
    */
-  let paintPage = (canvas, i) => {
-    let scale = ratio() * (globalThis.devicePixelRatio || 1);
-    let carrying = backed.get(canvas);
-    if (carrying && carrying.scale === scale) return carrying.painted;
+  let 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 }).catch((failure) => {
-      backed.delete(canvas);
-      throw failure;
-    });
+    let painted = paint(ctx, each, { scale, fonts }).then(
+      () => {
+        settled.add(canvas);
+      },
+      (failure) => {
+        backed.delete(canvas);
+        throw failure;
+      },
+    );
     backed.set(canvas, { scale, painted });
     return painted;
   };
 
-  /** Bumped per repaint, so a repaint overtaken by the next stops painting. */
+  /**
+   * 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 band below is read from the offsets once they are in.
+   * and the reach below is read from the offsets once they are in.
    */
   let sizeAll = () => {
     if (!list) return;
     let px = ratio();
-    for (let [i, each] of list.pages.entries()) {
-      let canvas = /** @type {HTMLElement} */ (sheet.children[i]);
-      canvas.style.width = each.width * px + "px";
-      canvas.style.height = each.height * px + "px";
-    }
+    for (let i = 0; i < list.pages.length; i++) sizePage(pageAt(i), i, px);
   };
 
   /**
-   * The indices of the pages in the band — the ones the viewport shows, and
+   * 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 band ends. `clientHeight` is read afresh each time, so a
-   * pane that changed size changes the band with it.
+   * 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 inBand = () => {
+  let inReach = () => {
     let view = scroll.clientHeight;
     let top = scroll.scrollTop - view;
     let bottom = scroll.scrollTop + 2 * view;
@@ -236,73 +385,59 @@ export let stage = () => {
   };
 
   /**
-   * Release every page the band has left behind, and answer with the ones to
-   * keep, each with its index — in the order they are painted in. The single
+   * 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.
    *
-   * @type {() => [number, HTMLCanvasElement][]}
+   * 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(inBand());
+    let wanted = new Set(inReach());
     let kept = [];
-    for (let i = 0; i < sheet.children.length; i++) {
-      let canvas = /** @type {HTMLCanvasElement} */ (sheet.children[i]);
-      if (wanted.has(i)) kept.push(/** @type {[number, HTMLCanvasElement]} */ ([i, canvas]));
-      else release(canvas);
+    // `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 band in order, yielding between pages and giving way to any
+  // 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, canvas] of keep()) {
+    for (let i of keep()) {
       if (mine !== epoch) return;
-      await paintPage(canvas, i);
+      await paintPage(i);
     }
   };
 
   /**
-   * The band pass a scroll or a resize runs. It keeps no epoch of its own, so
-   * a swap painting behind it is never cut off part-painted, and a page it
-   * starts is one a swap reaching the same page waits behind rather than
-   * skips. Nothing awaits these paints here: a scroll is not a render and has
-   * no failure channel of its own, and a paint that failed is forgotten, so
-   * the next pass over the band reports it the way any other paint does.
+   * 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 sync = () => {
-    if (!list) return;
-    for (let [i, canvas] of keep()) paintPage(canvas, i).catch(() => {});
-  };
-
-  /** One band pass a frame, however many scrolls and resizes ask for one. */
   let pending = false;
   let follow = () => {
     if (pending) return;
     pending = true;
     requestAnimationFrame(() => {
       pending = false;
-      sync();
+      if (!list) return;
+      for (let i of keep()) paintPage(i).catch(() => {});
     });
   };
   scroll.addEventListener("scroll", follow);
 
-  /** @type {(i: number, total: number) => HTMLCanvasElement} */
-  let pageOf = (i, total) => {
-    let canvas = document.createElement("canvas");
-    canvas.className = "qv-page";
-    // A canvas is 300 x 150 until told otherwise, and that store counts. A
-    // page starts with none and takes one when the band reaches it.
-    canvas.width = 0;
-    canvas.height = 0;
-    canvas.setAttribute("role", "img");
-    canvas.setAttribute("aria-label", "Page " + (i + 1) + " of " + total);
-    return canvas;
-  };
-
   return {
     element: scroll,
 
@@ -314,7 +449,8 @@ export let stage = () => {
      */
     fit: () => {
       let usable = scroll.clientWidth - 2 * GUTTER;
-      let width = pageWidth() * PX_PER_POINT;
+      // The list's page width, or the geometry's before one arrives.
+      let width = (list ? list.width : fallback) * PX_PER_POINT;
       if (usable <= 0 || !width) return null;
       return (usable / width) * 100;
     },
@@ -333,7 +469,7 @@ export let stage = () => {
      * seen. The browser clamps whatever it cannot honour. An empty sheet has
      * no view to hold, which is what mounting at an authored zoom takes.
      *
-     * Only the band is repainted, and only where the scale actually changed,
+     * 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) => {
@@ -367,26 +503,27 @@ export let stage = () => {
 
     /**
      * Put a laid-out report on the sheet, keeping the reader where they
-     * were: one canvas per page, the band among them painted at the applied
-     * scale. The order is the point of the method: the pages take their size
-     * before the offsets go back, so the browser clamps them against the
-     * extent they will have rather than the one they had — and the band is
-     * read from those offsets, so it is chosen after they are in. What the
-     * returned promise settles behind is the band, which is what the caller's
+     * were: one canvas per page, the reach among them painted at the applied
+     * scale. The order is the point of the method: the pages come off
+     * `pageOf` already at their size, so the browser clamps the offsets going
+     * back against the extent the sheet will have rather than the one it had
+     * — and the reach is read from those offsets, so it is chosen after they
+     * are in. What the
+     * returned promise settles behind is the reach, which is what the caller's
      * `renderComplete` means by "the pages on screen are painted".
      */
     swap: async (next, faces) => {
       // Reading the offsets flushes layout, so only an actual reswap pays for
       // it: on an empty sheet there is nothing scrolled to preserve.
-      let held = sheet.firstChild && { top: scroll.scrollTop, left: scroll.scrollLeft };
+      let held = sheet.firstChild && {
+        top: scroll.scrollTop,
+        left: scroll.scrollLeft,
+      };
       list = next;
       fonts = faces;
       sheet.replaceChildren(
-        ...next.pages.map((/** @type {any} */ _, /** @type {number} */ i) =>
-          pageOf(i, next.pages.length),
-        ),
+        ...next.pages.map((/** @type {any} */ _, /** @type {number} */ i) => pageOf(i)),
       );
-      sizeAll();
       if (held) {
         scroll.scrollTop = held.top;
         scroll.scrollLeft = held.left;
@@ -403,7 +540,7 @@ export let stage = () => {
     watch: (changed) => {
       let observer = new ResizeObserver(() => {
         // A resize that changes the fit repaints through `changed()`; one
-        // that does not still moved the viewport the band is measured in.
+        // that does not still moved the viewport the reach is measured in.
         follow();
         changed();
       });

package/lib/toolbar.js

@@ -3,54 +3,32 @@
  * host passed, in the order they were given. It sits at the right of the
  * viewer's bar, beside the zoom menu; no exportable target, no group.
  * The element owns the click — rendering with its current data and
- * auto-downloading through `download` below — because only it knows
+ * auto-downloading through `saveAs` below — because only it knows
  * whether it is still connected when the file arrives.
  *
- * The icon's label goes in as a template value, never as a string spliced
+ * The format's name goes in as a template value, never as a string spliced
  * into a document, so this module has no markup edge to escape at and never
  * grows one (hard constraint 4).
  */
 import { html, nothing } from "lit";
 import { button } from "./button.js";
+import { download } from "./icons.js";
 
-/** The exportable targets: content type and button wording. */
-/** @type {Record<string, { type: string, label: string }>} */
+/** The exportable targets, filed under the extension each downloads as: the
+ * content type its blob carries. The wording on the button and in a failure
+ * is that same name upper-cased, never a second spelling of it. */
+/** @type {Record<string, string>} */
 export let EXPORTS = {
-  pdf: { type: "application/pdf", label: "PDF" },
-  xlsx: {
-    type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-    label: "XLSX",
-  },
-  csv: { type: "text/csv", label: "CSV" },
+  pdf: "application/pdf",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  csv: "text/csv",
 };
 
-// Sheet outline with a folded corner, over the format's name.
-/** @type {(label: string) => import('lit').TemplateResult} */
-let icon = (label) => html`
-  <svg viewBox="0 0 20 20" width="19" height="19" aria-hidden="true">
-    <g fill="none" stroke="currentColor" stroke-width="1.2" stroke-linejoin="round">
-      <path d="M4.5 2.5h7l4 4v11h-11z"></path>
-      <path d="M11.5 2.5v4h4"></path>
-    </g>
-    <text
-      x="10"
-      y="14.5"
-      text-anchor="middle"
-      font-size="5"
-      font-weight="700"
-      letter-spacing="0.2"
-      fill="currentColor"
-    >
-      ${label}
-    </text>
-  </svg>
-`;
-
 // The anchor joins the document for the click — detached-anchor downloads
 // are unreliable outside Chromium — and the URL is revoked well after the
 // browser has had time to start reading the blob.
 /** @type {(body: string | Uint8Array<ArrayBuffer>, name: string, type: string) => void} */
-export let download = (body, name, type) => {
+export let saveAs = (body, name, type) => {
   let url = URL.createObjectURL(new Blob([body], { type }));
   let anchor = document.createElement("a");
   anchor.href = url;
@@ -80,14 +58,17 @@ export let exportGroup = (targets, context) => {
   return html`
     <div class="qv-exports">
       ${exportable.map((target) => {
-        let { label } = EXPORTS[target.name];
+        let label = target.name.toUpperCase();
         return button({
-          // The icon carries the format, so the button takes no text of its own.
+          // One drawn verb and the format in words beside it: the download
+          // icon says what the click does, and the format is information the
+          // reader needs rather than a glyph to decode (ADR 0044).
           title: "Download " + label,
+          label,
           name: target.name,
           disabled: context.busy.has(target.name),
           click: () => context.click(target),
-          content: icon(label),
+          content: download,
         });
       })}
     </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/viewer",
-  "version": "0.4.0",
+  "version": "0.5.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,21 +44,21 @@
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/layout": "^0.1.0",
+    "@quario/layout": "^0.2.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
+    "@cantoo/pdf-lib": "^2.9.1",
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
     "exceljs": "^4.4.0",
-    "pdf-lib": "^1.17.1",
-    "quario": "^0.4.0",
+    "quario": "^0.5.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.4.0"
+    "quario": "^0.5.0"
   },
   "size-limit": [
     {