@quario/pdf 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,39 +1,106 @@
-# Changelog
+# @quario/pdf
 
-All notable changes to @quario/pdf are documented in this file.
+## 0.9.0
 
-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).
+### Minor Changes
 
-## [Unreleased]
+- **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.
 
-## [0.7.0] - 2026-09-07
+  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.
 
-### Added
+  **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
+
+- **An image's box is now as wide as the container it sits in.** A
+  `background` or `border*` on an image item hugged the picture and now spans
+  the content width, or the slot's share inside a split; the picture itself
+  does not move. See the `@quario/layout` changelog for the rule and for what
+  it costs a report that relied on a border hugging a logo.
+
+### Patch Changes
+
+- **Every published README says where the documentation is.** Each package now
+  carries a Documentation section pointing at the reference, at the report schema
+  that normatively specifies what a report may declare, and at the package's own
+  API. The paragraphs that used to end on an unstated contract — the event
+  stream's field semantics, the style vocabulary, page columns, the Content
+  Security Policy a fragment with images needs, the formula mangling, and each
+  target's own contract — link the page that states it. Every link is an absolute
+  URL, so it resolves from the npm package page as readily as from an installed
+  copy.
+- Updated dependencies
+  - @quario/layout@0.5.0
+  - quario@0.8.0
+
+## 0.7.0
+
+### Minor Changes
 
 - **Styled runs reach the page.** A cell value written as a list of styled runs
   draws each run in its own face, size and colour, underlines and strikes
   through per run rather than across the line, and paints a run's `background`
   as a highlight behind its text.
-
-### Changed
-
 - **A `format` inside a sentence now presents where the engine says it does.** A
   cell mixing literal text and one interpolation under a `format` draws the
   value plainly, as the spreadsheet and CSV targets already did; splitting the
   value into styled runs is how a value inside a sentence is formatted.
 
-## [0.6.0] - 2026-09-07
+## 0.6.0
 
-### Added
+### Minor Changes
 
 - **A cell's own `currency` code is honoured**, ahead of the instance's
   default, so a listing whose rows arrive in different currencies presents each
   in its own. A code the engine could not accept leaves the cell as plain
   display text rather than presenting it in the instance's currency.
-
-### Changed
-
 - **Numbers presented through `format` now show a fixed two fraction digits,
   matching every other target.** `format: "number"` on `1000` renders
   `1,000.00` where it rendered `1,000`, and `0.12345` renders `0.12` where it
@@ -42,9 +109,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   so a JPY amount loses the two decimals it never had. `date` is unchanged, as
   are grouping separators and symbol placement. The digits come from the
   engine, so a cell reads the same here as it does in a workbook.
-
-### Fixed
-
 - **An image these bytes cannot embed now fails with the item's name on it.**
   A PNG whose pixel data is corrupt past the size in its header used to reject
   the render with `Invalid typed array length: 0` — the PDF writer's own words,
@@ -54,9 +118,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   account after it and on `cause`. A JPEG is unchanged: its header is read but
   its pixel data never is, so a corrupt one still embeds without complaint.
 
-## [0.5.0] - 2026-09-05
+## 0.5.0
 
-### Added
+### Minor Changes
 
 - **A spanning cell draws as one box** across the columns it covers, through
   `@quario/layout`. It takes no part in measuring them, and a spanning row that
@@ -64,16 +128,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   each slice lands in.
 - **`valign`** on table cells and split slots, through `@quario/layout`: middle
   and bottom place the content in the height its row or split leaves over it.
-
-### Changed
-
 - **A row's box is drawn by the row's cells**, through `@quario/layout`. A box
   declared on a table row used to be one rect across the columns; each covered
   cell now draws its own. A row's `borderBottom` still reads as one continuous
   edge, a row's `borderLeft` becomes an edge on every cell rather than one at
   the row's outer left, and a bordered row is taller by its border's width,
   since a border occupies height as a cell's always has.
-
 - **Embedding TrueType fonts now needs `fontkit`, not `@pdf-lib/fontkit`.**
   Install `fontkit` instead; nothing else about `options.fonts` changes. The
   old package's bundle crashed with a bare `ReferenceError` on any OpenType
@@ -81,28 +141,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Tamil, Khmer or Myanmar webfont in practice, and some fifty further scripts
   besides. Those faces now measure, embed and draw. Which scripts a face
   supports remains the font's and the parser's to answer, not this package's.
-
 - **`pdf-lib` is now `@cantoo/pdf-lib`.** A maintained fork, and what
   `fontkit`'s subsetting requires. Rendered documents are unchanged in what
   they draw: every drawn string is identical and every filled area lands in
   the same place, but the file's bytes differ, so a host comparing digests
   against stored output will see them move once.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Changed
+### Minor Changes
 
 - **A split slot's box now fills the split's height.** A slot's background and
   border stopped at that slot's own content and now take the split's height,
   the way a table cell's take their row's. See the `@quario/layout` changelog
   for the rule and for what it costs a report that relied on the short box.
-
 - **A date string under `format: "date"` now presents as a date.** The
   drawn text comes from the engine's `format()` helper, which revives the two
   read forms. See the `quario` changelog for the forms and the timezone rule.
-
-### Changed
-
 - **The layout moved to `@quario/layout`; this target paints its list.**
   Measurement, wrapping, pagination, page furniture, the marking's geometry
   and the page-size table now live in the layout package, which this target
@@ -112,16 +167,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   options are the layout's own, so the same object configures `pdf()`, the
   viewer and the editor. The font mapping's shape is now refused at the
   factory call rather than at render.
-
-### Fixed
-
 - **A nested group's footer keeps the page columns.** Inside a page-column
   region, the first footer of a group nested in it ended the region: the
   strips collapsed and every band after it was laid out across the page, as
   if `columns` were absent. Only the node that declared `columns` closes its
   own region now — a nested group's header and footer are region content,
   laid out in the strips.
-
 - **A padded or bordered item or row that breaks across a page keeps its
   box.** Content too tall for one page is drawn as slices, and a slice now
   carries the box sides the break left it — the top on the first, the bottom
@@ -133,60 +184,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the horizontal padding they were wrapped for, rather than flush to the
   column. **This changes output** for reports where such content breaks.
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Added
+### Minor Changes
 
 - **`format` stringifies at the edge from the instance locale.** A PDF
   without a host locale still uses `en-US` / UTC, so the bytes stay
   reproducible.
-
 - **A height-declared report header pins from the page top.** Leftover sits
   under the items; the next band starts at the pin. The half-line group gap
   drops after it. `page.margin` on the document is the inset when the host
   omits it; both is a render error.
-
 - **`spaceBefore` / `spaceAfter` skip the cursor.** Adjacent gaps add.
   `spaceBefore` drops at a fresh body page or strip top; page-band items
   keep it.
-
 - **The box is honoured in layout.** Padding and border inset wrap width; a
   named padding `0` beats the cell omakase (`PADX` 6 / `PADY` 2) on that
   side. Incomplete sides draw nothing.
-
-### Changed
-
 - **The last data row keeps the whole emitted total block.** A stack taller
   than a page degrades like a tall row.
-
 - **An unstyled table has no rules.** This target used to draw two 0.5 pt
   rules, under the header and above the total, that no declaration could
   ask for or refuse. Those strokes are gone. The strokes an author wants
   are the box they declared. Cell padding omakase stays on undeclared cell
   sides.
-
 - **A visible text item occupies a line at its own `size`, empty or not.** An
   empty or whitespace-only value used to sit at the report's base leading
   (~14 pt at the 10 pt baseline). It now occupies `1.4 ×` the item's size, the
   same as a glyph line. A literal newline is a line break; the blank line
   among `"a\n\nb"` is that size too. A table cell that is empty or only
   horizontal whitespace still has no content height.
-
-### Fixed
-
 - **A missing TrueType glyph draws as `?`, not `.notdef`.** Characters
   outside WinAnsi already substituted `?`; an embedded face's cmap holes
   drew a box instead, and text extraction hid it. Same rule for every
   face: a character the face cannot draw becomes `?`.
-
 - **CR, LF, and CRLF are one hard line break.** Cell text already broke
   on LF; a CRLF left a CR on the previous line, and a lone CR did not
   break. All three are now one break, matching `SCHEMA.md` Cell values.
   Wrapping still applies within each line.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Added
+### Minor Changes
 
 - **The report default sets the document's face and base size.** A report's
   top-level `style` replaces this target's own baseline, so its `size` scales
@@ -194,12 +233,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   nothing is set in. It is the layer _under_ the band-role defaults: a report
   declaring `size: 12` still renders its report header at 14, and an item's own
   style wins over both.
-
 - **`uppercase` draws capitals.** With no text-transform to defer to, this
   target capitalises the string before measuring it, so wrapping and column
   widths are those of the text actually drawn. The mapping is Unicode default
   case, never the host's locale, so output stays byte-reproducible.
-
 - **Splits lay out across the content width.** Each slot is measured and
   wrapped inside its own share, all slots draw from a common top, and the
   split takes the height of its tallest slot so the band below clears them
@@ -208,27 +245,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   any page renders in full past the bottom margin. The split's own style is
   the layer under each slot's, and its `background` fills the whole split
   behind them.
-
-### Changed
-
 - **A bare `Date` draws as ISO 8601 UTC, the same on every machine.** Cell
   text and outline bookmark titles for `Date` values used `String(date)`,
   which bakes the host's timezone and locale into the document — at odds with
   this target's byte-reproducibility guarantee. Both now render through the
   engine's shared display rule, so a `Date` group key titles its bookmark
   with the same ISO text its cells draw.
-
-### Removed
-
 - **`options.baseSize`.** A document's type size is the document's own, so it
   is the report's `style.size` — portable, travelling with the definition to
   every target — rather than a host option one target honoured. Text with
   nothing declared still renders at 10 points. Replace `pdf({ baseSize: 11 })`
   with `"style": { "size": 11 }` on the report.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **Paginated PDFs from the same compiled report.** The band flow places
   headers, groups, and tables; pdf-lib writes the file. Page furniture and an

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,27 +184,38 @@ 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/),
+with each declaration's fate in the
+[support matrix](https://getquario.com/docs/reference/support-matrix/).
+
+## Documentation
+
+[The quario documentation](https://getquario.com/docs/) is the reference.
+The [report schema](https://getquario.com/docs/reference/report-schema/) is the normative
+specification of what a report may declare, and
+[`@quario/pdf`](https://getquario.com/docs/reference/pdf/) is this package's own API.
+
 ## 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/lib/painter.js

@@ -80,6 +80,7 @@ let paintLine = ({ page, height }, op) =>
   });
 
 /** @type {(painter: Painter, op: any) => void} */
+// fallow-ignore-next-line code-duplication -- one operator path, so a face is embedded once per page; ink, baseline, rotation and opacity all differ, and the marking's draw stays its own
 let paintText = ({ page, height, fonts, faceKey }, op) => {
   let font = fontFor(fonts, op.font);
   page.pushOperators(
@@ -100,6 +101,7 @@ let paintText = ({ page, height, fonts, faceKey }, op) => {
 // face reuses the page's `faceKey` resource instead of growing the dictionary
 // per draw.
 /** @type {(painter: Painter, op: any) => void} */
+// fallow-ignore-next-line code-duplication -- one operator path, so a face is embedded once per page; ink, baseline, rotation and opacity all differ, and the marking's draw stays its own
 let paintMark = ({ page, height, fonts, faceKey }, op) => {
   let font = fontFor(fonts, op.font);
   page.pushOperators(
@@ -126,7 +128,7 @@ let paintMark = ({ page, height, fonts, faceKey }, op) => {
 // The embedders parse the bytes, and what they throw when those bytes are bad
 // says nothing an author could act on: a corrupt PNG used to reach a host as a
 // bare `RangeError: Invalid typed array length: 0`, naming no image and no
-// item (quario-e0bz). The engine vouched for the magic numbers and the layout
+// item (quario-e0bz). The engine vouched for the magic numbers and
 // read the size out of the header, so a file corrupt past that point arrives
 // here looking like any other and this is the first place that knows. The
 // embedder's own class and words survive behind the path, which is the shape

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/pdf",
-  "version": "0.7.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.4.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.7.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "fontkit": "^2.0.4",
-    "quario": "^0.7.0"
+    "quario": "^0.9.0"
   },
   "peerDependenciesMeta": {
     "fontkit": {