@quario/pdf 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @quario/pdf
 
+## 0.9.0
+
+### Minor Changes
+
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
+
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
+
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+### Patch Changes
+
+- The package now accepts only a version of `@cantoo/pdf-lib` it can import. The declared range is
+  `~2.9.1` rather than `^2.9.1`.
+
+  Earlier versions accepted `@cantoo/pdf-lib` 2.11.0, whose ESM build imports its font metric JSON
+  without an import attribute. A fresh install could resolve to it, and importing `@quario/pdf` then
+  failed on Node before rendering anything, with `TypeError [ERR_IMPORT_ATTRIBUTE_MISSING]` naming a
+  `.compressed.json` file inside that package. Node 22 and Node 24 both report it. If you saw that
+  error, reinstall — nothing in your own code has to change.
+
+- Updated dependencies
+  - quario@0.9.0
+  - @quario/layout@0.6.0
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -4,8 +4,8 @@
 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 —
-through `@quario/layout`, the same layout the viewer paints on screen, so the preview and the
-document break their pages in the same places. [`@cantoo/pdf-lib`](https://github.com/Cantoo-Scribe/pdf-lib) writes the file. You get typesetting plus pdf-lib: no Chromium
+through `@quario/layout`. That is the same layout the viewer paints on screen, so the preview and
+the document break their pages in the same places. [`@cantoo/pdf-lib`](https://github.com/Cantoo-Scribe/pdf-lib) writes the file. You get typesetting plus pdf-lib: no Chromium
 in your container, no page-load race, no fonts-not-ready flake.
 
 ## Install
@@ -14,8 +14,8 @@ in your container, no page-load race, no fonts-not-ready flake.
 npm install quario @quario/pdf
 ```
 
-`@cantoo/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.
+`@cantoo/pdf-lib` arrives 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:
 
@@ -58,8 +58,9 @@ const paged = {
 ```
 
 `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, probed as a
-two-page document, so `=page.total > 10` reserves only the 8 pt gap a declared band always costs.
+`page.number` only. The layout reserves band heights before it knows the real page count, probing as a
+two-page document. `=page.total > 10` therefore reserves only the 8 pt gap a declared band always
+costs.
 `page.total` is fine in band _text_.
 
 ## API
@@ -67,7 +68,7 @@ two-page document, so `=page.total > 10` reserves only the 8 pt gap a declared b
 ### `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)`
+the target you pass to `render`. The factory refuses an option it does not know. It throws a `TypeError` at the call for an unknown key. It throws one also for a key with a value of the wrong type. `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.
@@ -81,14 +82,14 @@ The compiled report carries `stream` (the raw event generator), `names`, `functi
 `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
+Rendering is asynchronous and returns the loop between batches, so a large report never blocks the
 host. Render-time failures reject with located errors.
 
 ### Options
 
 Page size and fonts are target configuration. The margin is the target's unless the document
-declares `page.margin`, in which case the document's is used; a document and a target that both
-declare one reject the render.
+declares `page.margin`, in which case the document's margin wins. A document and a target that
+both declare one reject the render.
 
 ```js
 {
@@ -98,7 +99,7 @@ declare one reject the render.
 }
 ```
 
-`size` defaults to `A4` (595.28 × 841.89 pt); an array is a custom `[width, height]` in points. An
+`size` defaults to `A4` (595.28 × 841.89 pt). An array is a custom `[width, height]` in points. An
 unknown size name is an error the factory throws. `margin` applies to all four sides and defaults to 54
 (0.75 in). Text renders at 10pt when nothing declares a size: a document's type size is the
 document's own, so it is the report's `style.size`, not a host option. Line leading is 1.4× a line's
@@ -108,8 +109,8 @@ largest font size.
 
 **Guaranteed** normative behavior a conforming target must produce:
 
-- Table header rows repeat after every page break. An unstyled table draws no rules; an
-  authored border on a header row or a total row is drawn at the width written.
+- Table header rows repeat after every page break. An unstyled table draws no rules. The target draws an
+  authored border on a header row or a total row at the width written.
 - 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.
@@ -117,25 +118,25 @@ largest font size.
 - 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
+- The target honours authored column `width` percentages. It measures the remaining columns from
+  content and scales them 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.
-- A report header declaring `height` pins a box of that many points from the page top; its items
+- A report header declaring `height` pins a box of that many points from the page top. Its items
   pack from the top and the next band starts where the box ends.
-- Every group instance opens with a half-line gap, dropped at a page top; authored `spaceBefore`
+- Every group instance opens with a half-line gap, dropped at a page top. Authored `spaceBefore`
   drops at a fresh page or strip top the same way.
 - An item or row a page cannot hold whole still carries its box: each slice draws the sides the
   break left it, the top on the first and the bottom on the last.
-- A split lays out as one block at the height of its tallest slot; every slot's box is the split's
+- A split lays out as one block at the height of its tallest slot. Every slot's box is the split's
   height, and a slot's `valign` places its content in that slack, as a table cell's does in its
   row's.
 - Page columns are strips: the flow fills one to its foot, moves to the next, and turns the page
-  once the last is spent; a table restates its headings at a strip head, a group's headers only
+  once the last is spent. A table restates its headings at a strip head, and a group's headers only
   at a page head.
-- The band-role defaults (a bold, larger report header; bold group headers) sit under the
-  author's own style, and `uppercase` capitalises the drawn string before it is measured.
+- The band-role defaults (a bold, larger report header, and bold group headers) sit under the
+  author's own style. `uppercase` capitalises the drawn string before the target measures it.
 - 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.
@@ -154,9 +155,9 @@ without authored margins.
 
 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 a face cannot draw render as `?` rather than failing the report, because cell
-text is untrusted data and one stray character must not take a document down. WinAnsi is the
-base-14 limit; a TrueType face's cmap is its own.
+encoding. Characters a face cannot draw render as `?` rather than failing the report, because
+quario does not trust cell text, and one stray character must not take a document down. WinAnsi
+is the base-14 limit. A TrueType face's cmap is its own.
 
 For full Unicode, supply TrueType families and select them by name:
 
@@ -169,10 +170,10 @@ const target = pdf({
 // 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. A mapping
-without a `regular` is refused by the factory (`options.fonts.<name>.regular: required`); bytes
+Missing variants fall back to the family's regular. Embedded text uses the font's own metrics.
+The target subsets it to the glyphs the document uses and carries a ToUnicode map, so extraction
+and copy see the original text. quario trusts fonts as host assets, like registered functions. The
+factory refuses a mapping without a `regular` (`options.fonts.<name>.regular: required`). Bytes
 the parser cannot read reject the render, located at the same option path.
 
 ## Outline
@@ -183,19 +184,19 @@ 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,
+This target pins the document's dates rather than stamping them, 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.
+per-page presence is normative. Exact geometry is best-effort. A licensed render draws nothing.
 
 ## Page furniture
 
-Paper size and fonts are options, not schema; the margin is an option a document may declare in
+Paper size and fonts are options, not schema. The margin is an option a document may declare in
 its stead. Authored watermarks and finer break control stay out of scope. Keep-together and continuation headers are by construction, above.
 
 The full contract is [The PDF target](https://getquario.com/docs/diving-deeper/pdf-target/),
@@ -211,10 +212,10 @@ specification of what a report may declare, and
 
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key once, on the instance; it is verified offline:
+Pass your license key once, on the instance. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/index.d.ts

@@ -14,7 +14,11 @@ export interface PdfMeta {
 /** One embeddable TrueType family: the layout's own, measured and embedded from the same bytes. */
 export type PdfFontFamily = LayoutFontFamily;
 
-/** Host controls, taken and validated at the factory call. */
+/**
+ * Host controls, taken and validated at the factory call: an option this
+ * target does not understand, or one of the wrong type, throws a `TypeError`
+ * there rather than costing the host the option in silence.
+ */
 export interface PdfOptions {
   page?: PdfPage;
   meta?: PdfMeta;

package/lib/index.js

@@ -15,6 +15,7 @@
  */
 import { PDFDocument } from "@cantoo/pdf-lib";
 import { layout } from "@quario/layout";
+import { hostMeta, hostOptions } from "quario";
 import { embedFonts } from "./embed.js";
 import { outline } from "./outline.js";
 import { paint } from "./painter.js";
@@ -26,13 +27,16 @@ import { paint } from "./painter.js";
 // Optional document information. Never a date: pdf-lib stamps the current time
 // unless told otherwise, and a timestamp would make the same input render
 // different bytes on every run. Each key names the pdf-lib setter it feeds,
-// here rather than in a table, and a value of any other shape is left off.
+// here rather than in a table, and that mapping is all this target owns of
+// `meta` -- the contract itself is the engine's `hostMeta`, checked at the
+// factory call, so a present property is a string and a nullish one is a
+// property the host did not write.
 /** @type {(doc: any, meta: any) => void} */
 let describe = (doc, meta) => {
   doc.setCreationDate(new Date(0));
   doc.setModificationDate(new Date(0));
   let field = (/** @type {string} */ method, /** @type {any} */ value) => {
-    if (typeof value === "string") doc[method](value);
+    if (value != null) doc[method](value);
   };
   if (meta) {
     field("setTitle", meta.title);
@@ -61,7 +65,9 @@ let open = async (meta, custom) => {
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function pdf(options) {
-  let { page, fonts: custom, meta } = options ?? {};
+  hostOptions(options, ["page", "meta", "fonts"], "options");
+  let { page, fonts: custom, meta: written } = options ?? {};
+  let meta = hostMeta(written, "options.meta");
   let paged = layout({ page, fonts: custom });
   /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
   let compile = (stream) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/pdf",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The browserless, paginated PDF render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -36,21 +36,21 @@
     "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
   },
   "dependencies": {
-    "@cantoo/pdf-lib": "^2.9.1",
-    "@quario/layout": "^0.5.0"
+    "@cantoo/pdf-lib": "~2.9.1",
+    "@quario/layout": "^0.6.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/fontkit": "^2.0.9",
     "fontkit": "^2.0.4",
-    "quario": "^0.8.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "fontkit": "^2.0.4",
-    "quario": "^0.8.0"
+    "quario": "^0.9.0"
   },
   "peerDependenciesMeta": {
     "fontkit": {