@quario/pdf 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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`).
+
+- **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
 
 ### Added

package/README.md

@@ -135,8 +135,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 outside WinAnsi render as `?` rather than failing the report, because cell
-text is untrusted data and one stray character must not take a document down.
+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.
 
 For full Unicode, supply TrueType families and select them by name:
 

package/lib/box.js

@@ -0,0 +1,111 @@
+/**
+ * The box model this target honours: per-side padding and border, border-box,
+ * no collapse. Cell omakase (PADX / PADY) applies only where the author named
+ * no padding on that side; a named 0 wins. A border side contributes only when
+ * width, style and colour all resolve and width is positive — an incomplete
+ * result at render is nothing, not a solid black stroke.
+ */
+import { PADX, PADY, col } from "./style.js";
+
+let SIDES = ["Top", "Right", "Bottom", "Left"];
+/** @type {Record<string, number[] | null>} */
+let DASH = { solid: null, dashed: [3, 2], dotted: [1, 1.5] };
+
+/** @typedef {{ t: number, r: number, b: number, l: number }} Inset */
+
+/** @type {Inset} */
+let CELL_PAD = { t: PADY, r: PADX, b: PADY, l: PADX };
+/** @type {Inset} */
+let NO_PAD = { t: 0, r: 0, b: 0, l: 0 };
+
+/** @type {(name: string) => boolean} */
+let isBox = (name) => name.startsWith("padding") || name.startsWith("border");
+
+/** @type {(style: any) => any} */
+let unbox = (style) => {
+  if (!style) return style;
+  let names = Object.keys(style).filter((name) => !isBox(name));
+  if (!names.length) return null;
+  return Object.fromEntries(names.map((name) => [name, style[name]]));
+};
+
+/** @type {(style: any, side: string, fallback: number) => number} */
+let padOf = (style, side, fallback) => {
+  let value = style?.["padding" + side];
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+};
+
+/** @type {(width: any) => boolean} */
+let isStroke = (width) => Number.isFinite(width) && width > 0;
+/** @type {(line: any) => boolean} */
+let isLine = (line) => typeof line === "string" && Object.hasOwn(DASH, line);
+
+/**
+ * @type {(width: any, line: any, color: any) =>
+ *   { width: number, dash: number[] | null, color: any } | null}
+ */
+let strokeOf = (width, line, color) => {
+  if (!isStroke(width) || !isLine(line) || !color) return null;
+  return { width, dash: DASH[line], color };
+};
+
+/**
+ * @type {(style: any, side: string) =>
+ *   { width: number, dash: number[] | null, color: any } | null}
+ */
+let edgeOf = (style, side) => {
+  if (!style) return null;
+  return strokeOf(
+    style["border" + side + "Width"],
+    style["border" + side + "Style"],
+    col(style["border" + side + "Color"]),
+  );
+};
+
+/** @type {(style: any, side: string) => number} */
+let thick = (style, side) => {
+  let edge = edgeOf(style, side);
+  return edge ? edge.width : 0;
+};
+
+/** @type {(style: any, side: string, fallback: number) => number} */
+let inset = (style, side, fallback) => padOf(style, side, fallback) + thick(style, side);
+
+/** @type {(style: any, omakase: Inset) => Inset} */
+let insetOf = (style, omakase) => ({
+  t: inset(style, "Top", omakase.t),
+  r: inset(style, "Right", omakase.r),
+  b: inset(style, "Bottom", omakase.b),
+  l: inset(style, "Left", omakase.l),
+});
+
+/** Endpoints of one inner-centred edge, as stroke() takes them. */
+/** @type {Record<string, (x: number, yTop: number, w: number, h: number, half: number) => number[]>} */
+let SPAN = {
+  Top: (x, yTop, w, _h, half) => [x, yTop - half, x + w, yTop - half],
+  Bottom: (x, yTop, w, h, half) => [x, yTop - h + half, x + w, yTop - h + half],
+  Left: (x, yTop, _w, h, half) => [x + half, yTop, x + half, yTop - h],
+  Right: (x, yTop, w, h, half) => [x + w - half, yTop, x + w - half, yTop - h],
+};
+
+/** @type {(canvas: { stroke: Function }, x: number, yTop: number, w: number, h: number, style: any, side: string) => void} */
+let paintEdge = (canvas, x, yTop, w, h, style, side) => {
+  let edge = edgeOf(style, side);
+  if (!edge) return;
+  canvas.stroke(...SPAN[side](x, yTop, w, h, edge.width / 2), edge.width, edge.color, edge.dash);
+};
+
+/**
+ * Fill and stroke one border-box. Background is the whole rect; each edge
+ * sits inside it, centred on its own width, so a stroke does not spill past
+ * the box the caller measured.
+ *
+ * @type {(canvas: { rect: Function, stroke: Function }, x: number, yTop: number,
+ *   w: number, h: number, style: any, bg: any) => void}
+ */
+let paintBox = (canvas, x, yTop, w, h, style, bg) => {
+  if (bg) canvas.rect(bg, x, yTop - h, w, h);
+  if (style) for (let side of SIDES) paintEdge(canvas, x, yTop, w, h, style, side);
+};
+
+export { CELL_PAD, NO_PAD, insetOf, paintBox, unbox };

package/lib/canvas.js

@@ -25,30 +25,36 @@ let NO_TURN = degrees(0);
 
 // The page box and the content box. Settled at `report-start` and fixed
 // thereafter: the geometry is the factory's and never moves, while `base` and
-// `style` take the report default one event into the render, before anything is
-// measured. The page bands are measured against the page box and take their
+// `family` take the report default one event into the render, before anything
+// is measured. The page bands are measured against the page box and take their
 // height off `top`/`bottom` through `adopt` below, while the first page is
 // still untouched.
 /**
- * `style` is the report default — the outermost style layer, resolved once per
- * render from `report-start` and carried here so a measuring canvas built off
- * this frame reads the same one the drawing canvas does. Null when the report
+ * `family` is the report default's typeface, normalised, and `base` its size —
+ * the two declarations that default is narrowed to. They ride the frame so a
+ * measuring canvas built off it reads the same pair the drawing canvas does,
+ * and so the default reaches a node as a fallback rather than a merged layer;
+ * `layout.js`'s `adoptDefault` carries why. `family` is null when the report
  * declares none.
  *
  * @typedef {{ width: number, height: number, margin: number, base: number,
- *   content: number, top: number, bottom: number, style: any }} Frame
+ *   content: number, top: number, bottom: number, family: string | null,
+ *   locale?: string, currency?: string, timeZone?: string }} Frame
  */
 
 // A frame from the page box and the base size: how `content`/`top`/`bottom`
 // fall out of a page and a margin is derived here, once, so no caller and no
 // suite has to restate it and drift from what a real render uses.
-/** @type {(width: number, height: number, margin: number, base: number, style?: any) => Frame} */
-let frame = (width, height, margin, base, style = null) => ({
+/**
+ * @type {(width: number, height: number, margin: number, base: number,
+ *   family?: string | null) => Frame}
+ */
+let frame = (width, height, margin, base, family = null) => ({
   width,
   height,
   margin,
   base,
-  style,
+  family,
   content: width - 2 * margin,
   top: height - margin,
   bottom: margin,
@@ -60,7 +66,8 @@ let frame = (width, height, margin, base, style = null) => ({
  * @typedef {Frame & Metrics & { y: number, fresh: boolean, count: number,
  *   newPage: () => void,
  *   rect: (color: any, x: number, y: number, w: number, h: number) => void,
- *   rule: (x1: number, x2: number, y: number) => void,
+ *   stroke: (x1: number, y1: number, x2: number, y2: number, thickness: number,
+ *     color: any, dash: number[] | null) => void,
  *   picture: (bytes: Uint8Array, format: string, x: number, y: number,
  *     w: number, h: number) => void,
  *   drawLine: (line: Line, x: number, yTop: number, avail: number,
@@ -210,9 +217,15 @@ let drawing = (doc, box, fonts) => {
     }
   };
 
-  /** @type {Canvas['rule']} */
-  let rule = (x1, x2, y) =>
-    page.drawLine({ start: { x: x1, y }, end: { x: x2, y }, thickness: 0.5, color: BLACK });
+  /** @type {Canvas['stroke']} */
+  let stroke = (x1, y1, x2, y2, thickness, color, dash) =>
+    page.drawLine({
+      start: { x: x1, y: y1 },
+      end: { x: x2, y: y2 },
+      thickness,
+      color,
+      ...(dash ? { dashArray: dash, dashPhase: 0 } : {}),
+    });
 
   /** @type {(piece: Line['pieces'][number], x: number, y: number) => void} */
   let writePiece = (piece, x, y) => {
@@ -284,7 +297,7 @@ let drawing = (doc, box, fonts) => {
     },
     newPage,
     rect,
-    rule,
+    stroke,
     picture,
     pictures,
     drawLine,
@@ -316,7 +329,7 @@ let measuring = (box, fonts) => ({
     throw new Error("probe reached newPage: the measuring path must not paginate");
   },
   rect: MARKS_NOTHING,
-  rule: MARKS_NOTHING,
+  stroke: MARKS_NOTHING,
   picture: MARKS_NOTHING,
   drawLine: MARKS_NOTHING,
 });

package/lib/fonts.js

@@ -115,22 +115,43 @@ export async function embedFonts(doc, custom) {
   return { families };
 }
 
+// What a declared `family` normalises to before it is looked up: lower case,
+// and nothing at all when the value is not a name. Exported because the report
+// default is normalised once per render rather than once per cell, and two
+// spellings of this would drift.
 /** @type {(style: any) => string} */
-let familyName = (style) => (typeof style.family === "string" ? style.family.toLowerCase() : "");
+export let familyName = (style) =>
+  typeof style.family === "string" ? style.family.toLowerCase() : "";
 
 // Own-key lookup: the family name is render data, so `constructor` must
 // fall back to sans rather than resolve an inherited member.
-/** @type {(fonts: Fonts, name: string) => any[]} */
+/** @type {(fonts: Fonts, name: string | null) => any[]} */
 let variantsOf = (fonts, name) =>
-  Object.hasOwn(fonts.families, name) ? fonts.families[name] : fonts.families.sans;
+  name && Object.hasOwn(fonts.families, name) ? fonts.families[name] : fonts.families.sans;
 
 /** @type {(style: any) => number} */
 let faceIndex = (style) => (style.bold ? 1 : 0) | (style.italic ? 2 : 0);
 
-// Resolve a style block to one embedded face.
-/** @type {(fonts: Fonts, style: any) => any} */
-export function face(fonts, style) {
-  return variantsOf(fonts, familyName(style))[faceIndex(style)];
+/**
+ * Resolve a style block to one embedded face.
+ *
+ * `fallback` is the report default's family, which the canvas carries for the
+ * whole render (docs/adr/0033) — so text declaring no family is set in the
+ * document's.
+ *
+ * The fallback turns on whether a family was *declared*, never on whether the
+ * declared one resolves: a literal `family` is a non-empty string by the time
+ * the engine passes it, but an `=` expression is resolved at render and
+ * reaches here unchecked, so an item can declare `""`, a number or `null`.
+ * Those are the item's own declaration and fall to sans like any other name
+ * this target cannot resolve (SCHEMA.md) — the document's family is for text
+ * that declared none. Own-key, because the block is render data.
+ *
+ * @type {(fonts: Fonts, style: any, fallback: string | null) => any}
+ */
+export function face(fonts, style, fallback) {
+  let declared = Object.hasOwn(style, "family");
+  return variantsOf(fonts, declared ? familyName(style) : fallback)[faceIndex(style)];
 }
 
 // The distance from a line's top to its baseline: pdf-lib's ascender, which
@@ -143,38 +164,60 @@ export let ascOf = (font, size) => font.heightAtSize(size, { descender: false })
 /** @type {(font: any, text: string, size: number) => number} */
 export let width = (font, text, size) => font.widthOfTextAtSize(text, size);
 
-// Printable ASCII, which every face encodes and which almost all report text
-// is. Asking the face instead costs a full measurement per atom.
+// Printable ASCII, which every text face encodes and which almost all report
+// text is. Asking the cmap instead costs a set walk per atom.
 let ASCII = /^[\x20-\x7E]*$/;
 
+// pdf-lib's getCharacterSet() is the cmap for both kinds of face: WinAnsi
+// code points on the base-14, fontkit's characterSet on an embedded TTF.
+// widthOfTextAtSize does not throw on a TrueType .notdef, so the old probe
+// let cmap holes through as glyph id 0. A face with no cmap (the layout
+// suite's measuring doubles) does not substitute: width is its whole contract.
+let CHARSETS = new WeakMap();
+let OPEN = { has: () => true };
+
+/** @typedef {{ has: (code: number) => boolean }} Cmap */
+
+/** @type {(font: any) => Cmap} */
+let charsetOf = (font) => {
+  let set = CHARSETS.get(font);
+  if (set) return set;
+  set = typeof font.getCharacterSet === "function" ? new Set(font.getCharacterSet()) : OPEN;
+  CHARSETS.set(font, set);
+  return set;
+};
+
 /**
- * Replace characters a face cannot encode with `?`.
+ * Replace characters a face cannot draw with `?`.
  *
- * The base-14 faces are WinAnsi and pdf-lib refuses anything outside it. Cell
- * text is untrusted data, so one stray character must not fail the render:
- * SCHEMA.md promises `?`, and full Unicode through `options.fonts`.
+ * Cell text is untrusted data, so one stray character must not fail the
+ * render: SCHEMA.md promises `?` for any face — WinAnsi on the base-14, the
+ * cmap on an embedded TrueType. A face that also lacks `?` omits the
+ * character rather than drawing .notdef.
  *
- * There is no way to ask a pdf-lib face what it can encode without measuring
- * against it, so the ASCII guard carries the common case and only text with a
- * character outside it pays for the answer. WinAnsi is a superset of printable
- * ASCII, so the guard never lets an unencodable character through.
+ * The ASCII guard carries the common case; only text with a character
+ * outside it pays for the cmap walk. Printable ASCII is a subset of WinAnsi
+ * and of every text face this target embeds.
  *
  * @type {(font: any, text: string) => string}
  */
 export let printable = (font, text) => {
   if (!text || ASCII.test(text) || encodable(font, text)) return text;
-  // WinAnsi encodability is a per-code-point question, so that is the unit to
-  // ask it in — the grapheme clusters the rule protects are unencodable anyway.
+  return replaceUndrawable(charsetOf(font), text);
+};
+
+/** @type {(set: Cmap, text: string) => string} */
+let replaceUndrawable = (set, text) => {
+  let sub = set.has(0x3f) ? "?" : "";
+  // Encodedness is a per-code-point question, so that is the unit to ask it
+  // in — the grapheme clusters the rule protects are undrawable anyway.
   // oxlint-disable-next-line typescript/no-misused-spread
-  return [...text].map((char) => (encodable(font, char) ? char : "?")).join("");
+  return [...text].map((char) => (set.has(char.codePointAt(0) ?? -1) ? char : sub)).join("");
 };
 
 /** @type {(font: any, text: string) => boolean} */
 let encodable = (font, text) => {
-  try {
-    font.widthOfTextAtSize(text, 1);
-    return true;
-  } catch {
-    return false;
-  }
+  let set = charsetOf(font);
+  // oxlint-disable-next-line typescript/no-misused-spread
+  return [...text].every((char) => set.has(char.codePointAt(0) ?? -1));
 };

package/lib/index.js

@@ -5,8 +5,8 @@
  * 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 geometry is target configuration
- * (`pdf({ page })`), never schema.
+ * 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,
@@ -57,11 +57,11 @@ let pair = (dimensions) => {
   return { width, height };
 };
 
-/** @type {(margin: any, width: number, height: number) => number} */
-let marginOf = (margin = 54, 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("options.page.margin: expected a non-negative number smaller than half the page");
+  fits || err(path + ": expected a non-negative number smaller than half the page");
   return margin;
 };
 
@@ -71,16 +71,30 @@ let marginOf = (margin = 54, width, height) => {
 // 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, settled here beside the validation
-// that produced them. This frame never moves at all: it serves every render the
-// target compiles, so a narrowing here would be one document's page bands
-// reserved out of the next one too. The one narrowing a render does make is the
-// band flow's, off that render's own canvas.
-/** @type {(options: any) => import('./canvas.js').Frame} */
-let geometry = (options) => {
+// 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));
-  return frame(width, height, marginOf(page.margin, width, height), BASE);
+  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
@@ -136,7 +150,7 @@ let markPages = async (canvas, marking) => {
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function pdf(options) {
-  let geo = geometry(options);
+  geometry(options);
   let meta = options?.meta,
     custom = options?.fonts;
   /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
@@ -146,11 +160,18 @@ export function pdf(options) {
     // 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);
-    await walk(stream(data), handlers);
+    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