@reportwright/engine 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,18 +1,28 @@
 # @reportwright/engine
 
+Turn a JSON report definition and your data into paged PDF, Excel, Word, PowerPoint, HTML or CSV, in Node or the browser, with no Chromium.
+
 [![npm](https://img.shields.io/npm/v/%40reportwright%2Fengine)](https://www.npmjs.com/package/@reportwright/engine) [![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/engine)](https://socket.dev/npm/package/@reportwright/engine)
 
-The ReportWright report engine for Node and browsers: a JSON report definition and data in, pages out, then PDF (also PDF/A-2b), Word, Excel, PowerPoint (exportPptx), HTML or CSV. The command line is `@reportwright/cli` (`pw`).
+**Live demo:** [mrarun005.github.io/reportwright-demo](https://mrarun005.github.io/reportwright-demo) (the [live gallery](https://mrarun005.github.io/reportwright-demo/#gallery) renders real definitions with this engine; [benchmarks](https://mrarun005.github.io/reportwright-demo/bench.html) compares it with pdfmake, react-pdf, PDFKit and Puppeteer on the same reports).
+
+The engine lays out pages from a definition (bands, tables with groups, matrices, charts, barcodes, subreports) and the exporters write the files. The command line is [`@reportwright/cli`](https://github.com/MrArun005/reportwright/tree/main/packages/cli) (`pw`); the in-browser viewer and designer are [`@reportwright/viewer`](https://github.com/MrArun005/reportwright/tree/main/packages/viewer).
+
+## Install
 
 ```bash
 npm i @reportwright/engine @reportwright/fonts
 ```
 
+`@reportwright/fonts` is a peer dependency: it holds the fonts, the HarfBuzz text shaper, the PDF font subsetter and the PDF/A colour profile.
+
+## Quick start (30 seconds)
+
 Save this as `statement.pw.json` (a minimal report; the repository's `examples/` has more):
 
 ```json
 {
-  "$schema": "pagewright/report@1",
+  "$schema": "reportwright/report@1",
   "name": "Statement",
   "page": { "size": "A4", "margins": [36, 36, 36, 36] },
   "parameters": [{ "name": "accountId", "type": "string" }],
@@ -30,6 +40,7 @@ Save this as `statement.pw.json` (a minimal report; the repository's `examples/`
 ```
 
 ```js
+// render.mjs: node render.mjs
 import { render, defaultFontStore, exportPdf } from '@reportwright/engine';
 import fs from 'node:fs';
 // the fonts, the text shaper (Arabic, Hebrew, Indic, Thai…) and the PDF subsetter come from @reportwright/fonts;
@@ -46,6 +57,179 @@ const bundledFonts = defaultFontStore({ fontsUrl: '/pw/fonts/' }); // a missing
 // only when asked: render(def, { exportData: true }) (needsExportData(format) says which formats need it)
 ```
 
+## Examples
+
+Every example below was run against this version in Node 20. They use this report, `orders.pw.json`: a title and a
+table of customers and amounts with a total (it is `examples/report.pw.json` in the repository):
+
+```json
+{
+  "$schema": "reportwright/report@1",
+  "name": "Orders",
+  "page": { "size": "A4", "margins": [36, 36, 36, 36] },
+  "dataSources": [{ "name": "orders", "type": "json", "data": { "rows": [] } }],
+  "dataSets": [{ "name": "Lines", "source": "orders", "path": "$.rows" }],
+  "sections": { "body": { "items": [
+    { "type": "textbox", "name": "Title", "x": 0, "y": 0, "w": 300, "h": 24, "value": "Orders", "style": { "fontSize": 18, "fontWeight": "bold" } },
+    { "type": "table", "name": "Table", "x": 0, "y": 40, "w": 400, "h": 60, "dataSet": "Lines",
+      "columns": [{ "width": 250 }, { "width": 150 }],
+      "header": [{ "height": 18, "cells": [{ "value": "Customer" }, { "value": "Amount", "style": { "textAlign": "right" } }] }],
+      "detail": [{ "height": 18, "cells": [{ "value": "=Fields.customer" }, { "value": "=Fields.amount", "style": { "format": "C2", "textAlign": "right" } }] }],
+      "footer": [{ "height": 18, "cells": [{ "value": "Total" }, { "value": "=Sum(Fields.amount)", "style": { "format": "C2", "textAlign": "right", "fontWeight": "bold" } }] }] }
+  ] } }
+}
+```
+
+### 1. Bind your own data, then write PDF, Excel, Word, PowerPoint, HTML and CSV
+
+`sources` replaces a data source's data by name. The data set reads `$.rows`, so the JSON has a `rows` array; a
+mismatch gives an empty table, not an error.
+
+```js
+import fs from 'node:fs';
+import { render, defaultFontStore, validate, exportPdf, exportXlsx, exportDocx, exportPptx, exportHtml, exportCsv } from '@reportwright/engine';
+
+const def = JSON.parse(fs.readFileSync('orders.pw.json', 'utf8'));
+const orders = { rows: [{ customer: 'Asha Rao', amount: 1200.5 }, { customer: 'Ben Ode', amount: 80 }] };
+
+const { errors } = validate(def);                 // { errors, warnings, exprErrors, checkOnly }
+if (errors.length) throw new Error(errors.join('\n'));
+
+const fonts = defaultFontStore();
+const model = await render(def, { fontStore: fonts, sources: { orders }, exportData: true });
+fs.writeFileSync('orders.pdf', await exportPdf(model, { fonts, title: 'Orders' }));
+fs.writeFileSync('orders.xlsx', await exportXlsx(model, { fonts }));
+fs.writeFileSync('orders.docx', await exportDocx(model, { fonts }));
+fs.writeFileSync('orders.pptx', await exportPptx(model, { fonts }));
+fs.writeFileSync('orders.html', await exportHtml(model, { fonts, title: 'Orders' }));
+fs.writeFileSync('orders.csv', exportCsv(model));  // Customer,Amount / Asha Rao,1200.5 / Ben Ode,80
+```
+
+### 2. Parameters and a filter
+
+```js
+def.parameters = [{ name: 'minAmount', type: 'float', default: 0 }];
+def.dataSets[0].filters = [{ expr: '=Fields.amount', op: '>=', value: '=Parameters.minAmount' }];
+def.sections.body.items[0].value = '="Orders over " & Parameters.minAmount';
+
+const model = await render(def, { fontStore: fonts, sources: { orders }, parameters: { minAmount: 100 } });
+// one row (Asha Rao) under the title "Orders over 100"
+```
+
+### 3. Archival and accessible PDF
+
+```js
+const model = await render(def, { fontStore: fonts, sources: { orders }, exportData: true });
+fs.writeFileSync('orders-pdfa.pdf', await exportPdf(model, { fonts, pdfa: true })); // PDF/A-2b, sRGB profile from @reportwright/fonts
+```
+
+From the command line, `pw render orders.pw.json --pdfa --ua` writes PDF/A-2a with PDF/UA-1 tagging.
+
+### 4. Stream a large report to a file
+
+```js
+import { exportPdfStream } from '@reportwright/engine';
+const out = fs.createWriteStream('orders.pdf');
+const r = await exportPdfStream(def, { sources: { orders }, title: 'Orders' }, out);
+out.end();
+console.log(r.streamed, r.pages);                  // true 1
+```
+
+Details, memory figures and what streams are under [Streaming PDF for large reports](#streaming-pdf-for-large-reports).
+
+### 5. Many reports in parallel (Node worker pool)
+
+```js
+import { createPool } from '@reportwright/engine/pool';
+const pool = createPool({ workers: 2 });
+const pdf = await pool.render(def, { format: 'pdf' }); // Uint8Array
+await pool.close();
+```
+
+## Features
+
+| Area | What the engine does |
+|---|---|
+| Layout | Page header and footer, body bands, absolutely placed items; tables with groups, subtotals, keep-together and page breaks; matrices (pivot); lists; subreports (nested up to 3 levels) |
+| Items | Text and rich text, images, lines and shapes, charts (incl. sparklines and data bars), barcodes, maps |
+| Expressions | `=Fields.x`, `=Parameters.x`, aggregates (`Sum`, `Count`, `Avg`, `Min`, `Max`, `CountRows()`), `RowNumber()`, lookups; an expression that does not parse draws `#Error` with a warning |
+| Data | Inline JSON, `sources` passed to `render()`, REST, GraphQL, SOAP, OData, CSV, XML; SQL through your own `sql` / `sqlRows` callback |
+| Text | HarfBuzz shaping (Arabic, Hebrew, Indic, Thai), bidi; CJK and emoji with [`@reportwright/fonts-cjk`](https://github.com/MrArun005/reportwright/tree/main/packages/fonts-cjk) |
+| PDF | Font subsetting, PDF/A-2b, PDF/A-2a and PDF/UA-1 (validated with veraPDF), AES-256 passwords and permissions |
+| Scale | Streaming PDF, Word and Excel export; disk-spilling sort; worker pool and opt-in worker threads |
+| Safety | SSRF guard on data fetches, per-fetch time and size limits, render `timeoutMs`, misspelled options reported |
+
+## Supported formats
+
+| Direction | Formats |
+|---|---|
+| Export | PDF (`exportPdf`, `exportPdfStream`), PDF/A-2b and PDF/A-2a, PDF/UA-1, Excel `.xlsx` (`exportXlsx`, `exportXlsxStream`), Word `.docx` (`exportDocx`, `exportDocxStream`), PowerPoint `.pptx` (`exportPptx`), HTML (`exportHtml`, with a sortable Tables view unless `static`), CSV (`exportCsv`), SVG per page (`pageToSvg`) |
+| Import | JasperReports `.jrxml`, SSRS `.rdl` / `.rdlc`, BIRT `.rptdesign`, ActiveReports `.rdlx-json`: with `pw import` in [`@reportwright/cli`](https://github.com/MrArun005/reportwright/tree/main/packages/cli) |
+
+## Options reference
+
+From the package's types (`index.d.ts`); the JSDoc in `dist/` has every option.
+
+**`render(definition, options)`** → page model
+
+| Option | Meaning |
+|---|---|
+| `fontStore` | the `FontStore`; share one across renders |
+| `parameters` | report parameter values by name (invariant form: `1234.5`, `2026-03-05`) |
+| `sources` | data already loaded, by data source name (skips loading them) |
+| `exportData` | keep the table data Excel, CSV, Word, interactive HTML and accessible PDF need |
+| `now`, `timeZone` | the render's clock and the zone dates show in |
+| `fetch`, `baseUrl`, `allowHosts`, `unsafeFetch` | how data requests are made (see the network notes below) |
+| `fetchTimeoutMs`, `maxFetchBytes` | per-fetch limits (30 s, 64 MB) |
+| `sql`, `loadReport` | callbacks for SQL sources and for subreports / masters by id |
+| `timeoutMs`, `deadline` | stop with status 504 when the render runs longer |
+| `largeReportRows` | rows past which a data set warns (100,000; `0` or `false` turns it off) |
+
+**`exportPdf(model, options)`** → `Uint8Array`: `fonts`, `title`, `subset` (`false` embeds full fonts), `pdfa`
+(`true` or `{ icc }`), `tagged`, `encrypt`, `onWarning`, `timeoutMs`.
+
+**`exportXlsx` / `exportDocx` / `exportPptx(model, options)`** → `Promise<Uint8Array>`: `fonts`, plus `currency` and
+`formulas` for Excel.
+
+**`exportHtml(model, options)`**: `fonts`, `title`, `static`, `locale`, `currency`, `lang`, `timeoutMs`.
+**`exportCsv(model, options)`**: `all`, `layout` (the printed layout instead of the data), `locale`, `currency`.
+
+**`exportPdfStream` / `exportDocxStream` / `exportXlsxStream(definition, options, sink)`**: `render()`'s and
+`exportPdf`'s options plus `window`, `maxRows`, `presorted`, `spill`, `parallel`, `signal`, `sqlRows`.
+
+Other exports: `validate`, `blankReport`, `blankDashboard`, `FontStore`, `fontFile`, `defaultFontStore`,
+`needsExportData`, `parameterOptions`, `resolveParameters`, `createSubsetter`, `pageToSvg`. Types for the definition
+format: `import type { Report } from '@reportwright/engine/report'`; JSON Schema: `@reportwright/engine/schema.json`.
+
+## Runtime support
+
+- **Node** 20.9 or later (`engines`). The SSRF guard pins the checked address on Node 20.16+ / 22.3+.
+- **Browsers**: the package is ES modules built for ES2022, for modern evergreen browsers through a bundler. In a
+  browser, pass `defaultFontStore({ fontsUrl })` (see the quick start). Sorted or grouped exports hold their rows in
+  memory there (keep them under about 100,000 rows).
+
+## Limits
+
+| Limit | Default | Option |
+|---|---|---|
+| Rows read by a streamed export | 5,000,000 | `maxRows` |
+| Time per data fetch | 30 s | `fetchTimeoutMs` |
+| Size per data fetch (decoded) | 64 MB | `maxFetchBytes` |
+| Redirects per fetch | 5 | none |
+| Subreport nesting | 3 levels | none |
+| Disk used by a spilled sort | 2 GB | `spill: { maxMB }` |
+| Warning threshold for a large data set | 100,000 rows | `largeReportRows` |
+
+## Related packages
+
+| Package | What it is |
+|---|---|
+| [`@reportwright/fonts`](https://github.com/MrArun005/reportwright/tree/main/packages/fonts) | fonts, shaper, subsetter and colour profile (required) |
+| [`@reportwright/fonts-cjk`](https://github.com/MrArun005/reportwright/tree/main/packages/fonts-cjk) | optional Chinese, Japanese, Korean and emoji fonts |
+| [`@reportwright/cli`](https://github.com/MrArun005/reportwright/tree/main/packages/cli) | `pw`: render, test, diff and import reports from the command line |
+| [`@reportwright/viewer`](https://github.com/MrArun005/reportwright/tree/main/packages/viewer) | the in-browser viewer and designer |
+| [`@reportwright/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) | framework wrappers for the viewer and designer |
+
 ## Implicit behaviour, and how to switch it
 
 - **ISO dates.** When a data set has no `fields`, they are detected from the rows, and a string that looks like an ISO
@@ -170,11 +354,16 @@ and stays in memory for the export: the export's own memory stays flat beside it
 many.
 
 - **Sorts and groups.** A table sort or groups put the rows in order first. In Node the sort spills to the system temp
-  folder (`spill: { dir, maxMB }`; 2 GB at most), so memory stays flat; `spill: false`, and in a
-  browser, it is in memory (all the rows: measured about 1.3 KB a row, so keep browser exports under about 100,000 sorted or
-  grouped rows). When the source already gives the rows in the report's order (`order by region, type` for groups by
-  region then type), pass `presorted: true`: nothing is sorted or held, each row is checked against the one before as it
-  passes, and a row out of order stops the export with an error.
+  folder (`spill: { dir, maxMB, runMB, mergeMB }`; 2 GB of disk at most; `runMB` (default 8) and `mergeMB` (default 4) set the memory), so memory stays flat: the sort holds about 8 MB of rows while reading
+  and 4 MB while merging, whatever the row count (past that many sorted runs, groups of them are merged on disk first).
+  `spill: false`, and in a browser, it is in memory (all the rows: measured about 1.3 KB a row, so keep browser exports
+  under about 100,000 sorted or grouped rows).
+- **Big grouped reports: sort at the source.** When the source already gives the rows in the report's order (`ORDER BY
+  region, type` for groups by region then type), pass `presorted: true`: nothing is sorted or held, each row is checked
+  against the one before as it passes, and a row out of order stops the export with an error. It is the cheapest way to
+  a large grouped report: a tester's 1,000,000-row grouped ledger (0.13.0, Node 22, 2 vCPU Linux) peaked at 293 MB
+  presorted and 386 MB sorted by the engine; the engine's sort holds less since 0.13.1, but it still reads and writes
+  every row to disk once more.
 - **parallel: N** (Node, off by default) lays out and paints with N worker threads; the file is byte for byte the same.
   Each thread loads the engine and fonts and lays out its own windows: about 150–300 MB a thread (measured: 260 MB
   serial, 590 MB with 2, 890 MB with 4, for 100,000 rows). It helps only with idle cores and a report whose layout, not

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 |