@quario/viewer 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @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
+
+- The viewer offers a Word download. Pass a `docx` target in `targets`, and the bar carries a `DOCX`
+  button beside the others. The buttons keep the order you gave. The file carries the content type
+  `application/vnd.openxmlformats-officedocument.wordprocessingml.document`.
+
+  Earlier versions dropped a `docx` target. The viewer rendered no button for it, and it reported no
+  failure.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.9.0
+  - @quario/layout@0.6.0
+  - @quario/landing@0.2.1
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -2,13 +2,28 @@
 
 **The embeddable report viewer for [quario](https://www.npmjs.com/package/quario), as a custom
 element.** Write `<quario-viewer>`, assign it a compiled report, the export targets you want, and
-data; it lays the report out on pages — the same pages the PDF target writes — paints them on a
+data. It lays the report out on pages — the same pages the PDF target writes — paints them on a
 white sheet in its shadow root, and offers export downloads for the targets you passed.
 
 The viewer is not a render target and compiles nothing. The sheet is `@quario/layout`'s display
-list, painted page by page; you pass the export targets you want, and the viewer wires a button
-to each (`"pdf"`, `"xlsx"`, `"csv"`). The bar always carries the zoom control; with no exportable
-target it carries nothing else.
+list, painted page by page. You pass the export targets you want, and the viewer wires a button
+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
 
@@ -16,10 +31,10 @@ target it carries nothing else.
 npm install quario @quario/viewer
 ```
 
-The engine is a peer; the viewer itself depends on no target package. Install the targets you want
-to export with (`@quario/pdf`, `@quario/xlsx`, `@quario/csv`) and pass them in. Its own runtime
-dependencies are [Lit](https://lit.dev) (`lit` + `@lit/task`) and `@quario/layout`, the paged
-layout it paints, plain ESM like everything else here. ESM-only, and
+The engine is a peer. The viewer itself depends on no target package. Install the targets you want
+to export with (`@quario/pdf`, `@quario/xlsx`, `@quario/csv`, `@quario/docx`) and pass them in. Its
+own runtime dependencies are [Lit](https://lit.dev) (`lit` + `@lit/task`) and `@quario/layout`, the
+paged layout it paints, plain ESM like everything else here. ESM-only, and
 browser-only by nature: the element needs a DOM. CSP-safe like the rest of quario. No
 string-to-code paths, chrome styled through constructed stylesheets, so your `style-src` never
 sees a style tag.
@@ -28,6 +43,7 @@ sees a style tag.
 
 ```js
 import { csv } from "@quario/csv";
+import { docx } from "@quario/docx";
 import { pdf } from "@quario/pdf";
 import { xlsx } from "@quario/xlsx";
 import { quario } from "quario";
@@ -35,14 +51,14 @@ import "@quario/viewer/register";
 
 const view = document.querySelector("quario-viewer");
 view.report = quario().report(schema, funcs);
-view.targets = [pdf(), xlsx(), csv()];
+view.targets = [pdf(), xlsx(), csv(), docx()];
 view.data = data;
 view.filename = "sales";
 ```
 
 with `<quario-viewer></quario-viewer>` in your markup, sized by your own CSS. The element is
-`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
+`display: block`, and its chrome fits a width of **320px**, a phone-width embed and the narrowest
+the bar supports. 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
@@ -67,14 +83,14 @@ package to install. See [Using with React, Vue and Svelte](#using-with-react-vue
 | `colorScheme` | `"light"`, `"dark"`, or `"auto"`                | `"light"`   |
 
 Properties, not attributes: `report`, `targets`, `data`, `page` and `fonts` are values no attribute
-could carry. `targets` mirrors `report.render(target, data)` for the exports: `"pdf"`/`"xlsx"`/`"csv"`
-targets become export buttons, in the order given, and the sheet needs none of them. The quario
-instance (and with it the license and the registry) stays yours: the element takes the compiled
-report, never a schema.
+could carry. `targets` mirrors `report.render(target, data)` for the exports:
+`"pdf"`/`"xlsx"`/`"csv"`/`"docx"` targets become export buttons, in the order given, and the
+sheet needs none of them. The quario instance (and with it the license and the registry) stays
+yours: the element takes the compiled report, never a schema.
 
 Assigning `data` (or any of the others) re-renders. Rapid successive writes render only the newest
 state: a slow render can never overwrite a newer one, and a superseded render fires no event.
-Assignments are compared by identity, so to re-render from the same object, assign a fresh one
+The viewer compares assignments by identity, so to re-render from the same object, assign a fresh one
 (`view.data = { ...data }`).
 
 `page` and `fonts` are the pdf target's own options: the viewer lays the report out on them, so
@@ -90,40 +106,41 @@ view.addEventListener("error", ({ detail: { error, kind } }) => {});
 await view.renderComplete; // true when the newest render landed on the sheet
 ```
 
-`rendered` fires each time a render lands on 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.)
+non-bubbling, like `<img>`'s. Listen on the element. (Because the event carries the name `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 landed on the sheet with the pages
 on screen finished trying to paint, `false` when it failed or there was nothing to render. It never
-rejects; failures arrive on the `error` event. `rendered` fires at that same moment. Like every
-outcome here, it answers for the newest render only. A superseded render's failure is reported to no
+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 reaches no
 one.
 
 An image the browser cannot decode — pixel data corrupt past the size in its header, which is all
 the engine reads — is drawn as nothing, and the page is drawn around it. That is not a render
-failure: `renderComplete` answers `true`, `rendered` fires, and no `error` event is raised. A face in
-`fonts` is a different story: it is parsed while the report is measured, so bytes that will not parse
-are a render error with a panel.
+failure: `renderComplete` answers `true`, `rendered` fires, and no `error` event follows. A face in
+`fonts` is a different story. The layout parses it while it measures the report, so bytes that will
+not parse are a render error with a panel.
 
 Your own mistakes surface on the same channel: a report that is not compiled, or a malformed
 option property, becomes a `TypeError` naming the property, on the `error` event and the
-[error panel](#errors). No particular target is required — the sheet is the layout's own.
+[error panel](#errors). The viewer needs no particular target — the sheet is the layout's own.
 
 ## 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
 
 No wrapper packages: each framework sets properties on custom elements directly, so the samples
-below are the whole integration. All three were run before landing here. Import
+below are the whole integration. Each of the three ran before landing here. Import
 `@quario/viewer/register` once, anywhere before the component mounts, and size the element with
 your own CSS.
 
@@ -150,7 +167,7 @@ function Report({ report, targets, data }) {
 }
 ```
 
-Re-rendering with a new `data` prop re-renders the report; the newest write wins, as always.
+Re-rendering with a new `data` prop re-renders the report. The newest write wins, as always.
 (React 18 and earlier stringify unknown props to attributes. There, hold a `ref` and assign the
 properties and listeners in an effect.)
 
@@ -213,46 +230,47 @@ listeners:
 
 The bar's magnifier opens the zoom menu: **Fit page** on its own, then 25%, 50%, 75%, 100%, 150%
 and 200%. A check marks the current mode — Fit page whenever the viewer is fitting, whatever
-percentage that came out at — and the percentage on screen is what the trigger is named after
+percentage that came out at — and the trigger carries the percentage on screen in its name
 ("Zoom, 62%"), so nothing in the bar changes width as it moves. The `zoom` property picks the mode
 the viewer opens in: a percentage between 25 and 200 — continuous, not one of the menu's stops — or
 `"fit"`, the default. A percentage the menu does not offer leaves every row unchecked.
 
 Fit sizes one page to the viewer's width and **only ever shrinks**: given room to spare it stops at
-100%, so the report is shown at its true point size rather than blown up. It has no floor, so a
+100%, so the report keeps its true point size rather than growing past it. It has no floor, so a
 narrow pane fits at whatever percentage that takes — below 25% the menu has no row to return to it,
 and **Fit page** is the only way back. A fitted viewer follows its own box, so a collapsing panel
 or a resized window re-fits on its own.
 
-The preview **scales; it never reflows.** Zooming repaints the pages larger or smaller, like a
+The preview **scales. It never reflows.** Zooming repaints the pages larger or smaller, like a
 photograph that stays sharp. Line breaks, column widths and point sizes stay what they are at
 100%, because the layout never changes under a zoom.
 
-Only the pages near the viewport are painted — the ones on screen and one screenful either side.
+The viewer paints only the pages near the viewport — the ones on screen and one screenful either side.
 Every page keeps its size, so the scrollbar and the scroll extent are the whole report from the
-start; a page further off is blank paper until you scroll to it, which is why a zoom step costs the
+start. A page further off is blank paper until you scroll to it, which is why a zoom step costs the
 same on a thousand-page report as on a five-page one.
 
 ## What the preview is
 
 The pages on screen are the pages the PDF export writes: both consume one layout, `@quario/layout`'s
-display list, laid out on your `page` and `fonts`. A report shorter than a page is one page; a
-longer one is as many as the layout breaks it into, stacked down the sheet. Sizing a container to a
-viewer showing a short report therefore reserves a full page — set `zoom` to a percentage small
-enough where the box has to stay small.
-
-Each page is a canvas, and text on it is drawn in the face the document will use. A TrueType
-family you pass as `fonts` is registered from your own bytes and drawn as the browser shapes it —
+display list, laid out on your `page` and `fonts`. A report shorter than a page is one page. A
+longer one is as many pages as the layout breaks it into, stacked down the sheet. Sizing a
+container to a viewer that draws a short report therefore reserves a full page. Set `zoom` to a
+percentage small enough where the box has to stay small.
+
+Each page is a canvas, and text on it is drawn in the face the document will use. The viewer
+registers a TrueType family you pass as `fonts` from your own bytes and draws it as the browser
+shapes it —
 the same shaping the PDF gets from the same file, so ligatures, joined scripts and accents look
 here the way they will on paper. Text in the built-in families is drawn character by character at
 the advances the layout measured, because the font a browser has for Helvetica, Times or Courier
 only stands in for the one the PDF writes, and the correction is what makes a line fill the same
 width and break in the same place the document does. Inside one run of a family you supply, a
-browser may kern by a fraction more than the document; where lines break and pages end is the
-layout's, and identical. Images are decoded from their bytes — no `data:` URIs, so a host page's
+browser may kern by a fraction more than the document. Where lines break and pages end is the
+layout's, and identical. The viewer decodes images from their bytes — no `data:` URIs, so a host page's
 Content Security Policy needs no `img-src` grant for them.
 
-Rendering an unlicensed evaluation, the marking is painted across every page, the way the PDF
+Rendering an unlicensed evaluation, the viewer paints the marking across every page, the way the PDF
 export marks every page: it rides on the layout, so what you see is what the document carries. A
 licensed render carries none.
 
@@ -262,8 +280,8 @@ reads `aria-busy="true"`. It reports that the viewer is working, not how far alo
 engine streams events and cannot know how many are still coming.
 
 There is no Print button, because the sheet is the wrong thing to print. Your page's stylesheets do
-not cross into the shadow root, so `@media print` rules never reach the report; and the pages are
-painted at whatever zoom the reader happened to leave them, so printing the page puts the viewer's
+not cross into the shadow root, so `@media print` rules never reach the report. The viewer also
+paints the pages at whatever zoom the reader happened to leave them, so printing the page puts the viewer's
 chrome on paper at that zoom. What a printer wants is the pdf target's
 document, the same bytes the PDF export hands over. A host that wants its own Print button owns
 two lines:
@@ -280,19 +298,23 @@ the export is, watermark and all.
 
 ## Errors
 
-When a render or an export fails, the viewer says so on the **error panel**, a strip across the top
-of the sheet carrying a short label — "Could not render the report", "Could not update the report — showing the previous version", or "Could not export PDF" — and the error's own message. It replaces rather than stacks, is
-dismissed by its own button, and is cleared by the next render that lands on the sheet. A successful
-export leaves it up, because the panel describes what you are looking at and a download says
-nothing about that.
+When a render or an export fails, the viewer says so on the **error panel**. The panel is a strip
+across the top of the sheet, carrying the error's own message under one of three short labels:
+
+- "Could not render the report"
+- "Could not update the report — showing the previous version"
+- "Could not export PDF" It replaces rather than stacks, its own
+  button dismisses it, and the next render that lands on the sheet clears it. A successful
+  export leaves it up, because the panel describes what you are looking at and a download says
+  nothing about that.
 
-Every failure the panel draws, and every export failure, also fires the `error` event; nothing is
-rethrown to the platform behind it. Failures after the element is removed are not reported, and a
+Every failure the panel draws, and every export failure, also fires the `error` event. The viewer rethrows
+nothing to the platform behind it. Failures after the element leaves the DOM go unreported, and a
 render that a newer one has already superseded reports to no one at all.
 
 The message carries quario's **located error**, the band/item path and the offending source, as in
-`detail[0] [{{ @.amount.toFixed(2) }}]: ...`. Showing it is safe because report definitions are
-trusted configuration; report _data_ never is, and none of it appears in the path. What can carry
+`detail[0] [{{ @.amount.toFixed(2) }}]: ...`. Drawing it is safe because report definitions are
+trusted configuration. Report _data_ never is, and none of it appears in the path. What can carry
 data is the message itself, if your own registry functions interpolate a row into what they throw.
 That is your call, and the panel puts it on screen as text, never as markup. Compile errors are not
 part of this: `q.report(schema)` raises those before the viewer is ever handed a report.
@@ -300,7 +322,7 @@ part of this: `q.report(schema)` raises those before the viewer is ever handed a
 ## Color scheme
 
 `colorScheme` paints the **chrome** — backdrop, bar, controls, progress strip, error
-panel — and never the sheet. `"light"` (the default) and `"dark"` pin; `"auto"` follows
+panel — and never the sheet. `"light"` (the default) and `"dark"` pin. `"auto"` follows
 the OS via CSS `color-scheme`. The pages stay white, marking included.
 
 Chrome styles live on `--qv-*` custom properties under stable `qv-*` class names. A
@@ -323,10 +345,10 @@ specification of what a report may declare, and
 
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key once, on the instance; it is verified offline:
+Pass your license key once, on the instance. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

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.
@@ -67,7 +68,7 @@ export class QuarioViewer extends LitElement {
   report: ViewableReport | undefined;
   /**
    * The export targets, as passed to `report.render`: ones named
-   * `"pdf"`/`"xlsx"`/`"csv"` become export buttons, in array order. The
+   * `"pdf"`/`"xlsx"`/`"csv"`/`"docx"` become export buttons, in array order. The
    * sheet needs none of them — it is the layout's own. An empty array is
    * a viewer with nothing to export.
    */

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

@@ -22,6 +22,7 @@ export let EXPORTS = {
   pdf: "application/pdf",
   xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
   csv: "text/csv",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
 };
 
 // The anchor joins the document for the click — detached-anchor downloads

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.8.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,22 +51,21 @@
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/landing": "^0.2.0",
-    "@quario/layout": "^0.5.0",
+    "@quario/landing": "^0.3.0",
+    "@quario/layout": "^0.7.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
-    "@cantoo/pdf-lib": "^2.9.1",
+    "@cantoo/pdf-lib": "~2.9.1",
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
-    "exceljs": "^4.4.0",
-    "quario": "^0.8.0",
+    "quario": "^0.10.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.8.0"
+    "quario": "^0.10.0"
   },
   "size-limit": [
     {