@quario/viewer 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @quario/viewer
 
+## 0.10.0
+
+### Minor Changes
+
+- **A viewer you insert again renders once more, unless its last render landed on the sheet.** It used to do that only for a render that stopped mid-flight, which left three ways for the newest render to go missing with nothing owed.
+
+  A render that failed while the element was out of the document is one of them. The error panel reaches nobody there, so the verdict reached nobody, and the element came back showing the previous pages with no panel and no re-render owed. A property the host rejected while the element was out of the document behaved the same way. So did a property written while it was out of the document.
+
+  All three now leave the render owed, and inserting the element collects it. What you see on reconnect is the panel the failure earns, or the pages the newest properties produce.
+
+  A failure the panel already showed is owed again too. Removing and inserting such an element re-runs the render and reports the same failure once. It is not announced twice.
+
+### Patch Changes
+
+- Updated dependencies
+  - @quario/layout@0.7.0
+  - quario@0.10.0
+  - @quario/landing@0.3.0
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -10,6 +10,21 @@ list, painted page by page. You pass the export targets you want, and the viewer
 to each (`"pdf"`, `"xlsx"`, `"csv"`, `"docx"`). The bar always carries the zoom control. With no
 exportable target it carries nothing else.
 
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Properties](#properties)
+- [Events and `renderComplete`](#events-and-rendercomplete)
+- [Lifecycle](#lifecycle)
+- [Using with React, Vue and Svelte](#using-with-react-vue-and-svelte)
+- [Zoom](#zoom)
+- [What the preview is](#what-the-preview-is)
+- [Errors](#errors)
+- [Color scheme](#color-scheme)
+- [Documentation](#documentation)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -115,11 +130,12 @@ option property, becomes a `TypeError` naming the property, on the `error` event
 
 ## Lifecycle
 
-There is no `destroy()`. Removing the element from the DOM abandons in-flight work and releases
-its observers. An export that settles after removal downloads nothing. The properties persist, and
-re-inserting the element re-renders from them, so reparenting is safe, and discarding a viewer is
-just discarding the element. Two viewers, or a viewer beside your own components, coexist: each
-element owns its own shadow root.
+There is no `destroy()`. Removal from the DOM stops the work in flight and releases the
+observers. An export that settles after removal downloads nothing. The properties and the pages
+persist. The element still owes a render that did not land on the sheet. It therefore renders
+once more when you insert it, unless its last render landed. Reparenting is safe, and you
+discard a viewer by discarding the element. Two viewers, or a viewer beside your own components,
+coexist: each element owns its own shadow root.
 
 ## Using with React, Vue and Svelte
 

package/lib/button.js

@@ -1,8 +1,6 @@
 /**
  * The shared `qv-button` template. Every control the viewer renders comes
- * from here — the zoom menu's trigger, the export downloads, the error
- * panel's dismiss — so they agree on the class, the `type` and how they are
- * named.
+ * from here, so they agree on the class, the `type` and how they are named.
  */
 import { css, html, nothing } from "lit";
 
@@ -69,13 +67,10 @@ let fallback = (value, otherwise) => value ?? otherwise;
  *   popover?: string, click?: () => void,
  *   content?: import('lit').TemplateResult }} control
  *   `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.
+ *   reads as. 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. `popover` names the menu this button opens, and the platform
+ *   then owns the opening and the invoker's `aria-expanded`.
  * @returns {import('lit').TemplateResult}
  */
 export let button = ({ title, label, disabled, name, popover, click, content }) => html`

package/lib/check.js

@@ -1,10 +1,7 @@
 /**
- * What the host got wrong, named. The element's own mistakes — a report that
- * is not compiled, a malformed option property — are definition-shaped: they
- * describe the embedding, not the report, so each check here throws a
- * `TypeError` naming the property and the expectation. The element rethrows
- * them from its render task, which is how one channel (the error event and
- * the panel) carries every failure a host can cause.
+ * What the host got wrong, named. Each check throws a `TypeError` naming the
+ * property and the expectation; the element rethrows them from its render
+ * task, so one channel carries every failure a host can cause.
  *
  * Pure policy, no DOM: this module is what the Node suite pins.
  */
@@ -57,9 +54,8 @@ 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.
+ * face that will not parse is found while the report is measured and is a
+ * render failure there.
  *
  * @param {any} fonts
  */
@@ -76,12 +72,10 @@ let inRange = (mode, floor, ceiling) =>
   [Number.isFinite(mode), mode >= floor, mode <= ceiling].every(Boolean);
 
 /**
- * The zoom mode from the `zoom` property. Fit is the default: the host owns
- * the box, and a report nobody can read until they touch a control is not
- * much of a preview. A host may author any percentage from 25 to 200 —
- * continuous, not one of the menu's own stops; fit itself computes anything
- * at or below 100, so this deliberately validates less than the element can
- * display.
+ * The zoom mode from the `zoom` property, fit by default. A host may author
+ * any percentage from 25 to 200 — continuous, not one of the menu's stops.
+ * Fit itself computes anything at or below 100, so this deliberately
+ * validates less than the element can display.
  *
  * @param {any} zoom
  * @returns {"fit" | number}
@@ -115,10 +109,9 @@ export let name = (filename) => {
 let SCHEMES = ["light", "dark", "auto"];
 
 /**
- * The used `color-scheme` from the `colorScheme` property. Light is the
- * default: embedding is the product, and following the OS would paint a light
- * toolbar in a host that already chose dark. `"auto"` is the opt-in that
- * follows, as CSS `light dark`.
+ * The used `color-scheme` from the `colorScheme` property, light by default:
+ * following the OS would paint a light toolbar in a host that already chose
+ * dark. `"auto"` is the opt-in that follows, as CSS `light dark`.
  *
  * @param {any} colorScheme
  * @returns {string}

package/lib/chrome.js

@@ -4,37 +4,23 @@
  * `stage.js` keeps it paper.
  *
  * This module also owns the **default palette**: the `:host` block below is
- * the one place a `--qv-*` fallback is written, and every sheet — this one
- * included — paints from the `--_*` alias it declares. That is what makes a
- * color one edit rather than a hunt, and `viewer.test.js` holds both halves:
- * `--qv-` appears in no other module, and the aliases read are exactly the
- * ones declared. The fallbacks are `light-dark()`, so a `color-scheme` pin on
- * the host paints chrome without a class.
+ * the one place a `--qv-*` fallback is written, and every sheet paints from
+ * the `--_*` alias it declares. The fallbacks are `light-dark()`, so a
+ * `color-scheme` pin on the host paints chrome without a class. The other
+ * sheets therefore paint only where this one is adopted too — presence, not
+ * order, since a custom property resolves down the inherited chain.
  *
- * The cost is that the other sheets no longer stand alone — they paint only
- * where this one is adopted too. It is presence, not order: a custom property
- * resolves down the inherited chain, so where CHROME sits in `static styles`
- * does not matter, only that it is there.
+ * The two halves are written differently on purpose. A host token must always
+ * win, so a default is a `var()` fallback — which applies only when the token
+ * is unset — never a `:host { --qv-border: … }` rule, whose pseudo-class
+ * specificity would beat the host's own `quario-viewer` rule (ADR 0018). The
+ * private aliases invert that: `:host` outranks the host rule, so nothing
+ * outside can shadow one by accident.
  *
- * Host tokens always win, and `:host` is what makes that survive here. A
- * `:host { --qv-border: … }` *default* would carry pseudo-class specificity
- * and beat a host's own `quario-viewer` rule — the seam ADR 0018 declines to
- * make a lie. A `var()` fallback applies only when the token is unset, so it
- * loses to a host token at any specificity. The private half inverts that on
- * purpose: `:host` outranks that same host rule, so nothing outside can
- * shadow an alias by accident.
- *
- * One of the fifteen is the sheet's rather than the chrome's: a color scheme
- * paints chrome only (ADR 0018), so `--qv-sheet-shadow` is the sheet's edge
- * against the backdrop. It is in the block because it has no exceptions, not
- * because it follows the pin.
- * `--qv-focus` and `--qv-progress` repeat the accent rather than chain a third
- * alias — a host is free to move one alone.
- *
- * What is not here is what another module owns: `stage.js` the surface a
- * report is scaled on, `panel.js` the error panel, `button.js` the controls
- * every group in the bar is built from. The element composes their templates
- * and stylesheets; the imports run one way only.
+ * `--qv-sheet-shadow` is the sheet's edge against the backdrop rather than
+ * chrome (a color scheme paints chrome only, ADR 0018); it sits here because
+ * it has no exceptions. `--qv-focus` and `--qv-progress` repeat the accent
+ * rather than chain a third alias, so a host can move one alone.
  */
 import { css, html, nothing } from "lit";
 
@@ -188,9 +174,8 @@ export let CHROME = css`
 `;
 
 /**
- * The render indicator. Idle it stays out of the accessibility tree — an
- * unstarted progressbar has nothing to announce — and the stylesheet above
- * hooks on the viewer's `aria-busy` to show it.
+ * The render indicator. Idle it stays out of the accessibility tree, and the
+ * stylesheet above hooks on the viewer's `aria-busy` to show it.
  *
  * @param {boolean} busy
  * @returns {import('lit').TemplateResult}

package/lib/index.d.ts

@@ -56,8 +56,9 @@ export interface ViewerErrorDetail {
  * element up with the panel saying why. A superseded render's failure is
  * reported to no one.
  *
- * Removing the element abandons in-flight work and releases its observers;
- * the properties persist, and reconnecting re-renders from them. There is no
+ * Removing the element stops the work in flight and releases its observers;
+ * the properties persist, and reconnecting renders them again unless the last
+ * render landed. There is no
  * `destroy()` — removal is destruction only in the garbage-collection sense,
  * and reparenting is safe. An export settling after removal downloads
  * nothing.

package/lib/index.js

@@ -14,15 +14,13 @@
  * and `@quario/viewer/register` performs the one-line define for hosts that
  * want it (docs/adr/0005-the-surfaces-are-custom-elements.md).
  *
- * Nothing here is markup: the sheet is a stack of canvases, and the list's
- * text reaches them as strings the painter draws, so the viewer has no
- * markup edge and adds no report content of its own. The unlicensed marking
- * rides on the list, one op per page, painted last — the same placement the
- * pdf target writes (docs/adr/0017-the-viewer-watermarks-the-sheet.md).
+ * Nothing here is markup: the sheet is a stack of canvases, so the viewer has
+ * no markup edge. The unlicensed marking rides on the list, one op per page,
+ * painted last (docs/adr/0017).
  *
- * The error panel is the only wording the viewer authors, and it is not
- * report content: it names which failure occurred, because no error knows
- * whether it was a mount, an update or an export (panel.js).
+ * The error panel is the only wording the viewer authors: it names which
+ * failure occurred, because no error knows whether it was a mount, an update
+ * or an export (panel.js).
  */
 import { Task, TaskStatus } from "@lit/task";
 import { LitElement, html } from "lit";
@@ -50,15 +48,13 @@ export const TAG = "quario-viewer";
 /**
  * The viewer element. Hosts assign `report`, `targets` and `data` (plus the
  * option properties `zoom`, `page`, `fonts`, `filename` and `colorScheme`)
- * and listen for `rendered` and `error`; rapid successive writes render only
- * the newest state, because the render pipeline is a task keyed on those
- * properties and the task's own call-id guard drops every superseded run
- * whole — including its failure, which is reported to no one (ADR 0005's
- * narrowed guarantee).
+ * and listen for `rendered` and `error`. Rapid successive writes render only
+ * the newest state: the task's call-id guard drops every superseded run
+ * whole, including its failure, which is reported to no one (ADR 0005).
  *
- * Removal is not destruction: disconnecting abandons in-flight work and
+ * Removal is not destruction: disconnecting stops the work in flight and
  * releases the resize observer, the properties persist, and reconnecting
- * re-renders from them. There is no `destroy()`.
+ * renders them again unless the last render landed. There is no `destroy()`.
  */
 export class QuarioViewer extends LitElement {
   // CHROME declares the default palette every other sheet paints from, so it
@@ -118,33 +114,34 @@ export class QuarioViewer extends LitElement {
 
   // The whole async pipeline: keyed on the render properties, re-run when one
   // changes — `page` and `fonts` among them, since either moves where the
-  // pages break. The task's call-id guard is the latest-wins machinery; side
-  // effects — the stage swap and both events — live only in the callbacks
-  // below, which that guard restricts to the newest run, never in the task
-  // body a stale run still executes to completion. `null` is the "nothing to
-  // show" result: unlike the task primitive's own initial-state symbol it
-  // settles `taskComplete`, which is what lets `renderComplete` always answer.
+  // pages break. Side effects live only in the callbacks below, which the
+  // task's call-id guard restricts to the newest run, never in the task body a
+  // stale run still executes to completion. `null` is the "nothing to show"
+  // result: unlike the 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.#landing.epoch],
-    task: async ([report, targets, data, page, fonts], { signal }) => {
+    task: async ([report, targets, data, page, fonts]) => {
+      // First, before anything that can throw: the debt opens by starting, so
+      // every way of not landing keeps it without saying so (ADR 0075). A
+      // host-option throw out of `#begin` is one of them.
+      this.#landing.owe();
       if (!this.#begin(report, targets)) return null;
       // The sheet's own target: the layout list, on the host's page and
       // fonts — the same two a host passes to `pdf()`, which is what makes
       // the preview page where the document pages.
       let target = layout({ page: /** @type {any} */ (page), fonts: /** @type {any} */ (fonts) });
       let list = await /** @type {any} */ (report).render(target, data);
-      // 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.#landing.dropped(signal, this.isConnected)) return this.#landing.abandon();
       return { list, fonts };
     },
     onComplete: (result) => {
       if (result === null || !this.isConnected) return;
       // 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.#landing.land();
+      // The boundary takes the paint rather than a promise to report back
+      // with: it reads which run this is here, while this run is still the
+      // newest one.
+      this.#painting = this.#landing.land(this.#stage.swap(result.list, result.fonts)).then(() => {
         // 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
@@ -264,9 +261,9 @@ export class QuarioViewer extends LitElement {
     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
+    // Reconnect re-renders from the current properties — but only where a
+    // render is owed, which is every run that did not reach the sheet
+    // (ADR 0075). The task's arguments did not
     // change, so the epoch is what re-runs it; left alone, reparenting a
     // settled viewer costs nothing.
   }
@@ -283,16 +280,17 @@ export class QuarioViewer extends LitElement {
    * A property the host got wrong fails loudly even while there is nothing to
    * render yet: a misconfigured host is caught in development, not when the
    * report arrives. Nothing assigned yet is not a failure. Disconnected
-   * elements keep processing updates, so the guard is what makes removal
-   * abandon work rather than merely hide it.
+   * elements keep processing updates, so the guard is what stops a removed
+   * element working where nobody is looking; the debt the run opened stands
+   * either way, and reconnecting collects it.
    *
    * @param {unknown} report
    * @param {unknown} targets
+   * @returns {boolean} Whether there is a render to do.
    */
   #begin(report, targets) {
     if (this.#options.invalid) throw this.#options.invalid;
-    if (vacant(report, targets)) return null;
-    if (!this.isConnected) return this.#landing.abandon();
+    if (vacant(report, targets) || !this.isConnected) return false;
     exports(report, targets);
     return true;
   }

package/lib/panel.js

@@ -6,15 +6,13 @@
  * Always the compound — "the error panel", never a bare "panel", which stays
  * the word for the host's own UI regions around the viewer (see CONTEXT.md).
  *
- * It is the one place the viewer states wording of its own. Everything else it
- * shows comes from the report: the fragment is the html target's, and even the
- * unlicensed marking's wording arrives inside it. A label cannot, because no
- * error knows whether it was a mount, an update or an export that failed —
- * which is exactly what the error event's `kind` names.
+ * It is the one place the viewer states wording of its own: no error knows
+ * whether it was a mount, an update or an export that failed, which is what
+ * the error event's `kind` names.
  *
- * What it prints beside that label is the error's own message, as a template
- * value. That is a markup edge, and it stays one: a message can carry report
- * data, because a host's registry function is free to interpolate a row into
+ * Beside that label it prints the error's own message, as a template value.
+ * That is a markup edge and stays one: a message can carry report data,
+ * because a host's registry function is free to interpolate a row into
  * whatever it throws (hard constraint 4).
  */
 import { css, html } from "lit";

package/lib/stage.js

@@ -13,63 +13,34 @@
  *
  * 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.
+ * on screen and one viewport height either side. The extent 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 0043, 0065).
  *
  * **A page the browser will not paint is blank, not a failure.** `start`
  * swallows and nothing here rejects: the report laid out and the list reached
- * the sheet, which is all a render promised, so the surfaces have no channel
- * for it and deliberately grow none.
- *
- * Little reaches it. An image that will not decode is the layout's own to
- * absorb — `paint` draws it as nothing and draws the page around it — and a
- * face is parsed with fontkit while the report is measured, so bytes that will
- * not parse are a render error long before the sheet. What is left is the face
- * fontkit accepted and the browser refuses, which the browser suite drives by
- * making `FontFace.prototype.load` reject under a record handed straight to
- * `swap`.
+ * the sheet, which is all a render promised.
  *
  * **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 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).
+ * *retired*: it comes off the sheet and a fresh one stands in its place, so
+ * the superseded paint draws into an element nobody is looking at. Otherwise
+ * 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 (ADR 0046). A
+ * canvas whose paint has settled is re-sized in place.
  *
- * 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
- * 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.
+ * Retirement is lazy: 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 shows its old pixels stretched until its turn comes. The cost is that
+ * a retired page is a replaced `role="img"` node, which assistive technology
+ * sees swapped under it — accepted, because the alternative 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
- * stage's own — `percent()` reports it, so no caller keeps a second copy.
- *
- * The editor builds its own stack of pages next door, and deliberately: what
- * the two surfaces share is the display list and the size of a point, not the
- * sheet. Each is a canvas element, a device-pixel size and a `paint()` call
- * around policy neither could lend the other — this one repaints under zoom
- * and guards a superseded repaint, that one builds once per swap and lays box
- * elements over the result.
+ * owns the policy over that answer. `percent()` reports what is on screen, so
+ * no caller keeps a second copy.
  */
 
 import { css } from "lit";
@@ -191,20 +162,16 @@ export let stage = () => {
 
     /**
      * Scale to `percent`, holding the middle of the viewport where it was:
-     * scaling about the sheet's corner would otherwise throw the reader back
-     * toward the top-left of whatever they were reading. The sheet starts one
-     * gutter down the scroll extent, so the centre converts through that
-     * 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. 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.
+     * scaling about the sheet's corner would throw the reader back toward the
+     * top-left of what they were reading. The sheet starts one gutter down the
+     * scroll extent, so the centre converts through that offset; horizontally
+     * the wrapper is centred by auto margins while it fits — exactly when
+     * `scrollLeft` is 0 — and its margins are 0 once it overflows. A sheet
+     * with no list on it has no view to hold. Asked of the list rather than
+     * the sheet's children, which since ADR 0065 are the reach's and can be
+     * none of them while a list is standing.
      *
-     * 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.
+     * Only the reach is repainted, and only where the scale actually changed.
      */
     scale: (percent) => {
       let held = paged.count() > 0 && {
@@ -236,17 +203,12 @@ export let stage = () => {
     },
 
     /**
-     * Put a laid-out report on the sheet, keeping the reader where they
-     * 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
-     * browser will not draw and the reach walks on past it.
+     * Put a laid-out report on the sheet, keeping the reader where they were.
+     * The order is the point of the method: the sheet takes its height from
+     * the list first, 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 afterwards. The returned promise
+     * settles behind the reach and **never rejects**.
      */
     swap: async (next, faces) => {
       // Reading the offsets flushes layout, so only an actual reswap pays for

package/lib/zoom.js

@@ -5,24 +5,17 @@
  * it (see stage.js).
  *
  * The preview **scales; it never reflows**. Fit shrinks the rendered sheet
- * like a photograph, so line breaks, column widths and point sizes stay
- * exactly what they are at 100%. Letting the sheet's width follow the viewer
- * instead would keep small text readable, but it would lay the report out
- * differently from the document the pdf target will page — and the `page`
- * property exists to promise those two agree. A legible-at-any-width reading mode
- * would be a separate feature under its own name, not something fit becomes
- * quietly.
+ * like a photograph, so line breaks, column widths and point sizes stay what
+ * they are at 100%. Letting the sheet's width follow the viewer would lay the
+ * report out differently from the document the pdf target pages, and the
+ * `page` property exists to promise those two agree.
  */
 
 /**
  * The percentages the menu offers, and — through its ends — the range the
  * `zoom` property accepts (check.js reads them, so the two cannot drift).
- *
- * The ends are therefore public API, not a menu detail: moving the first or
- * last entry widens or narrows what a host may author. `viewer.test.js` spells
- * the current range out in the message it expects, so such a move fails a test
- * that says so rather than passing quietly. Adding a stop between the ends is
- * free.
+ * The ends are therefore public API: moving the first or last entry widens or
+ * narrows what a host may author. Adding a stop between them is free.
  */
 export let STEPS = [25, 50, 75, 100, 150, 200];
 

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@quario/viewer",
-  "version": "0.9.0",
-  "description": "The embeddable report viewer shell for quario — in the makings, not yet released",
+  "version": "0.10.0",
+  "description": "Tiny, embeddable report viewer for quario. A custom element that pages on screen and exports what you hand it.",
+  "keywords": [
+    "csp",
+    "custom-element",
+    "quario",
+    "report",
+    "viewer"
+  ],
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -44,8 +51,8 @@
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/landing": "^0.2.1",
-    "@quario/layout": "^0.6.0",
+    "@quario/landing": "^0.3.0",
+    "@quario/layout": "^0.7.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
@@ -53,13 +60,12 @@
     "@cantoo/pdf-lib": "~2.9.1",
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
-    "exceljs": "^4.4.0",
-    "quario": "^0.9.0",
+    "quario": "^0.10.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.9.0"
+    "quario": "^0.10.0"
   },
   "size-limit": [
     {