blitz-pdf 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "blitz-pdf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Render HTML and CSS to PDF with Blitz and WebAssembly in Node.js, Bun, and browsers.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iteufel/blitz-pdf.git"
+  },
+  "homepage": "https://github.com/iteufel/blitz-pdf#readme",
+  "bugs": {
+    "url": "https://github.com/iteufel/blitz-pdf/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/node.js",
+  "module": "./dist/browser.js",
+  "types": "./dist/node.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/browser.d.ts",
+        "default": "./dist/browser.js"
+      },
+      "bun": {
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js"
+      },
+      "node": {
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js"
+      },
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./wasm": "./wasm/blitz_pdf_bg.wasm",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "wasm",
+    "src",
+    "examples",
+    "assets/icon.svg",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "licenses",
+    "vendor"
+  ],
+  "scripts": {
+    "build": "npm run build:wasm && npm run build:js",
+    "build:wasm": "node scripts/build-wasm.mjs",
+    "build:js": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test tests/*.test.ts",
+    "test:node": "node tests/node-smoke.mjs",
+    "test:bun": "bun test tests/*.test.ts",
+    "test:browser": "node scripts/serve-browser.mjs",
+    "test:pdfa": "node scripts/validate-pdfa.mjs",
+    "setup:verapdf": "node scripts/install-verapdf.mjs",
+    "bench": "bun benchmarks/render.ts",
+    "prepack": "node scripts/check-package.mjs",
+    "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"
+  },
+  "keywords": [
+    "pdf",
+    "html",
+    "css",
+    "wasm",
+    "webassembly",
+    "blitz",
+    "bun"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^6.4.299",
+    "typescript": "^5.9.3"
+  }
+}

package/src/api.ts

@@ -0,0 +1,44 @@
+import loadWasm, { render_pdf, engine_version, RenderJob } from "../wasm/blitz_pdf.js";
+import { createAssetLoader } from "./assets.js";
+import { normalizeOptions } from "./options.js";
+import type { InitOptions, PdfOptions, WasmSource } from "./types.js";
+
+export function createApi(defaultSource: () => Promise<WasmSource> | WasmSource,
+  prepare: (source: WasmSource) => Promise<WasmSource> = async source => source) {
+  let ready: Promise<void> | undefined;
+
+  /** Initialize once. Concurrent callers share initialization; failed loads can be retried. */
+  function init(options: InitOptions = {}): Promise<void> {
+    if (ready) return ready;
+    ready = (async () => {
+      const source = await prepare(options.wasm ?? await defaultSource());
+      await loadWasm({ module_or_path: source });
+    })().catch((error: unknown) => { ready = undefined; throw error; });
+    return ready;
+  }
+
+  /** Render HTML/CSS to a vector PDF/A-3u with embedded fonts and selectable text. */
+  async function renderPdf(html: string, options: PdfOptions = {}): Promise<Uint8Array> {
+    if (typeof html !== "string") throw new TypeError("html must be a string");
+    if (new TextEncoder().encode(html).byteLength > 16 * 1024 * 1024) throw new RangeError("HTML exceeds the 16 MiB limit");
+    const { assetResolver, ...normalized } = normalizeOptions(options);
+    await init();
+    if (!assetResolver) return render_pdf(html, normalized);
+    const load = createAssetLoader(assetResolver);
+    const job = new RenderJob(html, normalized);
+    try {
+      for (;;) {
+        const urls = job.pending_assets();
+        if (urls.length === 0) return job.finish();
+        const data = await load(urls);
+        for (let i = 0; i < urls.length; i++) job.provide_asset(urls[i]!, data[i]!);
+      }
+    } finally {
+      // In-flight JS loaders never access this job, including after a sibling rejects.
+      job.free();
+    }
+  }
+
+  async function getEngineVersion(): Promise<string> { await init(); return engine_version(); }
+  return { init, renderPdf, getEngineVersion };
+}

package/src/assets.ts

@@ -0,0 +1,43 @@
+import type { AssetData, AssetResolver, BinaryData } from "./types.js";
+
+export const MAX_ASSET_BYTES = 64 * 1024 * 1024;
+
+export function copyBytes(value: BinaryData, name: string): Uint8Array {
+  // Buffer.slice() creates a view, so use a constructor to snapshot every Uint8Array.
+  if (value instanceof Uint8Array) return new Uint8Array(value);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));
+  throw new TypeError(`${name} must be a Uint8Array or ArrayBuffer`);
+}
+
+export function assetBytes(value: AssetData, name: string): Uint8Array {
+  return typeof value === "string" ? new TextEncoder().encode(value) : copyBytes(value, name);
+}
+
+/** Load independent requests concurrently, with a byte budget shared by all batches of this render. */
+export function createAssetLoader(resolver: AssetResolver) {
+  let totalBytes = 0;
+  return async (urls: string[]): Promise<Uint8Array[]> => {
+    const results = new Array<Uint8Array>(urls.length);
+    let next = 0;
+    let failed = false;
+    async function worker() {
+      while (!failed && next < urls.length) {
+        const index = next++;
+        const url = urls[index]!;
+        try {
+          let value: Awaited<ReturnType<AssetResolver>>;
+          try { value = await resolver(url); }
+          catch (cause) { throw new Error(`Failed to load asset: ${url}`, { cause }); }
+          if (failed) return;
+          if (value == null) throw new Error(`Missing asset: ${url}. The asset resolver returned ${String(value)}`);
+          const data = assetBytes(value, `Asset resolver result for ${url}`);
+          totalBytes += data.byteLength;
+          if (totalBytes > MAX_ASSET_BYTES) throw new RangeError("Assets exceed the 64 MiB limit");
+          results[index] = data;
+        } catch (error) { failed = true; throw error; }
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(8, urls.length) }, worker));
+    return results;
+  };
+}

package/src/browser.ts

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

package/src/node.ts

@@ -0,0 +1,12 @@
+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 const { init, renderPdf, getEngineVersion } = createApi(
+  () => readFile(new URL("../wasm/blitz_pdf_bg.wasm", import.meta.url)),
+  async source => {
+    if (source instanceof URL && source.protocol === "file:") return readFile(source);
+    if (typeof source === "string" && source.startsWith("file:")) return readFile(new URL(source));
+    return source;
+  },
+);

package/src/options.ts

@@ -0,0 +1,101 @@
+import { assetBytes, copyBytes, MAX_ASSET_BYTES } from "./assets.js";
+import type { Length, PageFormat, PageNumberOptions, PdfOptions } from "./types.js";
+
+const formats: Record<PageFormat, readonly [number, number]> = {
+  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],
+};
+const optionKeys = new Set(["format", "width", "height", "landscape", "margin", "media", "baseUrl", "assets", "fonts", "title", "pageNumbers", "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 {
+  let result: number;
+  if (typeof value === "number") result = value;
+  else if (typeof value === "string") {
+    const match = /^\s*(\d+(?:\.\d+)?|\.\d+)(px|pt|mm|cm|in)\s*$/.exec(value);
+    if (!match) throw new TypeError(`${name} must be a number of CSS pixels or a length in px, pt, mm, cm, or in`);
+    result = Number(match[1]) * unitScale[match[2]!]!;
+  } else throw new TypeError(`${name} must be a CSS length`);
+  if (!Number.isFinite(result) || result < 0) throw new RangeError(`${name} must be finite and non-negative`);
+  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");
+  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");
+  if (options.format !== undefined && options.width !== undefined) throw new TypeError("Use either format or custom width and height");
+  let [width, height] = options.width === undefined
+    ? formats[format] : [length(options.width, "width"), length(options.height!, "height")];
+  if (options.landscape) [width, height] = [height, width];
+  if (width <= 0 || height <= 0 || width > 19200 || height > 19200) throw new RangeError("Page dimensions must be positive and at most 19200 CSS pixels");
+  const inputMargin = options.margin ?? 0;
+  const margin = { top: 0, right: 0, bottom: 0, left: 0 };
+  if (typeof inputMargin === "object") {
+    record(inputMargin, "margin");
+    for (const key of Object.keys(inputMargin)) if (!Object.hasOwn(margin, key)) throw new TypeError(`Unknown margin side: ${key}`);
+    for (const side of Object.keys(margin) as (keyof typeof margin)[]) margin[side] = length(inputMargin[side] ?? 0, `margin.${side}`);
+  } else {
+    const value = length(inputMargin, "margin");
+    for (const side of Object.keys(margin) as (keyof typeof margin)[]) margin[side] = value;
+  }
+  let pageNumbers: { template: string; align: "left" | "center" | "right"; fontSize: number } | null = null;
+  if (options.pageNumbers !== undefined && options.pageNumbers !== false) {
+    const input: PageNumberOptions = options.pageNumbers === true ? {} : options.pageNumbers;
+    record(input, "pageNumbers");
+    for (const key of Object.keys(input)) if (!["template", "align", "fontSize"].includes(key)) throw new TypeError(`Unknown pageNumbers option: ${key}`);
+    const template = input.template ?? "{page} / {pages}";
+    if (typeof template !== "string" || template.length > 512 || /[\u0000-\u001f\u007f\u0085\u2028\u2029]/u.test(template)) throw new TypeError("pageNumbers.template must be a single line of at most 512 characters");
+    if (!template.includes("{page}") || /[{}]/.test(template.replaceAll("{page}", "").replaceAll("{pages}", ""))) throw new TypeError("pageNumbers.template must include {page}; only {page} and {pages} placeholders are supported");
+    const align = input.align ?? "right";
+    if (!["left", "center", "right"].includes(align)) throw new TypeError("pageNumbers.align must be left, center, or right");
+    const fontSize = length(input.fontSize ?? 12, "pageNumbers.fontSize");
+    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");
+  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 baseUrl = options.baseUrl ?? "https://blitz-pdf.invalid/";
+  if (typeof baseUrl !== "string") throw new TypeError("baseUrl must be an absolute URL string");
+  let base: URL;
+  try { base = new URL(baseUrl); } catch { throw new TypeError("baseUrl must be an absolute URL string"); }
+  if (!["http:", "https:", "file:"].includes(base.protocol)) throw new TypeError("baseUrl must use http:, https:, or file:");
+  const assets: Record<string, Uint8Array> = Object.create(null);
+  const inputAssets = options.assets;
+  const assetResolver = typeof inputAssets === "function" ? inputAssets : undefined;
+  if (inputAssets !== undefined && !assetResolver) {
+    record(inputAssets, "assets");
+    let size = 0;
+    for (const [key, value] of Object.entries(inputAssets)) {
+      const data = assetBytes(value, `assets[${key}]`);
+      size += data.byteLength;
+      if (size > MAX_ASSET_BYTES) throw new RangeError("Assets exceed the 64 MiB limit");
+      const url = new URL(key, base).href;
+      if (Object.hasOwn(assets, url)) throw new TypeError(`Duplicate resolved asset URL: ${url}`);
+      assets[url] = data;
+    }
+  }
+  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 };
+}

package/src/types.ts

@@ -0,0 +1,49 @@
+/** 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 BinaryData = Uint8Array | ArrayBuffer;
+/** UTF-8 text (for CSS/SVG) or binary resource contents. */
+export type AssetData = BinaryData | string;
+export type AssetMap = Record<string, AssetData>;
+/** Receives an absolute URL. Returning null/undefined rejects the render as a missing asset. */
+export type AssetResolver = (url: string) => AssetData | null | undefined | Promise<AssetData | null | undefined>;
+export type WasmSource = BinaryData | WebAssembly.Module | URL | Request | Response | string;
+
+export interface InitOptions {
+  /** Override the bundled WASM location, or supply bytes/a compiled module. */
+  wasm?: WasmSource;
+}
+
+export interface PageNumberOptions {
+  /** Single line with {page} and optionally {pages}. Default: "{page} / {pages}". */
+  template?: string;
+  /** Default: right. */
+  align?: "left" | "center" | "right";
+  /** Default: 12 CSS pixels (9pt). */
+  fontSize?: Length;
+}
+
+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;
+  width?: Length;
+  height?: Length;
+  landscape?: boolean;
+  /** Default: 0. Missing sides of an object default to 0. */
+  margin?: Length | { top?: Length; right?: Length; bottom?: Length; left?: Length };
+  /** CSS media queries to use. Default: print. */
+  media?: "print" | "screen";
+  /** Base for resolving asset URLs. Default: https://blitz-pdf.invalid/ */
+  baseUrl?: string;
+  /** Resource map or async loader, called once per absolute URL per render. Data URLs are handled internally. */
+  assets?: AssetMap | AssetResolver;
+  /** Additional static TTF, OTF, WOFF, or WOFF2 fonts, using their internal family names. */
+  fonts?: readonly BinaryData[];
+  /** PDF document title. */
+  title?: string;
+  /** Selectable page-number footer. Reserves space above the bottom margin. Default: false. */
+  pageNumbers?: boolean | PageNumberOptions;
+  /** Reject larger documents. Default: 100; maximum: 1000. */
+  maxPages?: number;
+}

package/vendor/README.md

@@ -0,0 +1,17 @@
+# Stylo paged-media patch
+
+`stylo/` is the unmodified crates.io `stylo` 0.22.0 source except for:
+
+- `properties/longhands.toml`: enable `break-before`, `break-after`, and
+  `break-inside` for Servo; add inherited positive-integer `widows` and `orphans`.
+- `properties/shorthands.toml`: enable the three legacy `page-break-*` aliases.
+- `properties/counted_unknown_properties.py`: stop classifying widows/orphans as unknown.
+- `values/specified/box.rs`: parse `avoid-page`, `recto`, and `verso` break values.
+
+Upstream exposes break properties only in Gecko builds. Enabling them here lets
+Blitz's actual Stylo cascade handle selectors, inheritance, media queries, CSS
+variables, inline styles, and `!important`; no CSS rewriting is used.
+
+This directory retains its upstream MPL-2.0 license. The modified source ships in
+the npm archive. Update the patch when upgrading Stylo and run the pagination
+suite, especially the cascade and legacy-alias tests.

package/vendor/stylo/.cargo-ok

@@ -0,0 +1 @@
+{"v":1}

package/vendor/stylo/.cargo_vcs_info.json

@@ -0,0 +1,6 @@
+{
+  "git": {
+    "sha1": "34d25f741765a0bdb894f8271852e633299352d8"
+  },
+  "path_in_vcs": "style"
+}