@quario/pdf 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,13 +7,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **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
+  depends on and runs first; pdf-lib writes the resulting display list. **The
+  move itself changed no output**, byte for byte, for the same input; the fix
+  below is a separate change and does move some. The `page` and `fonts`
+  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
+  on the last. Previously an item that overflowed lost its box entirely, so
+  the same declaration drew a border on short data and none on long; a
+  bordered table cell drew all four sides on every slice, putting an edge
+  across the middle of its own text; and a row's own border vanished when
+  the row was too tall for a page. A slice's lines are also drawn inside
+  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
 
 ### Added
 
 - **`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 (`docs/adr/0041`, `docs/adr/0025`).
+  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

package/README.md

@@ -3,8 +3,9 @@
 **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
+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
 in your container, no page-load race, no fonts-not-ready flake.
 
 ## Install
@@ -13,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.

package/lib/embed.js

@@ -0,0 +1,102 @@
+/**
+ * The faces a document can draw with, embedded before anything is painted.
+ *
+ * Every face is embedded on the document before the list is painted, so
+ * resolving a list op's face to a pdf-lib font is synchronous — pdf-lib's
+ * `embedFont` is async, and the paint is not. Embedding the twelve base-14
+ * faces up front costs under 200 bytes in the output, which is cheaper than a
+ * two-pass split to embed only what is used.
+ *
+ * The registry mirrors the layout's: the same family names, the same four
+ * 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 "@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: variants("Helvetica", "Oblique"),
+  serif: variants("TimesRoman", "Italic"),
+  mono: variants("Courier", "Oblique"),
+};
+
+/** @typedef {{ families: Record<string, any[]> }} Fonts */
+
+// Host-supplied TrueType families need a font parser, which is an optional
+// peer: base-14 reports install nothing extra. Loaded only when `fonts` is
+// passed, and a missing package is reported as what it is.
+/** @type {(doc: any) => Promise<void>} */
+let useFontkit = async (doc) => {
+  let fontkit;
+  try {
+    fontkit = await import("fontkit");
+  } catch {
+    throw Error("options.fonts: install fontkit to embed TrueType families");
+  }
+  doc.registerFontkit(fontkit);
+};
+
+/** @type {(doc: any) => Promise<Record<string, any[]>>} */
+let embedBase = async (doc) => {
+  /** @type {Record<string, any[]>} */
+  let families = {};
+  for (let [name, variants] of Object.entries(BASE))
+    families[name] = await Promise.all(variants.map((v) => doc.embedFont(v)));
+  return families;
+};
+
+/** @type {(doc: any, src: any, path: string, variant: string) => Promise<any>} */
+let embedOne = async (doc, src, path, variant) => {
+  try {
+    return await doc.embedFont(src[variant], { subset: true });
+  } catch (e) {
+    throw Error(path + "." + variant + ": " + /** @type {Error} */ (e).message);
+  }
+};
+
+// Missing variants fall back to the family's regular, so a face is always
+// resolvable once the family is named. The shape was checked at the layout's
+// factory call; this only embeds.
+/** @type {(doc: any, name: string, def: any) => Promise<any[]>} */
+let familyOf = async (doc, name, def) => {
+  let path = "options.fonts." + name;
+  /** @type {any[]} */
+  let faces = [];
+  for (let variant of ["regular", "bold", "italic", "boldItalic"])
+    faces.push(def[variant] == null ? faces[0] : await embedOne(doc, def, path, variant));
+  return faces;
+};
+
+/** @type {(doc: any, custom: any, families: Record<string, any[]>) => Promise<void>} */
+let embedCustom = async (doc, custom, families) => {
+  if (!(custom && Object.keys(custom).length)) return;
+  await useFontkit(doc);
+  for (let [name, def] of Object.entries(custom))
+    families[name.toLowerCase()] = await familyOf(doc, name, def);
+};
+
+/**
+ * Embed every face the list can name and return the registry the painter
+ * reads.
+ *
+ * @param {any} doc The pdf-lib document.
+ * @param {any} custom `options.fonts`, or null.
+ * @returns {Promise<Fonts>}
+ */
+export async function embedFonts(doc, custom) {
+  let families = await embedBase(doc);
+  await embedCustom(doc, custom, families);
+  return { families };
+}
+
+/**
+ * The embedded font one list op names.
+ *
+ * @type {(fonts: Fonts, ref: { family: string, variant: number }) => any}
+ */
+export let fontFor = (fonts, ref) => fonts.families[ref.family][ref.variant];

package/lib/index.d.ts

@@ -1,12 +1,8 @@
+import type { LayoutFontFamily, LayoutPage } from "@quario/layout";
 import type { Target } from "quario";
 
-/** Page geometry, in PostScript points. Target configuration, never schema. */
-export interface PdfPage {
-  /** Named size or `[width, height]` in points. Default `'A4'`. */
-  size?: "A4" | "letter" | [number, number];
-  /** Margin on all four sides, in points. Default `54` (0.75 in). */
-  margin?: number;
-}
+/** Page geometry, in PostScript points: the layout's own, never schema. */
+export type PdfPage = LayoutPage;
 
 /** Optional document information; never includes dates, so output stays deterministic. */
 export interface PdfMeta {
@@ -15,13 +11,8 @@ export interface PdfMeta {
   subject?: string;
 }
 
-/** One embeddable TrueType family; missing variants fall back to `regular`. */
-export interface PdfFontFamily {
-  regular: Uint8Array | ArrayBuffer;
-  bold?: Uint8Array | ArrayBuffer;
-  italic?: Uint8Array | ArrayBuffer;
-  boldItalic?: Uint8Array | ArrayBuffer;
-}
+/** 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. */
 export interface PdfOptions {
@@ -30,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

@@ -1,102 +1,28 @@
 /**
  * @quario/pdf — the PDF render target: a pure consumer of the engine's public
- * event stream, passed to a compiled report's `render`, laying the banded walk out on
- * pages. Layout is ours — wrapped paragraphs, keep-together, repeated table
- * headers, page bands, `break: "page"`, `reset: "page"` — while the writing is pdf-lib's, so
- * this target carries a typesetter rather than a PDF implementation. Output
- * is deterministic: the document carries no dates of its own, so the same
- * input renders the same bytes. Page size is target configuration
+ * event stream, passed to a compiled report's `render`. The layout is
+ * `@quario/layout`'s — one paged display list, the same one the viewer paints
+ * on screen (docs/adr/0039) — and **pdf-lib writes the file**, so this target
+ * is a painter of that list rather than a typesetter or a PDF implementation.
+ * Output is deterministic: the document carries no dates of its own, so the
+ * same input renders the same bytes. Page size is target configuration
  * (`pdf({ page.size })`); `page.margin` may also be a document field.
  *
- * This file is options, fonts and geometry, the walk itself, and the passes
- * that follow it over the finished pages — page furniture and the marking,
- * neither of which can be drawn until the page count is known. Every handler
- * the driver dispatches to is the band flow's, next door in `layout.js`; this
- * file adds none. The work lives in the sibling modules, which ship beside it
- * — the package publishes `lib/` verbatim.
+ * This file is options, the layout pass, and the document: faces embedded,
+ * pages painted, the group tree attached as bookmarks. The work lives in the
+ * sibling modules, which ship beside it — the package publishes `lib/`
+ * verbatim.
  */
-import { PDFDocument } from "pdf-lib";
-import { breathe, walk } from "quario";
-import { drawing, frame, stamp } from "./canvas.js";
-import { embedFonts } from "./fonts.js";
-import { flow, furniture } from "./layout.js";
+import { PDFDocument } from "@cantoo/pdf-lib";
+import { layout } from "@quario/layout";
+import { embedFonts } from "./embed.js";
 import { outline } from "./outline.js";
+import { paint } from "./painter.js";
 
 // The options are described once, in the hand-written public declarations, and
 // read back here — a second copy in JSDoc is a copy that drifts.
 /** @import { PdfOptions } from './index.d.ts' */
 
-let SIZES = /** @type {Record<string, [number, number]>} */ ({
-  A4: [595.28, 841.89],
-  letter: [612, 792],
-});
-
-/** @type {(msg: string) => never} */
-let err = (msg) => {
-  throw Error(msg);
-};
-
-/** @type {(value: number) => boolean} */
-let positive = (value) => Number.isFinite(value) && value > 0;
-
-/** @type {(size: any) => any} */
-let named = (size = "A4") => {
-  let dimensions = Array.isArray(size) ? size : SIZES[size];
-  // oxlint-disable-next-line no-unused-expressions
-  dimensions || err('options.page.size: unknown page size "' + size + '"');
-  return dimensions;
-};
-
-/** @type {(dimensions: any) => { width: number, height: number }} */
-let pair = (dimensions) => {
-  let width = +dimensions[0],
-    height = +dimensions[1];
-  // oxlint-disable-next-line no-unused-expressions
-  (positive(width) && positive(height)) ||
-    err("options.page.size: expected finite positive dimensions");
-  return { width, height };
-};
-
-/** @type {(margin: any, width: number, height: number, path?: string) => number} */
-let marginOf = (margin = 54, width, height, path = "options.page.margin") => {
-  let fits = Number.isFinite(margin) && margin >= 0 && 2 * margin < Math.min(width, height);
-  // oxlint-disable-next-line no-unused-expressions
-  fits || err(path + ": expected a non-negative number smaller than half the page");
-  return margin;
-};
-
-// This target's baseline type size. Not a host option: a document's type size
-// is the document's own, so it is `style.size` on the report and the number
-// here is only what text renders at when nothing declares one. The XLSX target
-// carries the same 10 for the same reason (docs/adr/0014, docs/adr/0033).
-let BASE = 10;
-
-// The page box and the content box in one. Size is settled at the factory;
-// margin may come from the document's `report-start`, so a render peeks that
-// event before opening a canvas.
-/** @type {(page: any) => any} */
-let hostMargin = (page) => (Object.hasOwn(page, "margin") ? page.margin : undefined);
-/** @type {(opening: any) => any} */
-let docMargin = (opening) => opening?.margin;
-/** @type {(doc: any, host: any) => boolean} */
-let bothMargins = (doc, host) => doc != null && host !== undefined;
-/** @type {(fromDoc: boolean) => string} */
-let marginPath = (fromDoc) => (fromDoc ? "page.margin" : "options.page.margin");
-/** @type {(opening: any, page: any) => { value: any, path: string }} */
-let marginChoice = (opening, page) => {
-  let host = hostMargin(page);
-  let doc = docMargin(opening);
-  if (bothMargins(doc, host)) err("page.margin: document and target both declare a margin");
-  return { value: doc ?? host, path: marginPath(doc != null) };
-};
-/** @type {(options: any, opening?: any) => import('./canvas.js').Frame} */
-let geometry = (options, opening) => {
-  let { page = {} } = options ?? {};
-  let { width, height } = pair(named(page.size));
-  let chosen = marginChoice(opening, page);
-  return frame(width, height, marginOf(chosen.value, width, height, chosen.path), BASE);
-};
-
 // 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,
@@ -115,27 +41,11 @@ let describe = (doc, meta) => {
   }
 };
 
-/** @type {(canvas: import('./canvas.js').Drawing, draw: (i: number) => void) => Promise<void>} */
-let overPages = async (canvas, draw) => {
-  for (let i = 0; i < canvas.count; i++) {
-    canvas.select(i);
-    draw(i);
-    if (i % 50 === 49) await breathe();
-  }
-};
-
-/** @type {(canvas: import('./canvas.js').Drawing, bands: any,
- *   pages: { number: number, total: number }[]) => Promise<void>} */
-let furnish = async (canvas, bands, pages) => {
-  if (!bands) return;
-  await overPages(canvas, (i) => furniture(canvas, bands, pages[i]));
-};
-
-/** @type {(canvas: import('./canvas.js').Drawing, marking: any) => Promise<void>} */
-let markPages = async (canvas, marking) => {
-  if (!marking) return;
-  let mark = stamp(canvas, marking);
-  await overPages(canvas, () => canvas.watermark(mark));
+/** @type {(meta: any, custom: any) => Promise<{ doc: any, fonts: import('./embed.js').Fonts }>} */
+let open = async (meta, custom) => {
+  let doc = await PDFDocument.create();
+  describe(doc, meta);
+  return { doc, fonts: await embedFonts(doc, custom) };
 };
 
 /**
@@ -143,57 +53,29 @@ let markPages = async (canvas, marking) => {
  * `quario().report(schema).render(pdf({ page }), data)` resolves the
  * complete document as a `Uint8Array` (the host writes the file). Rendering
  * hands the loop back between event and page batches, so large reports stay
- * cooperative. Geometry and options are validated here, at the factory call.
+ * cooperative. Geometry and the font mapping are validated here, at the
+ * factory call — by the layout target, whose options they are.
  *
  * @param {PdfOptions} [options] Host controls (see SCHEMA.md, "The PDF target").
  * @returns {{name: "pdf", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function pdf(options) {
-  geometry(options);
-  let meta = options?.meta,
-    custom = options?.fonts;
+  let { page, fonts: custom, meta } = options ?? {};
+  let paged = layout({ page, fonts: custom });
   /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
-  let compile = (stream) => async (data) => {
-    let doc = await PDFDocument.create();
-    describe(doc, meta);
-    // Every face is embedded before the walk, so resolving a style to a
-    // font during layout stays synchronous.
-    let fonts = await embedFonts(doc, custom);
-    let gen = stream(data);
-    let first = gen.next();
-    let geo = geometry(options, first.done ? null : first.value);
-    let canvas = drawing(doc, geo, fonts);
-    // The band flow owns the placement state and every handler over it, and
-    // opens the first page as it is built; this file only hands it the stream.
-    let { handlers, finish } = flow(canvas);
-    function* events() {
-      if (!first.done) yield first.value;
-      yield* gen;
-    }
-    await walk(events(), handlers);
-    // The flow settled the opening event on its way past — it reserves the
-    // page bands off it — and hands it back with the marks. What is left on it
-    // is what the passes below want: the band closures to render per page, and
-    // the marking's wording to stamp.
-    // Null when nothing settled one, which reads as a document owing neither.
-    let { marks, opening, pages } = finish();
-    opening = opening || {};
-    // The passes below run over the finished pages, not the stream — no walk
-    // at all — so they open each page themselves and breathe on their own
-    // rather than through the driver.
-    await furnish(canvas, opening.page, pages);
-    // Every image the walk and the furniture pass placed, embedded and drawn
-    // now: a walk handler cannot await, and the page bands' images are not
-    // placed until the pass above has run. Before the marking, so an image can
-    // never cover it.
-    await canvas.pictures();
-    // The unlicensed marking goes on last, over content and page furniture
-    // alike, once per page (LICENSE section 6). Its wording rode in on
-    // `report-start`; only the placement is this target's.
-    await markPages(canvas, opening.marking);
-    outline(doc, marks, canvas.refs);
-    return doc.save();
+  let compile = (stream) => {
+    let lay = paged.compile(stream);
+    return async (data) => {
+      // The list measures against its own faces, so the document is written
+      // from the same breaks the preview shows; opening the document and
+      // embedding its faces depend on nothing the list decides, so they
+      // overlap the layout pass.
+      let [list, { doc, fonts }] = await Promise.all([lay(data), open(meta, custom)]);
+      let refs = await paint(doc, fonts, list);
+      outline(doc, list.marks, refs);
+      return doc.save();
+    };
   };
   return { name: "pdf", compile };
 }

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.