@reportwright/engine 0.0.0-stage → 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+All `@reportwright/*` packages (formerly `@pagewrightjs/*`) share one version. The versioning policy is in [CONTRIBUTING.md](CONTRIBUTING.md#versioning-semver).
+
+## 0.11.0 — 2026-10-08
+
+Everything since 0.10.0. Items marked **Behaviour change** alter output that a pixel-locked layout or a locale-sensitive
+export may depend on: check them before you upgrade.
+
+### Behaviour changes
+- **Numbers and dates shrink instead of wrapping.** An amount inside a text box shrinks like a number, a short code or a
+  header word shrinks before it breaks inside (`Amou|nt`, `m0|2`), and a short text shrinks before it is cut with `…`
+  or wraps alone in a one-line box. Reports that relied on the old wrap need a wider box or `shrinkToFit: false`.
+- **Widow control is on by default** for every group: a heading or a lone row no longer ends a page. `widowControl: false`
+  turns it off. Page counts can change for reports that break inside groups.
+- **A group taller than a page splits** with at least two rows on each side of the break, so no lone row sits at a page
+  foot or head. A keep-together block no longer leaves a blank page.
+- **Sideways tables spread their column sets evenly** over the pages they need (a balanced split, not a long last page).
+- **Number grouping follows Intl by default** (es-ES shows `1234,50`). The report option `grouping` is `always` or
+  `never`. Unformatted numbers use a Latin decimal sign with Latin digits (ar-SA).
+- **Page size names are forgiving.** `"a4 "` and `"letter"` resolve to A4 and Letter. An unknown size (`"A44"`) still
+  falls back to A4 with a warning and a suggestion.
+- **Data bars:** a value label sits after the bar when it fits, else inside it, right-aligned, in a contrasting ink.
+  Negative values draw from a zero line in `negativeColor` (default red); positive-only columns are unchanged.
+- **Charts:** column category labels turn (-45) when they do not fit flat, instead of dropping every other label. Scatter
+  and bubble axes pad the automatic range so the largest point is not on the frame. `outliers: clip | none` decides what
+  happens to points past an explicit axis min or max; clipped points get a ring and a warning. A scatter or bubble row
+  with no x or y is no longer drawn at 0 (one warning counts them).
+- **Fetched CSV, XML and JSON** read the response charset (ISO-8859-1, windows-1252, ...); UTF-8 is the default and a BOM
+  is stripped.
+- **Fetch is SSRF-guarded by default:** http(s) only, private and local addresses refused in every spelling, DNS checked
+  in Node, each redirect re-checked, parameters fill the path and query only. `allowHosts` and `unsafeFetch` opt out.
+- **Expressions read own members only:** `constructor`, `__proto__` and other inherited names give `#Error`.
+- **Data fetch errors** name the cause (DNS, refused, reset, TLS, timeout) and redact the URL (query shown as `?…`, no
+  userinfo, no keys or tokens).
+- **Charts and barcodes get generated alt text** (type, title, series, categories; symbology and value) when the author
+  sets none. The author's alt text always wins.
+- **Subreport report ids** may use capitals and underscores (still no `/`, `\`, `.` or `..`).
+- **Deterministic output:** structure tag ids come from the render's counter, so two renders give one model.
+  `exportPdf` takes `creationDate`, or `SOURCE_DATE_EPOCH`; then the dates are UTC and the document ID derives from the
+  content.
+- **PDF images that cannot be embedded** (GIF, WebP, undecodable, a URL with no `fetchImage`, too large) are left out
+  with a warning that names the picture and the reason. A cut or damaged PNG is checked and left out instead of hanging.
+
+### Added
+- **Vercel hosting.** `GET /api/v1/cron` runs the schedule tick and the batch queue when `CRON_SECRET` (16+ characters) is set, with `Authorization: Bearer $CRON_SECRET`; without it the route answers 404. `vercel.json` runs it daily. On Vercel, a queued batch runs after its response.
+- `PW_STORAGE` falls back to `DATABASE_URL` when unset, on Vercel or with `PW_STORAGE_FROM_DATABASE_URL=1` only (documented in docs/CONFIG.md).
+- **Designer: Import report** (File group) reads `.jrxml`, `.rdl`, `.rdlc`, `.rptdesign` and `.json` definitions through
+  the importers, and shows the importer's warnings. The CLI (`pw import`) does the same.
+- **ViewerHandle:** `setParameters`, `setDefinition`, `goToPage`, `getPageCount`, `print`, `export` (Blob), and `on(ready |
+  error | page | parameters)`. The React ref gets the handle. Documented in the viewer README.
+- **validate()** warns about unknown format codes (`N2x`), colour names (`redd`), named styles, sort entries not shaped
+  `{by, dir}`, date defaults that are not dates, charts with no series, local image paths, and unknown or padded page
+  sizes. Each warning has a did-you-mean where one exists.
+- **Word export:** heading items are Heading 1 to 6 paragraphs, and the document language is the report locale by default
+  (`lang` still wins).
+- **Tagged PDF:** link annotations say the link's visible text, else its tooltip, else its URL.
+- **PDF drill-through links** open the viewer with their parameters (a URI when the base URL is known). URIs are ASCII,
+  the outline holds headings and nests group bookmarks, and every PDF has page labels.
+- **Types:** `render()` takes a `RenderOptions` type. Sort entries are `{by, dir}` (`SortSpec`) on data sets, tables and
+  lists. `report.d.ts` is regenerated.
+- **Strict CSP:** the viewer and the Designer run under `style-src 'self'` with no style element and no style attribute
+  written by the engine. See the viewer README.
+- **Fonts:** `defaultFontStore({ fontsUrl })` reads a copied fonts folder in bundled apps. A font that does not load is named
+  on screen and `onReady` reports it. Faces load lazily, only those a report uses; a face that fails to load falls back to a
+  bundled face with a warning.
+
+### Changed
+- **Designer accessibility:** Inspector section headings are real buttons (Enter and Space toggle them). Chart gallery
+  choices are named by the chart type alone. The Designer's embedded font rules go through a constructable stylesheet.
+- **Viewer export menu:** each format is named by its format ("PDF document"), with the badge hidden from screen readers.
+- **Toolbar:** `toolbar.hide` takes group keys (`export`, `search`, `zoom`, `navigation`), `sidebar`, and every format id.
+  No Export gear when no format is left.
+- **Optional CJK and emoji faces** do not add a font warning; their own `NO_CJK_FONTS` warning covers them.
+
+### Fixed
+- Subreport ids and render warnings: a render's warning list holds each message once, and a barcode warning names an
+  unnamed item by place instead of `undefined`.
+- Text with objects, arrays or large numbers from data prints as data, not `[object Object]` or `1e+21`.
+- Decimal sums stay exact above 2^49.
+- Designer seq fields format as codes (no decimals, no grouping).
+- Tables take column widths from the content (`fitColumns`, and columns with no width).
+- Styles that are not objects (`"bold"`) are ignored with a validate() warning instead of crashing the render.
+- Expression and render guards: a traversal subreport id or a parameter value like `../x` is refused before `loadReport`.
+- Server renders: image URLs never reach internal hosts, dev mode included.
+- Vite bundles no longer warn 'cannot be analyzed' for the Node-only sharp import.
+
+## 0.10.0
+
+Streaming exports and a pool that uses every core. No change to rendering, totals or page counts. Design and measurements:
+[docs/research/STREAMING-1M.md](docs/research/STREAMING-1M.md).
+
+### Added
+- **Streaming data CSV and Excel.** A report with one table and row-by-row expressions (group and table footers may
+  total with Sum, Count, Avg, Min, Max or CountRows) exports as it reads: rows come from the source a batch at a time
+  (JSON arrays split from the byte stream, CSV, SQLite, PostgreSQL and MySQL cursors), are sorted and grouped through
+  temporary files when needed, and are written to the response with back-pressure. Memory stays flat: 100k → 300k rows
+  measured 160 → 168 MB for a CSV render, 185 → 197 MB for a grouped Excel one (the whole render process); 1M rows
+  projects under 300 MB. Same bytes as before for CSV, same cells and formulas for Excel. Other reports take the page
+  model as before. The answer has no `content-length`; a failure after the first bytes breaks the download off (CSV:
+  a last line `#ERROR <reference>`). Settings: `PW_STREAM`, `PW_STREAM_MAX_ROWS`, `PW_STREAM_FETCH_MAX_MB`,
+  `PW_STREAM_SQL_MAX_MB`, `PW_SPILL_MAX_MB`, `PW_SPILL_TOTAL_MB`, `PW_STREAM_STALL_MS`.
+- Excel tables longer than 1,048,576 rows continue on a sheet "Name (2)" with their header rows again.
+- `@reportwright/engine/pool`: `createPool({ heapMB, timeoutMs })`.
+
+### Changed
+- The server's render pool has a worker per core (less one, at most 16); memory decides what runs at once, by an
+  estimate per template and caller, with small heaps for small and streaming renders (`PW_RENDER_SMALL_HEAP_MB`) and
+  a cap on one caller's running renders (`PW_RENDER_RUNNING_PER_PRINCIPAL`). `UV_THREADPOOL_SIZE` follows the cores
+  (Dockerfile, cluster.mjs).
+- Excel: a plain cell no longer carries a duplicate style; the no-table CSV starts with a BOM like the others.
+
+### Fixed
+- SQLite sources: a reused query process failed every second query ("statement has been finalized").
+
+## 0.9.0
+
+Pagewright is now **ReportWright** (formerly Pagewright). No change to rendering, totals or page counts.
+
+### Changed
+- The npm packages moved to the `@reportwright` scope: `@reportwright/engine`, `/viewer`, `/fonts`, `/fonts-cjk`,
+  `/cli`, `/react`, `/vue`, `/svelte`, `/angular`. The `@pagewrightjs/*` packages are deprecated and get no updates.
+  Change the package names in your `package.json` and imports; nothing else.
+- The brand in the app, the Designer, the viewer, mails, the 9 interface languages, the CLI, error messages and
+  exports (the PDF Producer and Creator, HTML titles) reads ReportWright.
+- The CLI installs as `reportwright` and still as `pw`; the CJK font downloader as `reportwright-fonts-cjk` (and
+  `pagewright-fonts-cjk`).
+- The repository is `github.com/MrArun005/reportwright` (the old URL redirects).
+
+### Deprecated (removed in 1.0)
+- `<pagewright-viewer>` and `<pagewright-designer>` (now `<reportwright-viewer>`, `<reportwright-designer>`; both are
+  registered), `definePagewrightElements` (now `defineReportWrightElements`), `PagewrightViewer` and
+  `PagewrightDesigner` in React and Vue (now `ReportWrightViewer`, `ReportWrightDesigner`), `pagewrightViewer` and
+  `pagewrightDesigner` in Svelte (now `reportWrightViewer`, `reportWrightDesigner`), `window.Pagewright` (now
+  `window.ReportWright`) and `/embed/pagewright-viewer.js` (now `/embed/reportwright-viewer.js`). Each old name is
+  an alias of the new one.
+
+### Kept (so deployments and stored data keep working)
+- Settings keep the `PW_` prefix. The `x-pagewright-*` headers, the `pagewright_*` metrics, cookie and storage table
+  names, the `.pw.json` extension and `"$schema": "pagewright/report@1"` are unchanged; `reportwright/report@1` is
+  accepted as the same format.
+
+## 0.8.1
+
+Supply-chain hardening (what Socket.dev and similar scanners read). No change to rendering or exports.
+
+### Changed
+- `@pagewrightjs/viewer` no longer bundles pdf-lib, @pdf-lib/fontkit, bwip-js, fflate or bidi-js: they are
+  dependencies pinned to exact versions, as in the engine. Import the viewer through a bundler (Vite, webpack,
+  esbuild, Rollup…). Unpacked size 14.8 MB to 10.1 MB.
+- The engine and the CLI import bidi-js too (a pinned dependency) instead of bundling its Unicode tables.
+- `@pagewrightjs/cli` holds the report commands only (render, test, diff, import): no server modules, no
+  `child_process`, no environment reads. `pw audit` and `pw migrate-storage` run from the app (`node bin/pw.mjs`).
+- No line over 1,000 characters in any package (source maps aside).
+- `render(def, { fetch })` is the documented way to give the engine its network access; `globalThis.fetch` is only
+  the fallback, and the error without either says so.
+- `@pagewrightjs/fonts` ships a LICENSE file.
+
+### Added
+- `npm run scan:packages` (`scripts/scan-packages.mjs`): a Socket-style scan of every packed package, run in CI and
+  before publishing. Release steps: [docs/RELEASING.md](docs/RELEASING.md).
+
+## 0.8.0
+
+### Breaking (with a deprecation period)
+- One export signature: `exportPdf(model, { fonts, ... })`, `exportXlsx(model, { fonts, ... })`,
+  `exportDocx(model, { fonts, ... })`, `exportPptx(model, { fonts, ... })`. The 0.7 positional forms
+  (`exportPdf(model, fontStore, opt)`, `exportXlsx(model, ExcelJS, opt)`) still work in 0.8 and print one deprecation
+  warning; they are removed in 0.9. A wrong argument gives a `TypeError` that says what was expected.
+- A table cell under another cell's `colSpan` is no longer drawn on top of it (validate() warns about it).
+
+### Added
+- The viewer works without a server: `mountViewer(el, { definition, data, fontsUrl })` (also in the React, Vue,
+  Svelte and Angular wrappers). The README says what works standalone and what needs the self-hosted server.
+- `colSpan` in RDL/HTML style: a row with fewer cells than columns omits the spanned cells.
+- The report JSON Schema, published as `@pagewrightjs/engine/schema.json`; `report.d.ts` is generated from it and
+  `validate()` checks properties and choices against it (the hand-written types and the validator had drifted apart: `dir`, `alt` and about 30 engine properties were missing from one or the other).
+- `pdfa: true` finds the sRGB colour profile in `@pagewrightjs/fonts` by itself.
+- `@pagewrightjs/fonts-cjk`: Chinese, Japanese, Korean and emoji fonts, downloaded on demand
+  (`npx pagewright-fonts-cjk`), pinned and checked by SHA-256.
+- `createPool({ workers })` in `@pagewrightjs/engine/pool`: renders on worker threads (4 workers: 2.8× one).
+- `detectDates: false` on a data set; `colorByCategory: true` on charts (one colour per category across charts).
+- `pw import report.jrxml` (also .rdl and .rptdesign) in `@pagewrightjs/cli`.
+- Docs: docs/QUICKSTART.md, docs/SCHEMA.md and docs/FUNCTIONS.md (generated), docs/FROM-JASPER.md; `examples/`.
+
+### Changed
+- The Excel export has its own writer: no ExcelJS (and none of its deprecated dependencies, `uuid` among them);
+  50,000 rows: export memory +124 MB (was +409 MB), 3× faster.
+- Runtime dependencies are pinned to exact versions; the unused `harfbuzzjs` dependency is gone. `npm audit`: 0.
+- Every package ships readable (not minified) ES modules with source maps.
+- The viewer loads other interface languages and the Excel, HTML and CSV exporters on demand: first load 847 KB
+  gzipped (was 877 KB minified).
+- React, Vue, Svelte, Angular wrappers: a failed import shows its error in the element (`onError`); options are
+  compared by content, so an inline `definition` object does not remount the designer.
+- Package metadata (repository, homepage, bugs, keywords, engines, `sideEffects`, typed `exports`), README badges,
+  this changelog in every package, SECURITY.md, a semver policy, and a GitHub workflow that publishes with npm
+  provenance.
+
+## 0.7.3
+- Firefox and WebKit smoke tests in CI; settings table entries for monitoring. No API change.
+
+## 0.7.2, 0.7.1
+- Fixes to the package builds and README quick starts.
+
+## 0.7.0
+- First public release under the `@pagewrightjs` scope: engine, fonts, cli, viewer, react, vue, svelte, angular.

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Arun Mallikarjun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The fonts in public/fonts are under the SIL Open Font License (see their licence files).

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @reportwright/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![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) [![provenance](https://img.shields.io/badge/npm-provenance-green)](https://docs.npmjs.com/generating-provenance-statements)
+
+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. Includes the `pw` command line.
+
+```bash
+npm i @reportwright/engine @reportwright/fonts
+```
+
+```js
+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;
+// for your own fonts: new FontStore((key) => bytesOf(fontFile(key)))
+const fonts = defaultFontStore();
+const model = await render(JSON.parse(fs.readFileSync('statement.pw.json', 'utf8')), { fontStore: fonts, parameters: { accountId: 'LN-1' } });
+// fonts are subset by default (only the glyphs the PDF uses); { subset: false } embeds every font in full
+fs.writeFileSync('statement.pdf', await exportPdf(model, { fonts, title: 'Statement' }));
+// a bundled browser app (Vite, webpack, Next client code): copy the fonts folder to your site and point at it, since the
+// package's location is not known to the bundler. `cp -r node_modules/@reportwright/fonts/public/fonts public/pw/fonts`
+const bundledFonts = defaultFontStore({ fontsUrl: '/pw/fonts/' }); // a missing font is an error; a URL or, in Node, a path
+// the same options object everywhere: exportXlsx(model, { fonts }), exportDocx(model, { fonts }), exportPptx(model, { fonts })
+// Excel, CSV, Word, interactive HTML and the accessible PDF rebuild tables from the table data, which render() keeps
+// only when asked: render(def, { exportData: true }) (needsExportData(format) says which formats need it)
+```
+
+## 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
+  date (`2024-01-31`, `2024-01-31T10:00:00Z`) becomes a date. Keep such strings as text with `detectDates: false` on
+  the data set, or declare the fields and give that one `type: 'string'`.
+- **Chart colours.** By default colours go by position. `colorByCategory: true` on charts gives each category (pie,
+  donut and funnel slices; `seriesGroup` series) one colour in every chart of the report that sets it.
+- **Network.** Only data sources of a fetched type (`rest`, `graphql`, `soap`, `odata`, and `csv` or `xml` with a URL) and SQL sources without
+  `sql` make requests, through `render(def, { fetch })`. Without that option the engine uses `globalThis.fetch` behind
+  an SSRF guard: http(s) only; no loopback, private, link-local, CGNAT, multicast or reserved address in any spelling
+  (`2130706433`, `0x7f.1`, `[::ffff:127.0.0.1]`), no `localhost` name; in Node (20.16+) the request goes through
+  node:http(s) with the checked address pinned (no DNS rebinding; a failed lookup refuses); every redirect hop checked
+  again (at most 5; never https → http; another origin gets none of the source's headers); a parameter fills a URL's path and query, never its scheme and host (unless the
+  whole URL is a parameter and its host is in `allowHosts`). `allowHosts: ['10.0.0.5']` lets named hosts through;
+  `unsafeFetch: true` turns the guard off. Pass your own `fetch` to add auth, a proxy or an allow-list, or to forbid
+  requests altogether: `render(def, { fetch: () => { throw new Error('no network') } })`.
+- **Fetch limits.** Every data request (yours too) stops after `fetchTimeoutMs` (30 s, never past the render's
+  `timeoutMs`) and after `maxFetchBytes` (64 MB, counted decoded, so a gzip bomb stops too). Exporters take
+  `timeoutMs` as well; the PDF exporter checks every PNG before decoding it and leaves a damaged one out (`onWarning`).
+- **Currency.** `C2` with no `currency` on the report uses the locale's own (`en-IN` ₹, `de-DE` €, `en-US` $).
+
+## Many reports at once (Node): a worker pool
+
+```js
+import { createPool } from '@reportwright/engine/pool';
+const pool = createPool({ workers: 4 });            // default: CPU count - 1; each worker loads the engine and fonts once
+const pdf = await pool.render(definition, { format: 'pdf', parameters: { id: 42 } });   // Uint8Array
+await pool.close();
+```
+
+Measured on an 8-core laptop, 40 copies of a one-page chart report (`node scripts/bench-pool.mjs`): 1 worker 14.7/s,
+4 workers 40.7/s.
+
+The `pw` command line is in `@reportwright/cli`:
+
+```bash
+npx -p @reportwright/cli pw render statement.pw.json -p accountId=LN-1 -d loans=data.json -f pdf -o statement.pdf
+npx -p @reportwright/cli pw test reports        # snapshot tests for reports-as-code
+```
+
+MIT.