@quario/pdf 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to @quario/pdf are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-27
+
+### Added
+
+- **Paginated PDFs from the same compiled report.** The band flow places
+  headers, groups, and tables; pdf-lib writes the file. Page furniture and an
+  outline from the group tree. Optional TrueType embedding through
+  `@pdf-lib/fontkit`.

package/LICENSE

@@ -0,0 +1,219 @@
+# Quario License Agreement
+
+> **In short:** Quario is commercial software with visible source.
+> Evaluate it free for as long as you like. Evaluation output is
+> watermarked. Anything else needs a per-developer license, after
+> which deployment is unlimited and royalty-free. This summary is not
+> the license; the full terms below govern.
+
+Version 1.0, August 2026
+
+This agreement is between you and Webstronauts, trading as Quario,
+established in the Netherlands ("we", "us"), and governs the Software
+defined below.
+
+Quario is commercial software. Its packages ship with readable source
+code, but it is not open source. No rights are granted beyond those in
+this agreement.
+
+## 1. Definitions
+
+- The **Software** is any software we publish under the Quario name,
+  including the `quario` and `@quario/*` packages, except where a
+  product states its own terms. Each release states the edition of this
+  agreement that governs it.
+- **You** means the individual exercising rights under this agreement
+  and, where that individual acts for a company or other organization,
+  that organization. In that case the organization is the licensee, and
+  the rights and limits in this agreement apply to it as a whole.
+- An **Application** is software you create that incorporates the
+  Software and adds substantial functionality beyond it. A
+  licensee-operated service that embeds the Software and renders
+  reports for your End Users is an Application under this agreement,
+  even if it does little more than render.
+- A **Developer** is any individual (employee or contractor working on
+  your behalf) who writes or maintains code that uses the Software's
+  APIs, or who creates or maintains report definitions for use with the
+  Software. That includes people who never install or run the Software
+  themselves, when their definitions are rendered by a service that
+  embeds it.
+- A **Seat** is a paid license for one named Developer, purchased from
+  us or an authorized reseller.
+- **End Users** are people who interact with the Software only through
+  an Application: running it, viewing the reports it produces, or
+  supplying parameters or other input to existing report definitions
+  the Application provides. Creating or maintaining report definitions
+  makes someone a Developer. End Users do not purchase a license; their
+  rights come from section 5.
+
+## 2. Acceptance
+
+This file is our standing offer. Anyone who exercises the evaluation
+rights in section 3 accepts them, subject to their conditions. All
+other rights arise when Seats are purchased. Where a purchase is made
+for an organization, the person completing it confirms that they are
+authorized to accept this agreement on the organization's behalf, and
+acceptance covers the whole organization. If you do not accept this
+agreement, do not use the Software.
+
+## 3. Evaluation
+
+You may download, install, and use the Software free of charge to
+evaluate it: assessing whether it suits your purposes, and building
+prototypes or proofs of concept. Evaluation covers the full feature
+set, needs no key, and has no fixed time limit. The Software marks
+evaluation output as described in section 6.
+
+Evaluation is limited to assessment: you may not distribute any
+Application containing the Software, use the Software in live business
+operations, or expose it in services offered to third parties. The
+moment your use goes beyond evaluating the Software, it requires Seats
+under section 4.
+
+## 4. Developer licenses
+
+Any use of the Software beyond section 3 requires a Seat for every
+Developer, whether or not an Application has shipped. With those Seats
+in place:
+
+- Each licensed Developer may install and use the Software on any number
+  of machines for developing Applications.
+- Automated build, test, and CI systems do not consume Seats.
+- Seats are per named individual. They may be reassigned when a
+  Developer stops working with the Software, but not shared or pooled
+  between concurrently active Developers. Contractors' work for you is
+  covered by your Seats; work they do for other clients is not.
+
+## 5. Distribution and runtime
+
+With Seats under section 4 in place, you may deploy and operate your
+Applications yourself, and distribute the Software as an embedded part
+of them, **royalty-free**: no additional fees or per-deployment
+licenses are required for any number of servers, copies, or End Users.
+You may embed your license key in an Application and ship it at no
+charge, so section 6 does not mark that Application's output.
+
+For that purpose, we grant you the right to pass through to each End
+User, and to anyone who distributes or operates your Application on your
+behalf, a limited, non-exclusive, non-transferable right to execute the
+Software only as embedded in the Application. You must not permit them
+to extract the Software from the Application or use it to develop
+software of their own.
+
+If you operate a service that embeds the Software and renders reports
+for your End Users, that service is an Application under section 1. You
+may run it royalty-free under this section, and you may put your license
+key in it as in any Application. Calling applications that only request
+renders from it need not incorporate the Software. People who use those
+applications only as End Users under section 1 get the pass-through
+rights above.
+
+You may not:
+
+- distribute the Software on its own, or as part of a product whose
+  primary purpose is to provide report-engine, report-design, or
+  document-generation capability to third-party developers;
+- expose the Software's APIs to third parties as a development tool or
+  service that substitutes for those parties buying their own Seats. A
+  licensee-operated service that embeds the Software and renders for
+  your own End Users falls outside that ban;
+- fork, mirror, repackage, rename, or wrap the Software, or republish
+  it on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+For as long as this agreement is in force, you may not create any tool,
+library, product, or service that competes with the Software or any
+other Quario product, whether the competition is direct or indirect;
+this restriction does not survive termination. You may not remove or
+alter copyright or license notices in the Software. If your Application
+is itself a closed development product for third-party developers (OEM
+redistribution), contact us for separate terms.
+
+## 6. License keys and output marking
+
+The Software accepts a license key that evidences your Seats under
+section 4. Key checks run offline.
+
+Without a valid key, or with a key whose validity period does not cover
+the installed version's release date, the Software runs with its full
+feature set but marks its output as unlicensed. Using a key you are not
+entitled to is a material breach of this agreement.
+
+You may not remove, disable, or circumvent the key check or the output
+marking, or distribute anything that does.
+
+## 7. Term, updates, and perpetual fallback
+
+Seats are sold as an annual subscription. While the subscription is
+active, licensed Developers receive all Software versions we release,
+and support for the Software through our issue tracker and by email. We
+provide support with commercially reasonable effort; we do not guarantee
+specific response times.
+
+If the subscription lapses, your license to the versions released during
+your subscription is **perpetual, for the number of Seats held at the
+lapse**: up to that many Developers may keep using those versions, and
+your Applications may keep shipping them, forever, at no further cost.
+Versions released after the lapse require renewal. We encode this rule
+in purchased keys: a key remains valid for every version released
+during its validity period, with no end date.
+
+## 8. Source availability
+
+The Software's packages ship with readable source code so that you can
+review and debug what you run. Readable source does not grant extra
+rights: this agreement governs all use of the source, and you may
+publish the Software (modified or not) only as part of an Application
+under section 5.
+
+## 9. Ownership, trademarks, and feedback
+
+We license the Software; we retain all intellectual property rights in
+it. Report definitions, data, and output you create with the Software
+are yours. "Quario" and the Quario logo are our trademarks; this
+agreement grants no rights to use them beyond identifying the Software.
+If you send us feedback or suggestions, we may use them without
+obligation.
+
+## 10. Warranty and liability
+
+We provide the Software as is. To the fullest extent the law allows, we
+disclaim all warranties and conditions, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement.
+
+To the fullest extent the law allows: we are not liable for indirect or
+consequential damages, loss of profits, loss of data, or business
+interruption; and our total aggregate liability under this agreement is
+limited to the greater of EUR 100 and the fees you paid us in the
+twelve months preceding the event giving rise to the claim. These
+limitations do not apply where the damage results from the intent or
+deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
+management, or where mandatory law does not permit them.
+
+## 11. Termination and survival
+
+If you materially breach this agreement, we may terminate it by notice.
+If the breach can be remedied, we will first allow 30 days from that
+notice to remedy it, and termination takes effect only if the breach
+remains. On termination, the licenses granted here end.
+Perpetual-fallback rights under section 7 survive termination only if
+they arose from a lapse that predates the breach, and section 5
+survives with them to the extent needed to keep exercising them.
+Sections 8 through 12 survive any termination.
+
+## 12. General
+
+Dutch law governs this agreement. Disputes go to the competent court for
+our registered office. You may not assign this agreement without our
+consent, except to a successor of your whole business; we may assign it
+to a successor of ours. If a provision is unenforceable, the remainder
+stays in force. Failure to enforce a provision does not waive it. This
+agreement, together with your order for Seats, is the entire agreement
+about the Software, unless we agree otherwise in writing.
+
+---
+
+**Purchasing and contact:** <contact@getquario.com> ·
+<https://getquario.com>
+
+Copyright © 2026 Webstronauts. All rights reserved.

package/README.md

@@ -0,0 +1,189 @@
+# @quario/pdf
+
+**The PDF render target for [quario](https://www.npmjs.com/package/quario).** Renders a report
+definition straight to a paginated PDF. No headless browser, no print CSS, deterministic bytes.
+
+quario does the typesetting: pagination, keep-together, tables, fonts, the document outline.
+[pdf-lib](https://pdf-lib.js.org) writes the file. You get typesetting plus pdf-lib: no Chromium
+in your container, no page-load race, no fonts-not-ready flake.
+
+## Install
+
+```bash
+npm install quario @quario/pdf
+```
+
+pdf-lib comes along as a dependency; the engine is a peer, installed beside it. ESM-only, Node 22+, and browser-ready through
+any standards-based ESM bundler. The renderer returns bytes, so the host decides where they go.
+
+Embedding TrueType fonts also needs the optional peer:
+
+```bash
+npm install @pdf-lib/fontkit
+```
+
+It loads only when you pass `fonts` to the factory. The base-14 families need nothing extra.
+
+## Quick start
+
+```js
+import { writeFileSync } from "node:fs";
+import { pdf } from "@quario/pdf";
+import { quario } from "quario";
+
+const report = quario().report(schema, funcs);
+const bytes = await report.render(
+  pdf({ page: { size: "A4", margin: 54 }, meta: { title: "Sales 2026" } }),
+  data,
+);
+
+writeFileSync("sales.pdf", bytes);
+```
+
+Any schema the HTML target renders works here unchanged. Add page bands when you want running
+headers and page numbers. Page bands are the one part of the schema that only paginated targets
+consume:
+
+```js
+const paged = {
+  ...schema,
+  page: {
+    header: [{ type: "text", value: "{{ $.params.title }}", style: { size: 8, color: "#777777" } }],
+    footer: [
+      { type: "text", value: "{{ page.number }} / {{ page.total }}", style: { size: 8, align: "right" } },
+    ],
+  },
+};
+```
+
+`visible: "=page.number > 1"` on a band is the cover-page recipe. Gate band _visibility_ on
+`page.number` only. Band heights are reserved before the real page count is known, so
+`=page.total > 10` reserves nothing. `page.total` is fine in band _text_.
+
+## API
+
+### `pdf(options?)`
+
+The target factory takes this target's host options, validates them at the call, and returns
+the target you pass to `render`. `report()` compiles once and `report.render(pdf(options), data)`
+resolves the document bytes. One compile serves any number of configurations (A4 and letter from
+the same report). Compile at startup and render per request. Definition problems throw at
+`report()`, at compile time.
+
+```js
+const report = quario().report(schema, funcs);
+const bytes = await report.render(pdf({ page: { size: "letter" } }), data);
+```
+
+The compiled report carries `stream` (the raw event generator), `names`, `functions`, and
+`paths`, like every quario report. Engine-level options (`query` budgets, the license key)
+live on the instance, and `q.license` settles with the verification result.
+
+Rendering is asynchronous and hands the loop back between batches, so a large report never blocks the
+host. Render-time failures reject with located errors.
+
+### Options
+
+Page geometry is target configuration, never schema:
+
+```js
+{
+  page: { size: "A4", margin: 54 },   // 'A4' | 'letter' | [width, height] in points
+  baseSize: 10,                       // base font size in points
+  meta: { title, author, subject },   // optional /Info — strings only, never a date
+  fonts: { Inter: { regular, bold, italic, boldItalic } },  // TrueType bytes
+}
+```
+
+`size` defaults to `A4` (595.28 × 841.89 pt); an array is a custom `[width, height]` in points. An
+unknown size name is a definition error, thrown by the factory. `margin` applies to all four sides and defaults to 54
+(0.75 in). `baseSize` defaults to 10 and style `size` declarations override it per element; line
+leading is 1.4× a line's largest font size.
+
+## Layout
+
+**Guaranteed** normative behavior a conforming target must produce:
+
+- Table header rows repeat after every page break, with a rule under the header and above the
+  total row.
+- A group header always travels with its first content unit: the first detail lines, or a table's
+  header plus its first row. An instance's headers also repeat at the top of every page it
+  continues onto (outermost first, then content) and stop when the instance ends.
+- The total row keeps the last data row with it.
+- A row that fits on a page is never split across one.
+- `break: "page"` on a group opens a fresh page per instance.
+- `reset: "page"` on a group does the same and restarts `page.number` / `page.total` for that instance's sequence.
+- Authored column `width` percentages are honoured; remaining columns are measured from
+  content and scaled to fill the rest. A table whose authored shares leave the width-less columns
+  nothing is a definition error, so there is no over-commitment case.
+- Hidden cells keep their column slot.
+- Page bands render on every page, their heights reserved out of the body area.
+- An image draws at the size its `fit` dictates (`natural` at 96 dpi capped at the content
+  width, `width` scaled to it, aspect ratio preserved) and is never split across a page break:
+  one that does not fit the remaining height moves whole to a fresh page.
+
+**Best-effort** current implementation, pinned by no test and changeable
+without a breaking change: paragraph widow and orphan avoidance, slicing a row taller than the
+page, downscaling an image taller than any page, embedding repeated image bytes once, and where
+an image's page break lands. Do not write definitions that depend on these.
+
+Bands flow vertically in walk order, matching the HTML target's divs. Group nesting adds no
+indentation, but every instance opens with a structural half-line gap so groups read as blocks
+without authored margins.
+
+## Fonts and text
+
+The base-14 Helvetica, Times, and Courier families carry the default output (`family: "sans"`,
+`"serif"`, `"mono"`, each with regular, bold, italic, and bold-italic faces), using WinAnsi
+encoding. Characters outside WinAnsi render as `?` rather than failing the report, because cell
+text is untrusted data and one stray character must not take a document down.
+
+For full Unicode, supply TrueType families and select them by name:
+
+```js
+import { readFileSync } from "node:fs";
+
+const target = pdf({
+  fonts: { Inter: { regular: readFileSync("Inter-Regular.ttf"), bold: readFileSync("Inter-Bold.ttf") } },
+});
+// then, in the schema: style: { family: "Inter" }
+```
+
+Missing variants fall back to the family's regular. Embedded text uses the font's own metrics, is
+subset to the glyphs the document uses, and carries a ToUnicode map so extraction and
+copy see the original text. Fonts are trusted host assets, like registered functions.
+
+## Outline
+
+A grouped report carries a document outline (bookmarks) mirroring the group tree: one open entry
+per instance, nested by depth, titled by the instance's first group-header text, or `name: key`
+when there is none. Ungrouped reports have no outline.
+
+## Determinism
+
+The document's dates are pinned rather than stamped and `meta` is opt-in, so the same schema,
+data, and options produce **byte-identical** output. That makes report bytes cacheable, diffable,
+and safe to compare in tests.
+
+## Unlicensed marking
+
+An unlicensed render draws the wording from `report-start.marking` once per page, after
+everything else: a translucent grey line corner-to-corner over content and page furniture. The
+per-page presence is normative; exact geometry is best-effort. A licensed render draws nothing.
+
+## Page furniture
+
+Paper size, margins, and fonts are options, not schema. Authored watermarks and finer break
+control stay out of scope. Keep-together and continuation headers are by construction, above.
+
+## License
+
+Commercial software with readable source. Free, unlimited, watermarked evaluation; 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:
+
+```js
+const q = quario({ license: "quario_..." });
+await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
+```

package/lib/balance.js

@@ -0,0 +1,90 @@
+// The one number a balanced region decides: how tall each of its strips is
+// (ADR 0020 — balancing is a strip height, not a pass). Pure arithmetic over
+// what the buffer holds, so nothing here reaches a canvas or the band flow.
+//
+// Balancing by height alone under-fills, because most of what a region holds
+// does not divide: a group instance, a table row and an image each move whole.
+// A share that is not a whole number of them holds one fewer than it should,
+// and the page-bounded last strip absorbs the remainder (beads `quario-s5c`,
+// `quario-cgk`). So the height is not `measured / count` but the shortest
+// whole-line height at which placing the units in order lands them all in
+// `count` strips.
+//
+// The candidates are line multiples, for the reason the average was rounded to
+// one before this: a floor cuts between lines, so a height that is not a whole
+// number of them leaves every strip a fraction short. They are scanned from the
+// shortest upward rather than searched, because the range is bounded by the
+// lines a page holds and a scan owes nothing to an argument about the fill
+// being monotone in the height. The average is not the starting point and not
+// a lower bound: an instance drops its opening gap at a strip head, so `count`
+// of those gaps are measured that no strip ever pays.
+
+// A **unit** is one thing a strip places: `h` is what it costs mid-strip and
+// `head` what it costs when it is the first thing in a strip — which can be
+// less (a group instance drops its opening gap there) or more (a table row
+// pays for the column headings restated above it). `whole` units move
+// undivided and are the only ones `head` is read for; the rest flow, and
+// nothing that flows costs a different amount for opening a strip. What fills each of these in is the caller's, in
+// `layout.js`, which is also where the model's stated limits are.
+/**
+ * @typedef {{ whole: boolean, h: number, head: number }} Unit
+ */
+// How far one trial has filled: the strips it has opened and the height taken
+// out of the one it is in.
+/**
+ * @typedef {{ strips: number, used: number }} Fill
+ */
+
+// The height, or `null` when no candidate packs the units into `count` strips
+// and the region should fill instead. `room` is what one strip could hold at
+// most — the page — and `line` the height a floor cuts on.
+/** @type {(units: Unit[], count: number, room: number, line: number) => number | null} */
+export let balance = (units, count, room, line) => {
+  for (let lines = 1; lines * line <= room; lines++) {
+    let height = lines * line;
+    if (stripsFor(units, height) <= count) return height;
+  }
+  return null;
+};
+
+// How many strips this height needs. `Infinity` when a unit is too tall for a
+// strip of it at all — the scan answers that by looking higher, and the region
+// fills once even the page is too short.
+// The only way a height fails outright is a whole unit taller than a strip of
+// it, so that case is answered here rather than through a result both helpers
+// would have to carry.
+/** @type {(units: Unit[], height: number) => number} */
+let stripsFor = (units, height) => {
+  /** @type {Fill} */
+  let fill = { strips: 1, used: 0 };
+  for (let unit of units) {
+    if (!unit.whole) placeFlow(fill, unit, height);
+    else if (unit.head > height) return Infinity;
+    else placeWhole(fill, unit, height);
+  }
+  return fill.strips;
+};
+
+// A whole unit that would cross the floor opens the next strip instead, where
+// its opening gap is dropped — the rule `breaksFor` applies during the replay.
+/** @type {(fill: Fill, unit: Unit, height: number) => void} */
+let placeWhole = (fill, unit, height) => {
+  if (!fill.used) fill.used = unit.head;
+  else if (fill.used + unit.h <= height) fill.used += unit.h;
+  else {
+    fill.strips++;
+    fill.used = unit.head;
+  }
+};
+
+// Breakable content fills to the floor and continues in the next strip, so it
+// spills across as many as it takes rather than moving whole. No height is too
+// short for it: content that splits always goes somewhere.
+/** @type {(fill: Fill, unit: Unit, height: number) => void} */
+let placeFlow = (fill, unit, height) => {
+  fill.used += unit.h;
+  while (fill.used > height) {
+    fill.strips++;
+    fill.used -= height;
+  }
+};