blitz-pdf 0.1.1 → 0.1.3

package/docs/pagination-regressions.md

@@ -0,0 +1,88 @@
+# Pagination regressions in 0.1.2
+
+The regressions are exercised through `renderPdf` in `tests/pagination.test.ts`.
+Rebuild the WASM before running them.
+
+## Final breaks and empty lines
+
+```js
+await renderPdf("<p>Text<br></p>", { format: "A4" });
+```
+
+With the pinned Blitz `e72650a` and Parley 0.12.0, instrumenting this layout
+shows a paragraph height of 19 CSS pixels. Parley supplies two line ranges:
+`[0, 19]` for `Text\n`, and `[19, 38]` with an empty text range and no positioned
+items. Both have a finite, ordinary line height of 19 pixels.
+
+Blitz's `packages/blitz-dom/src/layout/inline.rs` excludes that second line
+from the block's height: it exists to position an editor cursor after a final
+newline, not as another CSS line box. Pagination previously kept it. With the
+default paragraph margins, the document ends inside this extra line; repeated
+attempts to move the break backward eventually stop making progress. The old
+error incorrectly classified this as a line taller than A4.
+
+`css_lines` now uses the same terminal-line test as Blitz, including for
+keep-with-next edges and widow/orphan counts. A real blank line has a newline in
+its text range and remains in pagination with its measured line box. No text,
+invisible anchor, or other character is inserted. Position assertions cover
+multiple blank lines, table cells, and automatic/forced page boundaries.
+
+## Height-limited tables
+
+Use the following HTML in both a browser and `renderPdf(html, { format: "A4" })`:
+
+```html
+<style>
+  .info { width: 75mm; max-height: 75mm; overflow: hidden; }
+  .info table { width: 100%; border-collapse: collapse; }
+  .info td {
+    max-width: 0;
+    word-break: break-all;
+    overflow-wrap: break-word;
+  }
+</style>
+<div class="info">
+  <table>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+    <tr><td>Text</td><td>Text</td></tr>
+  </table>
+</div>
+```
+
+Measured in Chromium 154 on macOS, `getBoundingClientRect()` gives a table
+width of about 283.46 pixels, cell widths of about 141.73 pixels and a total
+height of 123 pixels. Changing `max-width` to `none` produces the same
+dimensions for these equal cell contents.
+
+Blitz's final cell layout instead has width 2 pixels (zero content width plus
+padding), height 78 pixels, and four 19-pixel lines for `Text`. Its table grid
+adapts cells to grid items while retaining `max_size.width`; the inline layout
+therefore receives a zero-width constraint. This confirms a browser
+compatibility difference. It does not establish a general correction to the
+CSS table-width algorithm, which remains a separate upstream task.
+
+The resulting tall table exceeds its container's height. Pagination previously
+used line and row ranges beyond the overflow clip; the document end inside a
+clipped line could cause the same misleading error as the first reproduction.
+Pagination now clips those ranges to the visible padding box and intersects
+glyph bounds with the scene's nested clips. PDF text emission uses the same
+clip bounds to omit fully hidden runs. Regression coverage includes both
+`max-width` values, nested `hidden`/`clip` containers and clipped oversized ink.
+
+The zero-width case now exports, but its column widths still differ from the
+browser. Its test deliberately does not claim that all twelve cells are visible.
+
+## Diagnostic distinctions
+
+`PAGINATION_LINE_TOO_TALL` requires a blocking line whose visible height exceeds
+the available height. `PAGINATION_NO_PROGRESS` covers, for example, staggered
+columns of overlapping 40-pixel lines on an 80-pixel page. A forced break through
+a line has its own `PAGINATION_FORCED_BREAK_INTERSECTS_LINE` code. Tests assert
+the element, page/line indexes, available height and line range, and verify that
+rendering remains usable after an error.
+
+The Argon asset-path issue is outside this change.

package/examples/zugferd.mjs

@@ -0,0 +1,41 @@
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { renderPdf } from "blitz-pdf";
+
+// Use HTML and validated CII XML for the same invoice. This example packages
+// supplied invoice data; it does not generate or validate business information.
+const [htmlPath, xmlPath, profile, outputPath = "output/pdf/zugferd.pdf"] = process.argv.slice(2);
+if (!htmlPath || !xmlPath || !profile) {
+  console.error('Usage: node examples/zugferd.mjs invoice.html invoice.xml "EN 16931" [output.pdf]');
+  process.exit(1);
+}
+if (!["MINIMUM", "BASIC WL", "BASIC", "EN 16931", "EXTENDED"].includes(profile)) {
+  throw new Error("Choose MINIMUM, BASIC WL, BASIC, EN 16931, or EXTENDED for this example");
+}
+const [html, xml] = await Promise.all([readFile(htmlPath, "utf8"), readFile(xmlPath)]);
+const bytes = await renderPdf(html, {
+  format: "A4", margin: "15mm",
+  baseUrl: pathToFileURL(resolve(htmlPath)).href,
+  assets: async url => readFile(new URL(url)),
+  attachments: [{
+    name: "factur-x.xml", data: xml, mimeType: "text/xml", description: "Invoice XML",
+    relationship: ["MINIMUM", "BASIC WL"].includes(profile) ? "Data" : "Alternative",
+  }],
+  metadata: {
+    title: "Invoice", creator: "blitz-pdf invoice example", language: "de-DE",
+    xmp: [{
+      name: "Factur-X PDFA Extension Schema", prefix: "fx",
+      namespaceUri: "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#",
+      properties: [
+        { name: "DocumentFileName", value: "factur-x.xml", description: "Embedded invoice filename" },
+        { name: "DocumentType", value: "INVOICE", description: "Document type" },
+        { name: "Version", value: "1.0", description: "Schema version" },
+        { name: "ConformanceLevel", value: profile, description: "Invoice profile" },
+      ],
+    }],
+  },
+});
+await mkdir(dirname(resolve(outputPath)), { recursive: true });
+await writeFile(outputPath, bytes);
+console.log(`Created ${outputPath} (${bytes.length} bytes, PDF/A-3u with ${profile} Factur-X packaging).`);

package/licenses/RUST_DEPENDENCIES.txt

@@ -4815,6 +4815,7 @@ DEALINGS IN THE SOFTWARE.
 
 ========================================================================
 encoding_rs 0.8.42 (LICENSE-APACHE)
+krilla 0.8.2 (LICENSE_APACHE)
 kurbo 0.13.1 (LICENSE-APACHE)
 multiversion_no_op 1.0.0 (LICENSE-APACHE)
 polycool 0.4.0 (LICENSE-APACHE)
@@ -6699,6 +6700,32 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+========================================================================
+krilla 0.8.2 (LICENSE_MIT)
+========================================================================
+
+MIT License
+
+Copyright (c) 2024 Laurenz Stampfl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 ========================================================================
 kurbo 0.13.1 (LICENSE-MIT)
 peniko 0.6.1 (LICENSE-MIT)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blitz-pdf",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Render HTML and CSS to PDF with Blitz and WebAssembly in Node.js, Bun, and browsers.",
   "type": "module",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "dist",
     "wasm",
     "src",
+    "docs",
     "examples",
     "assets/icon.svg",
     "README.md",
@@ -71,7 +72,8 @@
     "example:node": "node examples/node.mjs",
     "example:bun": "bun examples/bun.ts",
     "example:pagination": "node examples/pagination.mjs",
-    "example:german-invoice": "node examples/german-invoice.mjs"
+    "example:german-invoice": "node examples/german-invoice.mjs",
+    "example:zugferd": "node examples/zugferd.mjs"
   },
   "keywords": [
     "pdf",

package/src/browser.ts

@@ -1,6 +1,6 @@
 import { createApi } from "./api.js";
 
-export type { AssetData, AssetMap, AssetResolver, BinaryData, InitOptions, Length, PageFormat, PageNumberOptions, PdfOptions, WasmSource } from "./types.js";
+export type { AssetData, AssetMap, AssetResolver, AttachmentRelationship, BinaryData, InitOptions, Length, PageFormat, PageNumberOptions, PdfAttachment, PdfDate, PdfMetadata, PdfOptions, PdfXmpProperty, PdfXmpSchema, WasmSource } from "./types.js";
 export const { init, renderPdf, getEngineVersion } = createApi(
   () => new URL("../wasm/blitz_pdf_bg.wasm", import.meta.url),
 );

package/src/document-options.ts

@@ -0,0 +1,218 @@
+import { assetBytes } from "./assets.js";
+import { record } from "./validation.js";
+import type { AssetData, AttachmentRelationship, PdfAttachment, PdfDate, PdfOptions, PdfXmpSchema } from "./types.js";
+
+const MAX_ATTACHMENT_BYTES = 64 * 1024 * 1024;
+const encoder = new TextEncoder();
+const relationships = new Set(["Source", "Data", "Alternative", "Supplement", "Unspecified"]);
+const reservedPrefixes = new Set(["x", "rdf", "dc", "pdf", "pdfaid", "pdfuaid", "pdfxid", "stRef", "stEvt", "stVer", "stJob", "stFnt", "stDim", "pdfaExtension", "pdfaSchema", "pdfaProperty", "pdfaType", "pdfaField", "xmp", "xmpRights", "xmpG", "xmpMM", "xmpBJ", "xmpTPg", "xmpDM", "xmpGImg", "xmpidq"]);
+const reservedNamespaces = new Set([
+  "adobe:ns:meta/",
+  "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+  "http://purl.org/dc/elements/1.1/",
+  "http://www.w3.org/XML/1998/namespace",
+  "http://www.w3.org/2000/xmlns/",
+  "http://ns.adobe.com/pdf/1.3/",
+  "http://ns.adobe.com/xmp/Identifier/qual/1.0/",
+  "http://www.npes.org/pdfx/ns/id/",
+  "http://www.aiim.org/pdfua/ns/id/",
+  "http://ns.adobe.com/xap/1.0/",
+  "http://ns.adobe.com/xap/1.0/rights/",
+  "http://ns.adobe.com/xap/1.0/sType/ResourceRef#",
+  "http://ns.adobe.com/xap/1.0/sType/ResourceEvent#",
+  "http://ns.adobe.com/xap/1.0/sType/Version#",
+  "http://ns.adobe.com/xap/1.0/sType/Job#",
+  "http://ns.adobe.com/xap/1.0/g/",
+  "http://ns.adobe.com/xap/1.0/sType/Font#",
+  "http://ns.adobe.com/xap/1.0/sType/Dimensions#",
+  "http://ns.adobe.com/xap/1.0/mm/",
+  "http://ns.adobe.com/xap/1.0/bj/",
+  "http://ns.adobe.com/xap/1.0/t/pg/",
+  "http://ns.adobe.com/xap/1.0/DynamicMedia/",
+  "http://ns.adobe.com/xap/1.0/g/img/",
+  "http://www.aiim.org/pdfa/ns/id/",
+  "http://www.aiim.org/pdfa/ns/extension/",
+  "http://www.aiim.org/pdfa/ns/schema#",
+  "http://www.aiim.org/pdfa/ns/property#",
+  "http://www.aiim.org/pdfa/ns/type#",
+  "http://www.aiim.org/pdfa/ns/field#",
+]);
+
+function keys(value: object, allowed: readonly string[], name: string) {
+  record(value, name);
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw new TypeError(`Unknown ${name} option: ${key}`);
+  }
+}
+
+function text(value: unknown, name: string, maxBytes = 16 * 1024): string {
+  if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+  // XML 1.0 characters only, including rejection of unpaired UTF-16 surrogates.
+  if (/[^\u0009\u000a\u000d\u0020-\ud7ff\ue000-\ufffd\u{10000}-\u{10ffff}]/u.test(value)) {
+    throw new TypeError(`${name} contains invalid XML characters`);
+  }
+  if (value.length > maxBytes || encoder.encode(value).byteLength > maxBytes) {
+    throw new RangeError(`${name} exceeds the ${maxBytes} byte limit`);
+  }
+  // XML normalizes literal CR/CRLF to LF. Match that in the PDF Info dictionary.
+  return value.replace(/\r\n?/g, "\n");
+}
+
+function optionalText(value: unknown, name: string) {
+  return value === undefined ? null : text(value, name);
+}
+
+function textList(value: unknown, name: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new TypeError(`${name} must be an array of strings`);
+  if (value.length > 256) throw new RangeError(`${name} must contain at most 256 entries`);
+  const result = Array.from(value, (entry, i) => text(entry, `${name}[${i}]`));
+  text(result.join(", "), name);
+  return result;
+}
+
+function xmlName(value: unknown, label: string): string {
+  const name = text(value, label, 128);
+  if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(name) || /^xml/i.test(name)) {
+    throw new TypeError(`${label} must be an ASCII XML name without a colon or xml prefix`);
+  }
+  return name;
+}
+
+function xmpSchemas(value: readonly PdfXmpSchema[] | undefined) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new TypeError("metadata.xmp must be an array of schemas");
+  if (value.length > 32) throw new RangeError("metadata.xmp exceeds the 32 schema limit");
+  const prefixes = new Set<string>();
+  const namespaces = new Set<string>();
+  let count = 0, size = 0;
+  return Array.from(value, (schema: PdfXmpSchema, i) => {
+    const label = `metadata.xmp[${i}]`;
+    keys(schema, ["name", "namespaceUri", "prefix", "properties"], label);
+    const name = text(schema.name, `${label}.name`);
+    if (!name.trim()) throw new TypeError(`${label}.name must not be empty`);
+    const prefix = xmlName(schema.prefix, `${label}.prefix`);
+    const namespaceUri = text(schema.namespaceUri, `${label}.namespaceUri`);
+    // xmp-writer writes namespace declarations as attributes. Require an absolute,
+    // ASCII URI without XML delimiters; callers can percent-encode these characters.
+    if (!/^[a-z][a-z0-9+.-]*:[\x21-\x7e]+$/i.test(namespaceUri) || /[<>"'&]/.test(namespaceUri)) {
+      throw new TypeError(`${label}.namespaceUri must be an absolute URI with XML delimiters percent-encoded`);
+    }
+    if (reservedPrefixes.has(prefix) || reservedNamespaces.has(namespaceUri)) {
+      throw new TypeError(`${label} uses a reserved XMP prefix or namespace`);
+    }
+    if (prefixes.has(prefix) || namespaces.has(namespaceUri)) throw new TypeError(`${label} has a duplicate XMP prefix or namespace`);
+    prefixes.add(prefix); namespaces.add(namespaceUri);
+    if (!Array.isArray(schema.properties) || schema.properties.length === 0) throw new TypeError(`${label}.properties must be a non-empty array`);
+    count += schema.properties.length;
+    if (count > 256) throw new RangeError("metadata.xmp exceeds the 256 property limit");
+    const propertyNames = new Set<string>();
+    size += encoder.encode(name + namespaceUri + prefix).byteLength;
+    const properties = Array.from(schema.properties, (property, j) => {
+      const key = `${label}.properties[${j}]`;
+      keys(property, ["name", "value", "description", "category"], key);
+      const name = xmlName(property.name, `${key}.name`);
+      if (propertyNames.has(name)) throw new TypeError(`${key} has a duplicate XMP property name`);
+      propertyNames.add(name);
+      const value = text(property.value, `${key}.value`);
+      const description = text(property.description, `${key}.description`);
+      if (!description.trim()) throw new TypeError(`${key}.description must not be empty`);
+      const category = property.category === undefined ? "external" : property.category;
+      if (category !== "internal" && category !== "external") throw new TypeError(`${key}.category must be internal or external`);
+      size += encoder.encode(name + value + description).byteLength;
+      if (size > 1024 * 1024) throw new RangeError("metadata.xmp exceeds the 1 MiB limit");
+      return { name, value, description, category };
+    });
+    return { name, prefix, namespaceUri, properties };
+  });
+}
+
+function date(value: PdfDate | undefined, name: string, fallback: number): number {
+  if (value === undefined) return fallback;
+  let result: number;
+  if (value instanceof Date) result = value.getTime();
+  else if (typeof value === "string") {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+    if (!match) throw new TypeError(`${name} must be a Date or ISO timestamp with a timezone`);
+    const [, y, mo, d, h, mi, s, zone] = match;
+    const year = Number(y), month = Number(mo), day = Number(d);
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    if (month < 1 || month > 12 || day < 1 || day > days[month - 1]! ||
+        Number(h) > 23 || Number(mi) > 59 || Number(s) > 59 ||
+        (zone !== "Z" && (Number(zone!.slice(1, 3)) > 23 || Number(zone!.slice(4)) > 59))) {
+      throw new RangeError(`${name} is not a valid calendar date`);
+    }
+    result = Date.parse(value);
+  } else throw new TypeError(`${name} must be a Date or ISO timestamp with a timezone`);
+  if (!Number.isFinite(result) || result < -62135596800000 || result > 253402300799999) {
+    throw new RangeError(`${name} must be a valid date in years 0001 through 9999`);
+  }
+  return Math.floor(result / 1000) * 1000;
+}
+
+export function normalizeDocumentOptions(options: PdfOptions) {
+  const legacyTitle = optionalText(options.title, "title");
+  const input = options.metadata === undefined ? {} : options.metadata;
+  keys(input, ["title", "author", "subject", "keywords", "creator", "producer", "language", "creationDate", "modificationDate", "documentId", "xmp"], "metadata");
+  const creationDate = date(input.creationDate, "metadata.creationDate", Math.floor(Date.now() / 1000) * 1000);
+  const modificationDate = date(input.modificationDate, "metadata.modificationDate", creationDate);
+  if (modificationDate < creationDate) throw new RangeError("metadata.modificationDate must not precede creationDate");
+  const language = optionalText(input.language, "metadata.language");
+  if (language !== null && !/^(?:[a-z]{2,8}|x)(?:-[a-z0-9]{1,8})*$/i.test(language)) {
+    throw new TypeError("metadata.language must be a language tag such as de-DE");
+  }
+  const metadata = {
+    title: input.title === undefined ? legacyTitle : text(input.title, "metadata.title"),
+    authors: textList(typeof input.author === "string" ? [input.author] : input.author, "metadata.author"),
+    subject: optionalText(input.subject, "metadata.subject"),
+    keywords: textList(input.keywords, "metadata.keywords"),
+    creator: optionalText(input.creator, "metadata.creator"),
+    producer: optionalText(input.producer, "metadata.producer"),
+    language, creationDate, modificationDate,
+    documentId: optionalText(input.documentId, "metadata.documentId"),
+    xmp: xmpSchemas(input.xmp),
+  };
+
+  if (options.attachments !== undefined && !Array.isArray(options.attachments)) {
+    throw new TypeError("attachments must be an array");
+  }
+  if ((options.attachments?.length ?? 0) > 100) {
+    throw new RangeError("Attachments exceed the 100 file limit");
+  }
+  let totalBytes = 0;
+  const names = new Set<string>();
+  function attachment(file: PdfAttachment, label: string) {
+    keys(file, ["name", "data", "mimeType", "description", "relationship", "modificationDate", "compress"], label);
+    const name = text(file.name, `${label}.name`, 255);
+    if (!name.trim() || name === "." || name === ".." || /[/\\:\u0000-\u001f\u007f-\u009f]/u.test(name)) {
+      throw new TypeError(`${label}.name must be a filename without directories or control characters`);
+    }
+    const normalizedName = name.normalize("NFC");
+    if (names.has(normalizedName)) throw new TypeError(`Duplicate attachment name: ${name}`);
+    names.add(normalizedName);
+    const mimeType = file.mimeType === undefined ? "application/octet-stream" : file.mimeType;
+    if (typeof mimeType !== "string" || mimeType.length > 255 || !/^[a-z0-9][a-z0-9.+-]*\/[a-z0-9][a-z0-9.+-]*$/i.test(mimeType)) {
+      throw new TypeError(`${label}.mimeType must be a MIME type without parameters`);
+    }
+    const relationship = file.relationship === undefined ? "Unspecified" : file.relationship;
+    if (!relationships.has(relationship)) throw new TypeError(`${label}.relationship is invalid`);
+    if (file.compress !== undefined && typeof file.compress !== "boolean") throw new TypeError(`${label}.compress must be a boolean`);
+    const data = file.data;
+    // Check binary sizes before allocating the defensive copy.
+    const size = typeof data === "string" ? data.length : data instanceof Uint8Array || data instanceof ArrayBuffer ? data.byteLength : 0;
+    if (totalBytes + size > MAX_ATTACHMENT_BYTES) throw new RangeError("Attachments exceed the 64 MiB limit");
+    const bytes = assetBytes(data as AssetData, `${label}.data`);
+    totalBytes += bytes.byteLength;
+    if (totalBytes > MAX_ATTACHMENT_BYTES) throw new RangeError("Attachments exceed the 64 MiB limit");
+    return {
+      name, data: bytes, mimeType,
+      description: file.description === undefined ? name : text(file.description, `${label}.description`),
+      relationship: relationship as AttachmentRelationship,
+      modificationDate: date(file.modificationDate, `${label}.modificationDate`, modificationDate),
+      compress: file.compress ?? null,
+    };
+  }
+  const attachments = Array.from(options.attachments ?? [], (file, i) => attachment(file, `attachments[${i}]`));
+  return { metadata, attachments };
+}

package/src/node.ts

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { createApi } from "./api.js";
 
-export type { AssetData, AssetMap, AssetResolver, BinaryData, InitOptions, Length, PageFormat, PageNumberOptions, PdfOptions, WasmSource } from "./types.js";
+export type { AssetData, AssetMap, AssetResolver, AttachmentRelationship, BinaryData, InitOptions, Length, PageFormat, PageNumberOptions, PdfAttachment, PdfDate, PdfMetadata, PdfOptions, PdfXmpProperty, PdfXmpSchema, WasmSource } from "./types.js";
 export const { init, renderPdf, getEngineVersion } = createApi(
   () => readFile(new URL("../wasm/blitz_pdf_bg.wasm", import.meta.url)),
   async source => {

package/src/options.ts

@@ -1,13 +1,19 @@
 import { assetBytes, copyBytes, MAX_ASSET_BYTES } from "./assets.js";
+import { normalizeDocumentOptions } from "./document-options.js";
+import { record } from "./validation.js";
 import type { Length, PageFormat, PageNumberOptions, PdfOptions } from "./types.js";
 
 const formats: Record<PageFormat, readonly [number, number]> = {
+  A0: [841 * 96 / 25.4, 1189 * 96 / 25.4],
+  A1: [594 * 96 / 25.4, 841 * 96 / 25.4],
+  A2: [420 * 96 / 25.4, 594 * 96 / 25.4],
   A3: [297 * 96 / 25.4, 420 * 96 / 25.4],
   A4: [210 * 96 / 25.4, 297 * 96 / 25.4],
   A5: [148 * 96 / 25.4, 210 * 96 / 25.4],
-  Letter: [8.5 * 96, 11 * 96], Legal: [8.5 * 96, 14 * 96], Tabloid: [11 * 96, 17 * 96],
+  A6: [105 * 96 / 25.4, 148 * 96 / 25.4],
+  Letter: [8.5 * 96, 11 * 96], Legal: [8.5 * 96, 14 * 96], Tabloid: [11 * 96, 17 * 96], Ledger: [17 * 96, 11 * 96],
 };
-const optionKeys = new Set(["format", "width", "height", "landscape", "margin", "media", "baseUrl", "assets", "fonts", "title", "pageNumbers", "maxPages"]);
+const optionKeys = new Set(["format", "width", "height", "landscape", "preferCSSPageSize", "margin", "media", "baseUrl", "assets", "fonts", "title", "metadata", "attachments", "pageNumbers", "headerTemplate", "footerTemplate", "maxPages"]);
 const unitScale: Record<string, number> = { px: 1, pt: 96 / 72, mm: 96 / 25.4, cm: 96 / 2.54, in: 96 };
 
 function length(value: Length, name: string): number {
@@ -22,19 +28,17 @@ function length(value: Length, name: string): number {
   return result;
 }
 
-function record(value: unknown, name: string): void {
-  if (value === null || typeof value !== "object" || Array.isArray(value) ||
-      ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
-    throw new TypeError(`${name} must be a plain object`);
-  }
-}
-
 export function normalizeOptions(options: PdfOptions = {}) {
   record(options, "options");
   for (const key of Object.keys(options)) {
     if (!optionKeys.has(key)) throw new TypeError(`Unknown PDF option: ${key}`);
   }
   if (options.landscape !== undefined && typeof options.landscape !== "boolean") throw new TypeError("landscape must be a boolean");
+  if (options.preferCSSPageSize !== undefined && typeof options.preferCSSPageSize !== "boolean") throw new TypeError("preferCSSPageSize must be a boolean");
+  for (const key of ["headerTemplate", "footerTemplate"] as const) {
+    if (options[key] !== undefined && typeof options[key] !== "string") throw new TypeError(`${key} must be an HTML string`);
+    if (new TextEncoder().encode(options[key] ?? "").byteLength > 1024 * 1024) throw new RangeError(`${key} exceeds the 1 MiB limit`);
+  }
   const format = options.format ?? "A4";
   if (!Object.hasOwn(formats, format)) throw new TypeError(`Unknown page format: ${String(format)}`);
   if ((options.width === undefined) !== (options.height === undefined)) throw new TypeError("width and height must be provided together");
@@ -67,13 +71,12 @@ export function normalizeOptions(options: PdfOptions = {}) {
     if (fontSize < 1 || fontSize > 48) throw new RangeError("pageNumbers.fontSize must be between 1 and 48 CSS pixels");
     pageNumbers = { template, align, fontSize };
   }
-  const footerHeight = pageNumbers ? pageNumbers.fontSize * 2 + 8 : 0;
-  if (width - margin.left - margin.right < 1 || height - margin.top - margin.bottom - footerHeight < 1) throw new RangeError("Margins and pageNumbers must leave at least one CSS pixel of content");
+  // Printable geometry is validated after external CSS @page rules have loaded.
   const media = options.media ?? "print";
   if (media !== "print" && media !== "screen") throw new TypeError("media must be print or screen");
   const maxPages = options.maxPages ?? 100;
   if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 1000) throw new RangeError("maxPages must be an integer between 1 and 1000");
-  if (options.title !== undefined && typeof options.title !== "string") throw new TypeError("title must be a string");
+  const document = normalizeDocumentOptions(options);
   const baseUrl = options.baseUrl ?? "https://blitz-pdf.invalid/";
   if (typeof baseUrl !== "string") throw new TypeError("baseUrl must be an absolute URL string");
   let base: URL;
@@ -97,5 +100,7 @@ export function normalizeOptions(options: PdfOptions = {}) {
   if (options.fonts !== undefined && !Array.isArray(options.fonts)) throw new TypeError("fonts must be an array of font bytes");
   const fonts = (options.fonts ?? []).map((font, i) => copyBytes(font, `fonts[${i}]`));
   if (fonts.reduce((total, font) => total + font.byteLength, 0) > 32 * 1024 * 1024) throw new RangeError("Fonts exceed the 32 MiB limit");
-  return { width, height, margin, media, maxPages, baseUrl: base.href, assets, assetResolver, fonts, pageNumbers, title: options.title ?? null };
+  return { width, height, margin, media, maxPages, baseUrl: base.href, assets, assetResolver, fonts, pageNumbers,
+    useCSSPageSize: options.preferCSSPageSize === true || (options.format === undefined && options.width === undefined),
+    headerTemplate: options.headerTemplate ?? null, footerTemplate: options.footerTemplate ?? null, ...document };
 }

package/src/types.ts

@@ -1,6 +1,6 @@
 /** Numbers are CSS pixels (96 px = 1 inch). */
 export type Length = number | `${number}${"px" | "pt" | "mm" | "cm" | "in"}`;
-export type PageFormat = "A3" | "A4" | "A5" | "Letter" | "Legal" | "Tabloid";
+export type PageFormat = "A0" | "A1" | "A2" | "A3" | "A4" | "A5" | "A6" | "Letter" | "Legal" | "Tabloid" | "Ledger";
 export type BinaryData = Uint8Array | ArrayBuffer;
 /** UTF-8 text (for CSS/SVG) or binary resource contents. */
 export type AssetData = BinaryData | string;
@@ -23,10 +23,77 @@ export interface PageNumberOptions {
   fontSize?: Length;
 }
 
+/** A Date or an ISO 8601 timestamp with an explicit timezone. Serialized in UTC to whole seconds. */
+export type PdfDate = Date | string;
+export type AttachmentRelationship = "Source" | "Data" | "Alternative" | "Supplement" | "Unspecified";
+
+export interface PdfAttachment {
+  /** Unique filename, without directories. Unicode is supported. */
+  name: string;
+  /** File contents, not a path or URL. Strings are encoded as UTF-8. */
+  data: AssetData;
+  /** MIME type without parameters. Default: application/octet-stream. */
+  mimeType?: string;
+  /** Human-readable description. Default: name. */
+  description?: string;
+  /** PDF/A association with the whole document. Default: Unspecified. */
+  relationship?: AttachmentRelationship;
+  /** Default: the document modification date. */
+  modificationDate?: PdfDate;
+  /** Omit to let the engine choose whether compression helps. */
+  compress?: boolean;
+}
+
+/** A custom text property and its PDF/A schema description. */
+export interface PdfXmpProperty {
+  /** XML local name, e.g. DocumentFileName. */
+  name: string;
+  value: string;
+  description: string;
+  /** Default: external (supplied by the user). */
+  category?: "internal" | "external";
+}
+
+/** Custom XMP text properties, emitted with their PDF/A extension schema. */
+export interface PdfXmpSchema {
+  /** Human-readable schema name. */
+  name: string;
+  /** Absolute namespace URI, e.g. urn:example:documents:1.0#. */
+  namespaceUri: string;
+  /** Unique XML namespace prefix, e.g. acme. Built-in prefixes are reserved. */
+  prefix: string;
+  properties: readonly PdfXmpProperty[];
+}
+
+export interface PdfMetadata {
+  /** Overrides the legacy top-level title option. */
+  title?: string;
+  author?: string | readonly string[];
+  subject?: string;
+  keywords?: readonly string[];
+  /** Application that created the document. */
+  creator?: string;
+  /** Default: blitz-pdf and its version. */
+  producer?: string;
+  /** Document language, e.g. de-DE. */
+  language?: string;
+  /** Default: render start time. */
+  creationDate?: PdfDate;
+  /** Default: creationDate. Must not precede it. */
+  modificationDate?: PdfDate;
+  /** Stable input used to derive the PDF document ID across revisions. */
+  documentId?: string;
+  /** Up to 32 custom schemas / 256 text properties / 1 MiB combined. */
+  xmp?: readonly PdfXmpSchema[];
+}
+
 export interface PdfOptions {
   // All output uses PDF/A-3u conformance, including Unicode mappings and ICC colors.
   /** Default: A4. Use width and height together for a custom page. */
   format?: PageFormat;
+  /** Let CSS @page size override explicit format/width/height. Default: false.
+   * Without explicit dimensions, CSS page size is always used when available. */
+  preferCSSPageSize?: boolean;
   width?: Length;
   height?: Length;
   landscape?: boolean;
@@ -42,8 +109,16 @@ export interface PdfOptions {
   fonts?: readonly BinaryData[];
   /** PDF document title. */
   title?: string;
+  /** Synchronized PDF information dictionary and XMP metadata. */
+  metadata?: PdfMetadata;
+  /** Direct file attachments. Maximum 100 files and 64 MiB combined. */
+  attachments?: readonly PdfAttachment[];
   /** Selectable page-number footer. Reserves space above the bottom margin. Default: false. */
   pageNumbers?: boolean | PageNumberOptions;
+  /** HTML rendered on every page inside the top margin. Styles are template-local. */
+  headerTemplate?: string;
+  /** HTML rendered on every page inside the bottom margin. Styles are template-local. */
+  footerTemplate?: string;
   /** Reject larger documents. Default: 100; maximum: 1000. */
   maxPages?: number;
 }

package/src/validation.ts

@@ -0,0 +1,6 @@
+export function record(value: unknown, name: string): void {
+  if (value === null || typeof value !== "object" || Array.isArray(value) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}