@reportwright/viewer 0.13.0 → 0.13.2-rc.1

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All `@reportwright/*` packages (formerly `@pagewrightjs/*`) share one version. The versioning policy is in [CONTRIBUTING.md](CONTRIBUTING.md#versioning-semver).
 
+## 0.13.2-rc.1 — 2026-10-09 (release candidate)
+
+### Changed
+- **The rename to ReportWright is finished; every old Pagewright name keeps working until 1.0.** New names, with the old one kept as a deprecated alias:
+  - report schema: `reportwright/report@1` is now what new and saved reports carry; `pagewright/report@1` is read as the same format (a server before 0.9 cannot open a report saved by 0.13.2).
+  - HTTP headers: `x-reportwright-pages`, `-ms`, `-warnings`, `-snapshot`, `-pending`, `-signature` (webhooks and the audit SIEM webhook) and `-idempotency-key` (mail) are sent together with the old `x-pagewright-*` header; the proxy secret is read from `x-reportwright-proxy-secret`, else `x-pagewright-proxy-secret`.
+  - Prometheus metrics: `/api/v1/metrics` emits every family as `reportwright_*` and again as `pagewright_*` (the old ones go in 1.0: move dashboards and alerts). `scripts/uptime-check.mjs` reads either.
+  - one console warning per page for `definePagewrightElements`, the `<pagewright-viewer>` / `<pagewright-designer>` tags, the Svelte `pagewrightViewer` / `pagewrightDesigner` actions, `window.Pagewright` and `/embed/pagewright-viewer.js` (and `-viewer.full.js`). The React and Vue `PagewrightViewer` / `PagewrightDesigner` stay the same components, without a warning; all are typed `@deprecated`.
+  - the live demo moved to https://mrarun005.github.io/reportwright-demo/ (the site build's default base is `/reportwright-demo/`).
+  - kept as they are, since changing them would break stored data: the `.pw.json` extension, the designer clipboard format `pagewright/items@1`, and the salts of the TOTP secret key and the audit checkpoint chain.
+- **The render worker is minified.** `engine.worker.js` (and `engine.worker.bwip.js`) in `@reportwright/viewer` and the embed builds are minified, still one file with no chunk imports, with a linked source map (`engine.worker.js.map`) beside it so worker stack traces stay readable. `engine.worker.js` 2,195,290 → 1,218,659 bytes (608 → 503 KB gzipped); `engine.worker.bwip.js` 1,651,602 → 973,261 bytes (315 → 267 KB gzipped). The size budget in tests/engine/b10-bundle-size.test.js is now 504 KB gzipped (was 600).
+- **Publishing verifies before `latest` moves.** The publish workflow publishes to the `next` dist-tag, installs all nine packages from the registry and smoke-tests them (imports, PDF/XLSX/DOCX export, `qpdf --check`, `pw render`, the viewer's files, the wrappers' peer), and only then moves `latest`.
+
+### Performance
+- **Trade-off made by 0.13.1: less memory, about 10–14% slower.** The 0.13.1 fixes for grouped sorts (N44: sort runs spill to disk in smaller runs, about 8 MB) and for streamed tagged PDFs (N44: tagged structure flushed per page) cost time for the memory they save: about 10–14% slower on the tester's 2 vCPU machine (not measured here). Memory: a 200,000-row grouped ledger peaks at 232 MB instead of 280 MB, and the same with 50 runs (1,000,000 rows' run count) 240 MB instead of 296 MB; a tagged streamed PDF at 50k/100k/200k rows holds 6.7/7.3/9.3 MB off-heap instead of 16.8/29.1/36.6 MB. `spillSorter({ runMB, mergeMB })` sets the sort's run size if speed matters more than memory.
+### Added
+- **`pw import <folder>`: bulk import.** Every `.rdl`, `.rdlc`, `.jrxml`, `.rptdesign` and `.rdlx-json` report in a folder (`--recursive` for subfolders) is imported into `-o <outDir>`, which mirrors the folder.
+  - One bad file never stops the batch. Exit 0 means all were imported, 2 some failed, 1 none.
+  - Subreports, SSRS shared data sources (`.rds`), JasperReports style templates (`.jrtx`) and images are resolved across the batch. Images are copied once per content. Unresolved references are listed per file.
+  - `import-report.json` and a standalone, escaped `import-report.html` give for each file the mapped, approximated and dropped counts, each item's reason, and every expression that was not translated with its line and column.
+  - `.pw-import.json` holds the hash of each written file, and a re-run skips an output the user edited unless `--force`.
+  - `--verify` renders each report with its embedded or sample data and compares it with the output it replaced.
+  - Paths from the folder are untrusted. Links that point outside it are refused, outputs stay in `outDir`, and `--max-files` and `--max-bytes` cap the input.
+  - The importers now return structured `items` (each item's notes, untranslated expressions and source position) and take a `resolve` option for shared data sources and style templates.
+  - Docs: the CLI README, "Bulk import". Test: tests/engine/c132-import-batch.test.js.
+- **`pw --version` / `pw -v`** prints the CLI version (from its package.json) and the version of the engine it carries.
+- **`showWarnings`** (viewer option, default `false`): shows the render's warnings under the pages; the designer's Preview always shows them. Documented in the viewer README and typed in `ViewerOptions`.
+- **ⓘ help tooltips in the designer.** Long help paragraphs (the Outline, Layers and Parts panels, field hints over 90 characters) sit behind an ⓘ button that opens on hover, keyboard focus or click and closes with Esc; the button is described by the text (`aria-describedby`).
+### Fixed
+- **An unchecked check box has no tick on the designer canvas.** The canvas drew ✓ in every check box; it now follows the value as the renderer does (`false`, `=False`, a missing value: empty), and dims the tick of a value only the data decides.
+- **Selecting an item no longer moves the canvas.** The canvas toolbar grew a second row (24 px) when the align buttons of a selection appeared; it now has one fixed height (it scrolls sideways when narrow) and its hint moved to the status bar.
+- **Keyboard nudge steps.** Arrow moves the selection 1 pt, or one grid step with Snap to grid on (a cell in cell mode); Shift+Arrow moves ten of them (it was 4 grid steps); positions stay rounded to 2 decimals.
+- **Render warnings in the viewer read as words.** The count says "8 warnings" or "1 warning", not "warning(s)".
+- **The Data panel lists a data set's fields when it declares none.** It said "No fields" next to 300 rows; it now detects them from inline JSON or the first rows of fetched data with the engine's own detection (`detectFields`, the one streaming uses) and marks them as detected.
+- **No cut-off text in the Inspector and the Outline.** The Regional "Division by zero" choice gets the full width ("Infinity (as SSRS)" was cut); a long name in the Outline wraps inside the panel, with the full name as its tooltip, and the item type and buttons move under it together.
+- **The parameter dialog's help matches the viewer.** The live-parameters option no longer says that turning it off adds a View report button (the button is always there), and the panel-columns help says the grid applies on a wide screen.
+- **Export options icon.** The sun-like gear is a sliders icon; the button keeps its name, Export options.
+
+## 0.13.1 — 2026-10-09
+
+### Fixed
+- **N10: the CJK fonts are named Regular in the PDF.** `@reportwright/fonts-cjk` downloads variable TrueType fonts whose default instance is Thin; 0.13.0 cut and renamed the subset at Regular, but `exportPdf` and `exportPdfStream` built the BaseFont from the full font's PostScript name, so pdffonts showed `NotoSansJP-Thin` / `NotoSansKR-Thin`. Both now take the name from the subset they embed (`NotoSansJP-Regular`). Test: tests/engine/b11-cjk-names.test.js (the downloaded fonts are tested when present).
+- **N44: a streamed tagged PDF's memory stays flat.** The writer kept where each object is in arrays of 7 bytes an object that doubled; a tagged million-row ledger has 8–11 million objects (an element per cell), most of tagging's ~125 MB at 1M rows. They are now blocks of 16,384 entries, each deflated (~2 KB) once the numbers are two blocks past; the tagger lets go of a page's elements when it ends. Same file byte for byte (but its ID): veraPDF UA-1 and A-2a pass, same `pdfinfo -struct` tree. Off-heap peak at 50k/100k/200k rows: 16.8/29.1/36.6 MB before, 6.7/7.3/9.3 MB after (RSS ~205 MB either way). Test: tests/engine/b11-n44-tagged-memory.test.js.
+- **N45: `pw render` stopped by a signal leaves no temporary file.** SIGTERM (Docker, Kubernetes, CI), SIGINT (Ctrl+C) and SIGHUP remove `<file>.<pid>.part`, keep an older PDF at the path as it was, and exit 143, 130 or 129. Before, every one of them left the `.part` file. Test: tests/engine/b10-perf-cli.test.js.
+- **N41: a copied worker starts.** The npm package's `engine.worker.js` bundles its libraries (bidi-js, fontkit) instead of importing them by name, so an esbuild app that copies it next to its bundle renders in the worker (it crashed with "Failed to resolve module specifier bidi-js" and fell back to the main thread). Barcodes and the standard-font metrics are files next to it (`engine.worker.bwip.js`, `engine.worker.stdfonts.js`), as in the browser build; the README says to copy `engine.worker*.js`. Test: tests/e2e/b11-esbuild-worker.mjs.
+- **N40: `fonts` is optional.** `render()`, `exportPdf()`, `exportPdfStream()` and the Word, Excel and PowerPoint exports use one default store over `@reportwright/fonts` when given none, and an export loads the fonts the model uses into whatever store it gets, so render and export need not share a store (it failed with "this.loader is not a function" or 'Font "Helvetica" is not loaded'). A report in the standard PDF fonts needs no store and no fonts package (a bold title in a Helvetica report no longer loads Inter-Bold); a font that cannot load says "Install @reportwright/fonts, or pass { fontStore }". Test: tests/engine/b11-fonts-n40.test.js, and the packed packages in all four combinations (packages.test.js).
+- **N19: one warning prefix.** The engine package's console warnings and deprecations start with `[reportwright]`, as the rest do (they said `[@reportwright/engine]`).
+- **N43: the standard-font metrics are a table.** Helvetica, Times, Courier, Symbol and ZapfDingbats widths and font-wide metrics are generated once from the Adobe AFM data (`scripts/gen-standard-metrics.mjs` → `src/engine/text/standard-metrics.js`, 22 KB, 5 KB gzipped) instead of decompressed with pako from `@pdf-lib/standard-fonts` at every cold start; that package is no longer a dependency of `@reportwright/engine` or `@reportwright/viewer` (pdf-lib still installs it for itself), and the viewer's `engine.worker.stdfonts.js` is gone (the table is in the worker: 588 → 594 KB gzipped, about 100 KB gzipped less in all). PDFs are byte-identical. A new process making a 1-page Helvetica invoice: median of 10, 115 → 94 ms on an M2 (Node 20). Test: tests/engine/b11-fonts-n43.test.js.
+- **N42: the designer Outline passes axe.** It was a `listbox` whose rows also hold their move buttons (a listbox may hold only options: aria-required-children, critical). The rows are now toggle buttons (`aria-pressed`) in a labelled group, with the same keyboard: one Tab stop, Up/Down/Home/End, Enter or Space selects.
+- **N44: a large sort's memory stays flat.** The disk spill behind grouped and sorted streamed reports held a 1,000-row batch from every sorted run while merging (50 runs at 1,000,000 rows), so its memory grew with the rows. Runs are now about 8 MB (at most 10,000 rows), batches 200 rows, and the merge holds about 4 MB: past that many runs, groups of runs are merged on disk first. A 200,000-row grouped ledger: 280 → 232 MB peak; the same with 50 runs (the run count of 1,000,000 rows): 296 → 240 MB. `spillSorter({ runMB, mergeMB })` sets them. The engine README recommends `presorted: true` with ORDER BY at the source for big grouped reports. Test: tests/engine/b11-mem-spill.test.js.
+- **SILENT-6: an item taller than the page warns in `validate()`.** A body item taller than the room the page has for the body (the page less its margins, page header and footer, a body section's own page and bands counted) warns with both heights and what the render does: its lower part is cut at the page bottom (a text box's text of more than one line continues on the next page). Tables, matrices, lists and subreports, which split by their rows, and pageless pages are quiet. `render()` keeps its own warning where it cuts (with the page number) and does not repeat validate's. Test: tests/engine/b11-mem-silent6-tall.test.js.
+- **N37: repeated copies cascade.** Ctrl+D (Duplicate) and Paste put a copy 12 pt right and down, and 12 more while an item already sits there, so copying the same item again and again fans the copies out instead of stacking them on the first copy. A pasted coordinate that is not a finite number starts at 0, and the steps are bounded, so a paste of hostile JSON (`1e309`, 2^60) cannot hang the tab. Test: tests/engine/b11-mem-designer-cascade.test.js.
+
 ## 0.13.0 — 2026-10-09
 
 A minor release: new options (`largeReportRows`, `signal`, `warnOnLeave`, `onDirtyChange`), the 14 standard PDF fonts, streamed Excel and Word exports, and warnings where mistakes used to be silent. The tester's 0.12.1 tickets are fixed except where noted; fonts are still TTF (WOFF2 is not done).

package/README.md

@@ -1,9 +1,136 @@
 # @reportwright/viewer
 
+An embeddable report viewer and drag-and-drop report designer for any web page: view, page, search, drill down and export PDF, Excel, Word, PowerPoint, HTML or CSV in the browser.
+
 [![npm](https://img.shields.io/npm/v/%40reportwright%2Fviewer)](https://www.npmjs.com/package/@reportwright/viewer) [![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/MrArun005/reportwright/blob/main/LICENSE) [![Socket](https://socket.dev/api/badge/npm/package/@reportwright/viewer)](https://socket.dev/npm/package/@reportwright/viewer)
 
+**Live demo:** [mrarun005.github.io/reportwright-demo](https://mrarun005.github.io/reportwright-demo): the [gallery](https://mrarun005.github.io/reportwright-demo/#gallery) is this viewer, the [designer playground](https://mrarun005.github.io/reportwright-demo/play.html) is `mountDesigner` with your own pasted JSON or CSV, and [made by hand in the designer](https://mrarun005.github.io/reportwright-demo/learn.html) walks through building reports step by step.
+
 The ReportWright report viewer in any web app (React is bundled inside, in a shadow root, so your styles do not leak in). A React app imports `@reportwright/viewer/react-peer` (and `/react-peer/designer`) instead, the same viewer using the app's own React, so the page loads React once; `@reportwright/react` does this for you:
 
+## Install
+
+```bash
+npm i @reportwright/viewer @reportwright/fonts
+cp -r node_modules/@reportwright/fonts/public public/pw     # serve fonts/, harfbuzz-subset.wasm, icc/ as static files
+```
+
+React and React DOM 18+ are peer dependencies (the default build carries its own copy inside the shadow root; `/react-peer` uses yours).
+
+## Quick start (30 seconds, plain HTML + a bundler)
+
+```html
+<!-- index.html -->
+<div id="report" style="height: 600px"></div>
+<button id="save-pdf">Save PDF</button>
+<script type="module" src="./main.js"></script>
+```
+
+```js
+// main.js
+import { mountViewer } from '@reportwright/viewer';
+import definition from './orders.pw.json';       // the report from @reportwright/engine's README examples
+
+const viewer = mountViewer('#report', {
+  definition,
+  data: { orders: { rows: [{ customer: 'Asha Rao', amount: 1200.5 }, { customer: 'Ben Ode', amount: 80 }] } },
+  fontsUrl: '/pw/fonts/',
+});
+viewer.on('ready', ({ pages }) => console.log(`${pages} page(s)`));
+document.querySelector('#save-pdf').onclick = async () => open(URL.createObjectURL(await viewer.export('pdf')));
+```
+
+Run it with `npx vite` (Vite 7: set `worker: { format: 'es' }`, see below). Verified against this version in Chromium
+with Vite 7.
+
+## Examples
+
+**Embed the designer and keep the definition in your app.**
+
+```js
+import { mountDesigner } from '@reportwright/viewer/designer';
+const designer = mountDesigner('#designer', {
+  definition,
+  fontsUrl: '/pw/fonts/',
+  onSave: (def) => fetch('/api/reports/orders', { method: 'PUT', body: JSON.stringify(def) }),
+  toolbox: { hide: ['map'] },
+});
+designer.isDirty();        // unsaved changes?
+designer.getDefinition();  // the current definition
+```
+
+**Re-run with new parameters without remounting.**
+
+```js
+viewer.setParameters({ minAmount: 100 });
+viewer.on('parameters', (p) => history.replaceState(null, '', '?' + new URLSearchParams(p)));
+```
+
+**Trim the toolbar and show render warnings while developing.**
+
+```js
+mountViewer('#report', { definition, data, fontsUrl: '/pw/fonts/', toolbar: { hide: ['powerpoint', 'csv', 'sidebar'] }, showWarnings: true });
+```
+
+**React, Vue, Svelte, Angular:** use [`@reportwright/react`](https://github.com/MrArun005/reportwright/tree/main/packages/react), [`@reportwright/vue`](https://github.com/MrArun005/reportwright/tree/main/packages/vue),
+[`@reportwright/svelte`](https://github.com/MrArun005/reportwright/tree/main/packages/svelte) or [`@reportwright/angular`](https://github.com/MrArun005/reportwright/tree/main/packages/angular); they take the same options.
+
+## Features
+
+| Area | Viewer | Designer |
+|---|---|---|
+| Navigation | pages, thumbnails, document map, search, zoom, single / continuous / galley view | live preview |
+| Interactivity | parameters, interactive sort, drill-down, drill-through (`onDrill`, `reports`) | data panel, inspector, toolbox (each can be hidden) |
+| Export in the browser | PDF, PDF/A, Excel, Word, PowerPoint, HTML, CSV, JSON; print | the same, from the preview |
+| Embedding | shadow root (no style leaks), CSP without `'unsafe-inline'`, `nonce` | `onSave`, `onOpen`, `readOnly`, `dataSourceTemplates`, `warnOnLeave` |
+| Performance | rendering in a Web Worker; fonts fetched only when the layout needs them | |
+
+## Options reference
+
+From `dist/viewer.d.ts` and `dist/designer.d.ts`.
+
+**`mountViewer(target, options)`** → `ViewerHandle`
+
+| Option | Type | Meaning |
+|---|---|---|
+| `definition` | object | the report JSON |
+| `data` | `Record<string, unknown>` | JSON by data source name (a definition with one source also takes the JSON itself) |
+| `fontsUrl` | string | URL of the served copy of `@reportwright/fonts/public/fonts` |
+| `server`, `report`, `params` | string, string, object | a self-hosted server, a saved report id and its parameters |
+| `reports` | `Record<string, object>` | definitions by id for drill-through and subreports without a server |
+| `lang`, `title`, `height` | string | interface language, document title, element height |
+| `toolbar` | `{ hide?, add? }` | hide built-in items, add buttons (`{ id, label, title?, after?, onClick(api) }`) |
+| `viewMode` | `'single' \| 'continuous' \| 'galley'` | page layout on screen |
+| `showWarnings` | boolean | list the render's warnings under the pages |
+| `onReady` | `(error \| null) => void` | the first run ended |
+| `onDrill` | `(report, params) => void` | handle a drill-through yourself |
+| `fonts`, `customFonts`, `uiFontCss` | | extra report fonts and the interface font |
+| `snapshot` | object | show a stored run |
+| `allowHosts`, `unsafeFetch`, `fetch` | | data request guard (see below) |
+| `nonce` | string | for the fallback `<style>` under a CSP |
+
+**`mountDesigner(target, options)`** → `DesignerHandle` (`unmount`, `getDefinition`, `save`, `isDirty`): `server`,
+`fontsUrl`, `report`, `definition`, `lang`, `height`, `onSave`, `onOpen`, `readOnly`, `toolbox: { hide }`,
+`panels: { data, inspector }`, `dataSourceTemplates`, `nonce`, `allowHosts`, `unsafeFetch`, `fetch`, `warnOnLeave`
+(default `true`), `onDirtyChange`.
+
+## Browser support and limits
+
+- Modern evergreen browsers with ES modules, Web Workers and constructable stylesheets (an older browser without the
+  last gets a `<style>` element). Node 20.9+ for the build tooling (`engines`).
+- Without the worker (a bundler that does not copy it) the report renders on the main thread: it works, but large
+  reports make the page janky.
+- Sorted or grouped exports in the browser hold every row in memory (about 1.3 KB a row measured): keep them under
+  about 100,000 rows, or render on the server with [`@reportwright/engine`](https://github.com/MrArun005/reportwright/tree/main/packages/engine).
+- A browser cannot resolve DNS, so the private-address guard cannot catch a public name that points at a private
+  address (see [Data sources and private addresses](#data-sources-and-private-addresses)).
+
+## Related packages
+
+[`@reportwright/engine`](https://github.com/MrArun005/reportwright/tree/main/packages/engine) (the same rendering in Node), [`@reportwright/fonts`](https://github.com/MrArun005/reportwright/tree/main/packages/fonts) (required),
+[`@reportwright/fonts-cjk`](https://github.com/MrArun005/reportwright/tree/main/packages/fonts-cjk), [`@reportwright/cli`](https://github.com/MrArun005/reportwright/tree/main/packages/cli), and the wrappers
+[`react`](https://github.com/MrArun005/reportwright/tree/main/packages/react), [`vue`](https://github.com/MrArun005/reportwright/tree/main/packages/vue), [`svelte`](https://github.com/MrArun005/reportwright/tree/main/packages/svelte), [`angular`](https://github.com/MrArun005/reportwright/tree/main/packages/angular).
+
 ## Bundler setup (read this first)
 
 The viewer renders in a Web Worker (`engine.worker.js`, one self-contained file next to the viewer). Bundlers that understand
@@ -11,8 +138,10 @@ The viewer renders in a Web Worker (`engine.worker.js`, one self-contained file
 
 - **Vite 7**: set `worker: { format: 'es' }` in `vite.config.js`. Without it the build fails with
   `Invalid value "iife" for option "worker.format"`.
-- **esbuild** (plain bundling) does not follow `new Worker(new URL(...))`: copy `node_modules/@reportwright/viewer/dist/engine.worker.js`
-  next to your bundle (it is one file; its only imports are the package's own dependencies).
+- **esbuild** (plain bundling) does not follow `new Worker(new URL(...))`: copy the worker files next to your bundle:
+  `cp node_modules/@reportwright/viewer/dist/engine.worker*.js dist/`. `engine.worker.js` has no imports (its libraries are
+  inside it); `engine.worker.bwip.js` (barcodes) loads only when a report
+  needs it. Without it those reports render on the main thread, with the warning below.
 
 If the worker cannot load, the viewer still renders, on the main thread (slow and janky at 100k rows), and logs once
 `[reportwright] worker did not load (<reason>); rendering on the main thread`. `handle.usesWorker` tells you which one you got.
@@ -136,11 +265,11 @@ Types are included (`ViewerOptions`, `DesignerOptions`, …). Framework wrappers
 
 ### Viewer toolbar: `toolbar.hide`
 
-`toolbar: { hide: [...], add: [...] }` hides built-in items. A group key hides the whole group; an item id hides that one item. Hiding every export format also hides the Export menu and its options gear.
+`toolbar: { hide: [...], add: [...] }` hides built-in items. A group key hides the whole group; an item id hides that one item. Hiding every export format also hides the Export menu and its Export options button.
 
 | Key | Hides |
 |---|---|
-| `export` | the Export menu: every format and the options gear (Print stays) |
+| `export` | the Export menu: every format and the Export options button (Print stays) |
 | `pdf`, `excel`, `word`, `powerpoint`, `html`, `csv`, `json` | that one export format |
 | `print` | the Print button |
 | `search` | the search box and its match controls |
@@ -149,10 +278,18 @@ Types are included (`ViewerOptions`, `DesignerOptions`, …). Framework wrappers
 | `sidebar` | the page thumbnails and the document map buttons |
 | `parameters` | the Parameters button |
 | `run`, `viewMode`, `fullScreen`, `stats` | those single items (use their id) |
-| `exportOptions` | the options gear (the formats stay) |
+| `exportOptions` | the Export options button (the formats stay) |
 
 Any other key is taken as an item id. Unknown keys hide nothing.
 
+### Render warnings: `showWarnings`
+
+`showWarnings: true` shows the render's warnings (a data value that does not read as a number, an unknown field, content cut off at the page edge…) under the pages, as a collapsed list headed "8 warnings" or "1 warning". The default is `false`: readers of a finished report do not see them. The designer's Preview always shows them.
+
+```js
+mountViewer('#report', { definition, data, fontsUrl: '/fonts/', showWarnings: true });
+```
+
 ### Controlling a mounted viewer: `ViewerHandle`
 
 `mountViewer` returns a handle (the React, Vue, Svelte and Angular wrappers give you the same one through their ready callback or event):
@@ -165,15 +302,21 @@ Any other key is taken as an item id. Unknown keys hide nothing.
 | `getPageCount()` | the page count of the last run (0 before the first) |
 | `print()` | opens the print dialog for the PDF |
 | `export(format)` | `Promise<Blob>`: `format` is `pdf`, `xlsx`, `docx`, `pptx`, `html`, `csv` or `json` (or the item ids `excel`, `word`, `powerpoint`) |
-| `on(event, fn)` | listens for `ready` (a run finished, detail: page count), `error` (detail: message), `page` (detail: current page), `parameters` (detail: the parameters); returns an unsubscribe function |
+| `on(event, fn)` | listens for `ready` (a run finished, detail: `{ pages }`), `error` (detail: message), `page` (detail: current page), `parameters` (detail: the parameters); returns an unsubscribe function |
 | `unmount()` | removes the viewer |
 
 ```js
 const viewer = mountViewer('#report', { server, report: 'loan-statement' });
 viewer.setParameters({ accountId: 'LN-2' });      // re-runs; 'ready' fires when it is done
-const pdf = await viewer.export('pdf');           // a Blob
+document.querySelector('#save-pdf').onclick = async () => {
+  const pdf = await viewer.export('pdf');         // a Blob of the report as shown
+  open(URL.createObjectURL(pdf));
+};
 ```
 
+`export()` exports the last finished run. `ready` fires once that run is on screen, so calling `export()` inside a
+`ready` listener (or `onReady`) works.
+
 ## Size
 
 What a page downloads when the viewer mounts: **847 KB gzipped** (0.7.3: 877 KB), readable unminified code with

package/THIRD-PARTY-NOTICES.md

@@ -9,7 +9,7 @@ ReportWright is MIT licensed (see LICENSE). It ships or bundles the following th
 | [HarfBuzz](https://github.com/harfbuzz/harfbuzz), compiled to WebAssembly by [harfbuzzjs](https://github.com/harfbuzz/harfbuzzjs) | harfbuzzjs 1.6.2 | HarfBuzz: "Old MIT" (below); harfbuzzjs: MIT, Copyright (c) 2019-2026 The harfbuzzjs project authors | text shaping (`harfbuzz.wasm`) and font subsetting (`harfbuzz-subset.wasm`) |
 | [pdf-lib](https://github.com/Hopding/pdf-lib) | 1.17.1 | MIT, Copyright (c) 2019 Andrew Dillon | the classic PDF writer (encryption, `prepare`, `save`) |
 | [@pdf-lib/fontkit](https://github.com/Hopding/fontkit) | 1.1.1 | MIT | reading font files |
-| [@pdf-lib/standard-fonts](https://github.com/Hopding/standard-fonts) | 1.0.0 | MIT; the metrics are Adobe's AFM files for the 14 standard PDF fonts | Helvetica, Times and Courier widths |
+| [@pdf-lib/standard-fonts](https://github.com/Hopding/standard-fonts) | 1.0.0 | MIT; the metrics are Adobe's AFM files for the 14 standard PDF fonts | Helvetica, Times and Courier widths: generated from its AFM data into src/engine/text/standard-metrics.js (scripts/gen-standard-metrics.mjs); the package itself is not a runtime dependency |
 | [bwip-js](https://github.com/metafloor/bwip-js) | 4.11.4 | MIT | barcodes |
 | [fflate](https://github.com/101arrowz/fflate) | 0.8.3 | MIT | zip and deflate (Excel, Word, PowerPoint, PDF streams) |
 | [bidi-js](https://github.com/lojjic/bidi-js) | 1.0.3 | MIT | right-to-left text |