@quario/pdf 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- **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
+  rendered `0.123`; `format: "percent"` on `0.21` renders `21.00%` where it
+  rendered `21%`. `format: "currency"` follows the currency's own minor units,
+  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,
+  naming neither an image nor an item, so a report with two pictures gave no
+  way to tell which was at fault. The message now begins with the item's
+  `source` path and says the image could not be embedded, keeping the writer's
+  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
+
+### Added
+
+- **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
+  slices across pages or page-column strips follows the geometry of the strip
+  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
+  face needing a shaping state machine — which is every Devanagari, Bengali,
+  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
 
 ### Changed

package/README.md

@@ -5,7 +5,7 @@ definition straight to a paginated PDF. No headless browser, no print CSS, deter
 
 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. [pdf-lib](https://pdf-lib.js.org) writes the file. You get typesetting plus pdf-lib: no Chromium
+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,13 +14,13 @@ in your container, no page-load race, no fonts-not-ready flake.
 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
+`@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.
 
 Embedding TrueType fonts also needs the optional peer:
 
 ```bash
-npm install @pdf-lib/fontkit
+npm install fontkit
 ```
 
 It loads only when you pass `fonts` to the factory. The base-14 families need nothing extra.
@@ -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, so
-`=page.total > 10` reserves nothing. `page.total` is fine in band _text_.
+`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.total` is fine in band _text_.
 
 ## API
 
@@ -85,7 +86,9 @@ host. Render-time failures reject with located errors.
 
 ### Options
 
-Page geometry is target configuration, never schema:
+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.
 
 ```js
 {
@@ -96,7 +99,7 @@ Page geometry is target configuration, never schema:
 ```
 
 `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
+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
 largest font size.
@@ -105,12 +108,12 @@ largest font size.
 
 **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.
+- 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.
 - 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.
+- The total rows keep the last data row with them.
 - 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.
@@ -119,17 +122,32 @@ largest font size.
   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
+  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`
+  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
+  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
+  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.
 - 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
+**Best-effort** current implementation, pinned only as a regression guard where the layout suite
+holds it, and changeable without a breaking change: paragraph widow and orphan avoidance, the
+gutter between page-column strips and whether a region balances, 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
+indentation, but every instance that draws opens with a structural half-line gap so groups read as blocks
 without authored margins.
 
 ## Fonts and text
@@ -153,7 +171,9 @@ const target = pdf({
 
 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.
+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
+the parser cannot read reject the render, located at the same option path.
 
 ## Outline
 
@@ -175,8 +195,8 @@ per-page presence is normative; exact geometry is best-effort. A licensed render
 
 ## 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.
+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.
 
 ## License
 

package/lib/embed.js

@@ -11,27 +11,18 @@
  * variants indexed by `bold + 2 * italic`, a missing variant falling back to
  * the family's regular — so a `FaceRef` on the list names one font here.
  */
-import { StandardFonts } from "pdf-lib";
+import { StandardFonts } from "@cantoo/pdf-lib";
 
+// A family's four names are one stem plus the weight and slant suffixes that
+// family spells, so each family names its two and the four are walked out of
+// them rather than written twelve times over.
+/** @type {(stem: string, slant: string) => string[]} */
+let variants = (stem, slant) =>
+  ["", "Bold", slant, "Bold" + slant].map((v) => /** @type {any} */ (StandardFonts)[stem + v]);
 let BASE = {
-  sans: [
-    StandardFonts.Helvetica,
-    StandardFonts.HelveticaBold,
-    StandardFonts.HelveticaOblique,
-    StandardFonts.HelveticaBoldOblique,
-  ],
-  serif: [
-    StandardFonts.TimesRoman,
-    StandardFonts.TimesRomanBold,
-    StandardFonts.TimesRomanItalic,
-    StandardFonts.TimesRomanBoldItalic,
-  ],
-  mono: [
-    StandardFonts.Courier,
-    StandardFonts.CourierBold,
-    StandardFonts.CourierOblique,
-    StandardFonts.CourierBoldOblique,
-  ],
+  sans: variants("Helvetica", "Oblique"),
+  serif: variants("TimesRoman", "Italic"),
+  mono: variants("Courier", "Oblique"),
 };
 
 /** @typedef {{ families: Record<string, any[]> }} Fonts */
@@ -43,9 +34,9 @@ let BASE = {
 let useFontkit = async (doc) => {
   let fontkit;
   try {
-    fontkit = (await import("@pdf-lib/fontkit")).default;
+    fontkit = await import("fontkit");
   } catch {
-    throw Error("options.fonts: install @pdf-lib/fontkit to embed TrueType families");
+    throw Error("options.fonts: install fontkit to embed TrueType families");
   }
   doc.registerFontkit(fontkit);
 };

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import type { LayoutFontFamily, LayoutPage } from "@quario/layout";
 import type { Target } from "quario";
 
-/** Page geometry, in PostScript points: the layout's own, never schema. */
+/** Page geometry, in PostScript points: the layout's own, its margin one a document may declare instead. */
 export type PdfPage = LayoutPage;
 
 /** Optional document information; never includes dates, so output stays deterministic. */
@@ -21,7 +21,7 @@ export interface PdfOptions {
   /**
    * TrueType families to embed (subset), selected from styles by
    * `family: '<name>'`. Fonts are trusted host assets. Requires the optional
-   * peer `@pdf-lib/fontkit`; the base-14 families need nothing extra.
+   * peer `fontkit`; the base-14 families need nothing extra.
    */
   fonts?: Record<string, PdfFontFamily>;
 }

package/lib/index.js

@@ -13,7 +13,7 @@
  * sibling modules, which ship beside it — the package publishes `lib/`
  * verbatim.
  */
-import { PDFDocument } from "pdf-lib";
+import { PDFDocument } from "@cantoo/pdf-lib";
 import { layout } from "@quario/layout";
 import { embedFonts } from "./embed.js";
 import { outline } from "./outline.js";

package/lib/outline.js

@@ -7,7 +7,7 @@
  * own position. pdf-lib has no bookmark API, so the objects are built through
  * its low-level context — the only place in this target that does.
  */
-import { PDFHexString, PDFName, PDFNumber } from "pdf-lib";
+import { PDFHexString, PDFName, PDFNumber } from "@cantoo/pdf-lib";
 
 // A PDF *text string*: UTF-16BE with a BOM, so a title survives whatever the
 // author wrote. `PDFHexString.fromText` encodes exactly that.

package/lib/painter.js

@@ -9,12 +9,12 @@
  * and one logo on every page is embedded once, the marking after them so an
  * image can never cover it (LICENSE section 6).
  */
-import { breathe } from "quario";
-import { degrees, drawImage, drawText, rgb } from "pdf-lib";
+import { breathe, imageError } from "quario";
+import { degrees, drawImage, drawText, rgb } from "@cantoo/pdf-lib";
 import { fontFor } from "./embed.js";
 
-/** @typedef {import('pdf-lib').PDFPage} PDFPage */
-/** @typedef {import('pdf-lib').PDFName} PDFName */
+/** @typedef {import('@cantoo/pdf-lib').PDFPage} PDFPage */
+/** @typedef {import('@cantoo/pdf-lib').PDFName} PDFName */
 
 // The operator builder wants explicit rotation and skew; report text has none.
 let NO_TURN = degrees(0);
@@ -122,11 +122,45 @@ let paintMark = ({ page, height, fonts, faceKey }, op) => {
 
 // Keyed by the array the source expression yielded, so one logo reused
 // across pages is embedded once and every placement references it.
+//
+// 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
+// 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
+// SCHEMA.md documents for every render error.
+//
+// **What this cannot promise is symmetry between the two formats.** pdf-lib's
+// PNG embedder decompresses the pixel data, while its JPEG embedder reads
+// markers alone and never the scan data, so a JPEG corrupt past its frame
+// header embeds without complaint and arrives here as no failure at all.
+// Corrupt scan data cannot be told from good without decoding the image, which
+// is not a cost a render should pay to find out what it is about to write.
+//
+// Closing part of the gap was weighed and declined (`quario-dqt8`). A JPEG
+// carrying no `SOS` at all is structural, as cheap to read as the size, so the
+// marker walk in `@quario/layout`'s `image.js` could say so — but measuring
+// what that catches settled it: a JPEG's headers are roughly fixed while its
+// scan grows with the image, so the check covers truncation only up to the
+// point the scan starts. On the 882-byte `logo.jpg` fixture that is 85% of the
+// file; on a photograph it is a fraction of a percent, and every truncation
+// worth worrying about lands past it. What it would buy is the shape of a
+// hand-built repro; what it would cost an author is a rule whose seam falls in
+// an arbitrary place — a JPEG whose scan never starts fails, one whose scan is
+// cut does not — and the PNG/JPEG asymmetry survives either way. So the line
+// stays where the engine's own guarantee stops.
 /** @type {(painter: Painter, op: any) => Promise<any>} */
 let imageOf = async ({ doc, embedded }, op) => {
   let image = embedded.get(op.bytes);
   if (!image) {
-    image = await (op.format === "png" ? doc.embedPng(op.bytes) : doc.embedJpg(op.bytes));
+    try {
+      image = await (op.format === "png" ? doc.embedPng(op.bytes) : doc.embedJpg(op.bytes));
+    } catch (cause) {
+      let said = /** @type {Error} */ (cause).message;
+      throw imageError(op.path, "the image could not be embedded: " + said, cause);
+    }
     embedded.set(op.bytes, image);
   }
   return image;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/pdf",
-  "version": "0.4.0",
+  "version": "0.6.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,23 +36,24 @@
     "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
   },
   "dependencies": {
-    "@quario/layout": "^0.1.0",
-    "pdf-lib": "^1.17.1"
+    "@cantoo/pdf-lib": "^2.9.1",
+    "@quario/layout": "^0.3.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
-    "@pdf-lib/fontkit": "^1.1.1",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.4.0",
+    "@types/fontkit": "^2.0.9",
+    "fontkit": "^2.0.4",
+    "quario": "^0.6.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "@pdf-lib/fontkit": "^1.1.1",
-    "quario": "^0.4.0"
+    "fontkit": "^2.0.4",
+    "quario": "^0.6.0"
   },
   "peerDependenciesMeta": {
-    "@pdf-lib/fontkit": {
+    "fontkit": {
       "optional": true
     }
   },
@@ -62,7 +63,7 @@
       "ignore": [
         "quario",
         "@quario/layout",
-        "pdf-lib"
+        "@cantoo/pdf-lib"
       ],
       "limit": "6 kB"
     }