@mccaskie-labs/workbench-pdf 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @mccaskie-labs/workbench-pdf
+
+## 0.1.1
+
+### Patch Changes
+
+- No code change. The first version published by the publish workflow, which confirms the package's npm trusted publisher.
+
+## 0.1.0
+
+- First version: `createPdfMaker` with the standard branded layout (`document`) and the app's own HTML (`html`), `renderDocument` for previews, and `WorkbenchPdfError` (`docs/spec.md` §10, 11 November 2026).

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @mccaskie-labs/workbench-pdf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Branded PDFs for apps built on Workbench, a private platform. The app's content is printed with its logo, colours and fonts, in the app's own Worker through Cloudflare Browser Rendering (now called Browser Run). Nothing goes through the Workbench Gateway and the app needs no API token: the Worker's `BROWSER` binding is the only access. Published publicly so Workbench projects can install it with no token; it is not supported for other uses.
+
+```sh
+npm install @mccaskie-labs/workbench-pdf @mccaskie-labs/workbench-config @cloudflare/puppeteer zod
+```
+
+`wrangler.jsonc`:
+
+```jsonc
+"compatibility_flags": ["nodejs_compat"],
+"browser": { "binding": "BROWSER" }
+```
+
+```ts
+import { defineBrand } from '@mccaskie-labs/workbench-config'
+import { createPdfMaker } from '@mccaskie-labs/workbench-pdf'
+import brandFile from '../brand.json'
+
+const brand = defineBrand(brandFile)
+
+export default {
+  async fetch(req, env) {
+    const pdf = createPdfMaker({ browser: env.BROWSER, brand })
+    const bytes = await pdf.document({
+      title: 'Invoice WBP-0042',
+      subtitle: 'Probe runs for October 2026',
+      date: '11 November 2026',
+      blocks: [
+        { type: 'facts', items: [{ label: 'Due', value: '25 November 2026' }] },
+        { type: 'table', columns: ['Item', 'Amount'], align: ['left', 'right'], rows: [['Image probe', '₱112.50']] },
+        { type: 'note', text: 'Paid by card on file.' },
+      ],
+    })
+    return new Response(bytes, { headers: { 'content-type': 'application/pdf' } })
+  },
+}
+```
+
+| Export | What it does |
+| --- | --- |
+| `createPdfMaker({ browser, brand, size?, timeoutMs? })` | The maker. Checks the brand at once (`invalid_brand`). `size` is `A4` (default) or `Letter`; `timeoutMs` is 1,000 to 120,000, default 30,000 |
+| `pdf.document(doc, { size?, landscape? })` | The standard layout: logo and name across the top, the title, subtitle and date, then the blocks; the footer on every page has the name, site, `footer` line and "Page n of m". Returns the PDF bytes |
+| `pdf.html(body, { title, standardStyles?, header?, javascript?, allowOrigins?, size?, landscape? })` | The app's own HTML (a body fragment, trusted as given) with the brand's fonts, colours, header and footer. The brand is in CSS variables: `--brand-primary`, `--brand-text`, `--brand-background`, `--brand-muted`, `--brand-heading-font`, `--brand-body-font` |
+| `pdf.renderDocument(doc)` | The standard layout's HTML without printing, for previews and tests |
+| `WorkbenchPdfError` | Every failure: `code` and `retryable` |
+
+Blocks for `document()`, all plain text (escaped; there is no way to pass HTML): `heading` (`level` 2 or 3), `paragraph`, `list` (`ordered?`), `table` (`columns`, `rows`, `align?` of `left` or `right` per column), `facts` (label and value pairs), `note` and `pageBreak`. Format dates, numbers and money with the app's country pack before passing them in. Limits: 2,000 blocks, 20,000 characters in one text and 2,000,000 in all.
+
+**What the page can reach.** It runs no script (unless `html()` gets `javascript: true`) and loads nothing but `data:` URIs and the brand's font stylesheets (Google Fonts' font files included), plus any https origins the app lists in `allowOrigins`. The logo is fetched once per maker by the Worker, checked (PNG, JPEG or SVG, at most 1 MiB) and inlined. One browser is opened per PDF and always closed.
+
+Error codes: `invalid_document`, `invalid_brand`, `logo_unavailable`, `browser_unavailable` (no binding, or Browser Rendering's limit reached; retryable), `timeout` and `render_failed` (both retryable). Messages never include the document's text. The package doesn't retry.
+
+**Cost.** Browser time is billed per account: Workers Paid includes 10 browser hours and 10 concurrent browsers a month, then US$0.09 an hour and US$2 a browser (checked 11 November 2026). A PDF takes a few seconds. On Workers Free the limit is 10 minutes a day.
+
+**Tests.** Pass `launch` (a fake browser) and `fetch` (a fake logo host) to `createPdfMaker`; nothing then reaches the network. Local `wrangler dev` runs the binding against a local Chrome.
+
+Runs in the Cloudflare Workers runtime (with `nodejs_compat`). `@cloudflare/puppeteer` 1.4 or later and `zod` 4 are peer dependencies.

package/dist/brand.d.ts

@@ -0,0 +1,12 @@
+import { type Brand, type ResolvedBrand } from "@mccaskie-labs/workbench-config";
+export interface PrintFont {
+    family: string;
+    url?: string;
+}
+export type PrintBrand = ResolvedBrand & {
+    print: {
+        heading: PrintFont;
+        body: PrintFont;
+    };
+};
+export declare function printBrand(input: Brand | ResolvedBrand): PrintBrand;

package/dist/brand.js

@@ -0,0 +1,17 @@
+// The app's brand file (brand.json, checked by workbench-config's
+// defineBrand), checked again here so a hand-built object fails clearly, with
+// the fonts filled in for print.
+import { brandSchema, resolveBrand } from "@mccaskie-labs/workbench-config";
+import { WorkbenchPdfError } from "./errors.js";
+const SYSTEM = { family: "system-ui" };
+export function printBrand(input) {
+    const result = brandSchema.safeParse(input);
+    if (!result.success) {
+        const fields = [...new Set(result.error.issues.map((i) => i.path.join(".") || "(brand)"))];
+        throw new WorkbenchPdfError("invalid_brand", `brand: check ${fields.join(", ")}`);
+    }
+    const brand = resolveBrand(result.data);
+    const body = brand.fonts?.body ?? SYSTEM;
+    const heading = brand.fonts?.heading ?? body;
+    return { ...brand, print: { heading, body } };
+}

package/dist/document.d.ts

@@ -0,0 +1,40 @@
+export type Block = {
+    type: "heading";
+    text: string;
+    level?: 2 | 3;
+} | {
+    type: "paragraph";
+    text: string;
+} | {
+    type: "list";
+    items: string[];
+    ordered?: boolean;
+} | {
+    type: "table";
+    columns: string[];
+    rows: string[][];
+    align?: ("left" | "right")[];
+} | {
+    type: "facts";
+    items: {
+        label: string;
+        value: string;
+    }[];
+} | {
+    type: "note";
+    text: string;
+} | {
+    type: "pageBreak";
+};
+export interface PdfDocument {
+    title: string;
+    subtitle?: string;
+    /** Shown under the title as given; format it with the app's country pack. */
+    date?: string;
+    blocks: Block[];
+}
+export declare const MAX_BLOCKS = 2000;
+export declare const MAX_TEXT = 20000;
+export declare const MAX_TOTAL_TEXT = 2000000;
+/** Throws `invalid_document` naming the first problem. Never echoes the text. */
+export declare function checkDocument(doc: PdfDocument): void;

package/dist/document.js

@@ -0,0 +1,84 @@
+// The standard layout's content: plain text in a few block types. Every
+// string is text, escaped when the page is built; there is no way to pass
+// HTML here (use `html()` for the app's own markup).
+import { WorkbenchPdfError } from "./errors.js";
+export const MAX_BLOCKS = 2000;
+export const MAX_TEXT = 20_000;
+export const MAX_TOTAL_TEXT = 2_000_000;
+const bad = (what) => {
+    throw new WorkbenchPdfError("invalid_document", what);
+};
+/** Throws `invalid_document` naming the first problem. Never echoes the text. */
+export function checkDocument(doc) {
+    if (typeof doc !== "object" || doc === null)
+        bad("document is missing");
+    let total = 0;
+    const text = (v, where, optional = false) => {
+        if (optional && v === undefined)
+            return;
+        if (typeof v !== "string")
+            bad(`${where} must be text`);
+        const s = v;
+        if (s.length > MAX_TEXT)
+            bad(`${where} is longer than ${MAX_TEXT} characters`);
+        total += s.length;
+    };
+    text(doc.title, "title");
+    if (doc.title.trim() === "")
+        bad("title is empty");
+    text(doc.subtitle, "subtitle", true);
+    text(doc.date, "date", true);
+    if (!Array.isArray(doc.blocks))
+        bad("blocks must be a list");
+    if (doc.blocks.length > MAX_BLOCKS)
+        bad(`more than ${MAX_BLOCKS} blocks`);
+    doc.blocks.forEach((b, i) => {
+        const at = `blocks[${i}]`;
+        switch (b?.type) {
+            case "heading":
+                text(b.text, `${at}.text`);
+                if (b.level !== undefined && b.level !== 2 && b.level !== 3)
+                    bad(`${at}.level must be 2 or 3`);
+                break;
+            case "paragraph":
+            case "note":
+                text(b.text, `${at}.text`);
+                break;
+            case "list":
+                if (!Array.isArray(b.items))
+                    bad(`${at}.items must be a list`);
+                b.items.forEach((item, j) => text(item, `${at}.items[${j}]`));
+                break;
+            case "table": {
+                if (!Array.isArray(b.columns) || b.columns.length === 0)
+                    bad(`${at}.columns must be a non-empty list`);
+                b.columns.forEach((c, j) => text(c, `${at}.columns[${j}]`));
+                if (!Array.isArray(b.rows))
+                    bad(`${at}.rows must be a list`);
+                b.rows.forEach((row, r) => {
+                    if (!Array.isArray(row) || row.length !== b.columns.length)
+                        bad(`${at}.rows[${r}] must have ${b.columns.length} cells`);
+                    row.forEach((cell, j) => text(cell, `${at}.rows[${r}][${j}]`));
+                });
+                if (b.align !== undefined && (!Array.isArray(b.align) || b.align.some((a) => a !== "left" && a !== "right"))) {
+                    bad(`${at}.align must list "left" or "right"`);
+                }
+                break;
+            }
+            case "facts":
+                if (!Array.isArray(b.items))
+                    bad(`${at}.items must be a list`);
+                b.items.forEach((f, j) => {
+                    text(f?.label, `${at}.items[${j}].label`);
+                    text(f?.value, `${at}.items[${j}].value`);
+                });
+                break;
+            case "pageBreak":
+                break;
+            default:
+                bad(`${at}.type is not a known block`);
+        }
+    });
+    if (total > MAX_TOTAL_TEXT)
+        bad(`more than ${MAX_TOTAL_TEXT} characters in all`);
+}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export type PdfErrorCode = "invalid_document" | "invalid_brand" | "logo_unavailable" | "browser_unavailable" | "timeout" | "render_failed";
+export declare class WorkbenchPdfError extends Error {
+    readonly code: PdfErrorCode;
+    readonly retryable: boolean;
+    constructor(code: PdfErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+// Every failure the package raises is a WorkbenchPdfError with a stable code.
+// Callers branch on `code`, never on the message. Messages never include the
+// document's text.
+const RETRYABLE = new Set(["browser_unavailable", "timeout", "render_failed"]);
+export class WorkbenchPdfError extends Error {
+    code;
+    retryable;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "WorkbenchPdfError";
+        this.code = code;
+        this.retryable = RETRYABLE.has(code);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createPdfMaker } from "./maker.ts";
+export { WorkbenchPdfError, type PdfErrorCode } from "./errors.ts";
+export { MAX_BLOCKS, MAX_TEXT, MAX_TOTAL_TEXT } from "./document.ts";
+export { MAX_LOGO_BYTES } from "./logo.ts";
+export type { Block, PdfDocument } from "./document.ts";
+export type { BrowserBinding, BrowserLike, HtmlOptions, Launch, PageLike, PageSize, PdfMaker, PdfMakerOptions, PrintOptions, RequestLike } from "./maker.ts";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createPdfMaker } from "./maker.js";
+export { WorkbenchPdfError } from "./errors.js";
+export { MAX_BLOCKS, MAX_TEXT, MAX_TOTAL_TEXT } from "./document.js";
+export { MAX_LOGO_BYTES } from "./logo.js";

package/dist/layout.d.ts

@@ -0,0 +1,12 @@
+import type { PrintBrand } from "./brand.ts";
+import type { PdfDocument } from "./document.ts";
+/** The whole standard-layout page. `logoSrc` is normally a data: URI. */
+export declare function standardPage(brand: PrintBrand, doc: PdfDocument, logoSrc: string): string;
+/** The app's own HTML (trusted as given) inside the brand's page. */
+export declare function ownPage(brand: PrintBrand, body: string, title: string, opts: {
+    standardStyles: boolean;
+    header: boolean;
+    logoSrc: string;
+}): string;
+/** Chrome's print footer: its own small page, so every style is inline. */
+export declare function footerTemplate(brand: PrintBrand): string;

package/dist/layout.js

@@ -0,0 +1,104 @@
+// Builds the page the browser prints: the brand's look, then either the
+// standard layout's blocks or the app's own HTML.
+/** Plain text made safe in HTML text and quoted attributes. */
+const escape = (value) => value.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+// A family name inside a CSS string, so no value can end the string or the <style>.
+const cssString = (value) => `"${value.replace(/[\\"<>\n\r]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `)}"`;
+const stack = (f) => `${cssString(f.family)}, system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif`;
+/** The <head> parts every page shares: font stylesheets and the brand's CSS variables. */
+function brandHead(brand, title) {
+    const urls = [...new Set([brand.print.heading.url, brand.print.body.url].filter((u) => !!u))];
+    const links = urls.map((u) => `<link rel="stylesheet" href="${escape(u)}">`).join("");
+    const c = brand.colours;
+    return (`<meta charset="utf-8"><title>${escape(title)}</title>${links}` +
+        `<style>:root{--brand-primary:${c.primary};--brand-text:${c.text};--brand-background:${c.background};--brand-muted:${c.muted};` +
+        `--brand-heading-font:${stack(brand.print.heading)};--brand-body-font:${stack(brand.print.body)}}</style>`);
+}
+const STANDARD_CSS = `
+*{box-sizing:border-box}
+html{-webkit-print-color-adjust:exact;print-color-adjust:exact}
+body{margin:0;background:var(--brand-background);color:var(--brand-text);font-family:var(--brand-body-font);font-size:10.5pt;line-height:1.5}
+h1,h2,h3{font-family:var(--brand-heading-font);color:var(--brand-primary);line-height:1.25;margin:1.2em 0 .4em;break-after:avoid}
+h1{font-size:20pt;margin:0}
+h2{font-size:14pt}
+h3{font-size:11.5pt}
+p{margin:0 0 .7em}
+ul,ol{margin:0 0 .7em;padding-left:1.4em}
+li{margin:.15em 0}
+table{width:100%;border-collapse:collapse;margin:.4em 0 1em;font-size:9.5pt}
+thead{display:table-header-group}
+th{text-align:left;font-weight:600;background:color-mix(in srgb,var(--brand-primary) 12%,var(--brand-background));color:var(--brand-text)}
+th,td{padding:5px 8px;border-bottom:1px solid color-mix(in srgb,var(--brand-muted) 35%,transparent);vertical-align:top}
+tr{break-inside:avoid}
+.r{text-align:right;font-variant-numeric:tabular-nums}
+dl.facts{display:grid;grid-template-columns:max-content 1fr;gap:4px 16px;margin:.4em 0 1em}
+dl.facts dt{color:var(--brand-muted)}
+dl.facts dd{margin:0}
+.note{border-left:3px solid var(--brand-primary);background:color-mix(in srgb,var(--brand-primary) 6%,var(--brand-background));padding:8px 12px;margin:.4em 0 1em}
+.subtitle{color:var(--brand-muted);font-size:12pt;margin:.2em 0 0}
+.date{color:var(--brand-muted);font-size:9.5pt;margin:.3em 0 1.2em}
+.page-break{break-after:page}
+`;
+function logoTag(brand, src) {
+    const size = (brand.logo.width ? ` width="${brand.logo.width}"` : "") + (brand.logo.height ? ` height="${brand.logo.height}"` : "");
+    return `<img src="${escape(src)}" alt="${escape(brand.logo.alt ?? brand.name)}"${size}>`;
+}
+const HEADER_CSS = `.brand-head{display:flex;align-items:center;justify-content:space-between;gap:16px;padding-bottom:12px;margin-bottom:18px;border-bottom:2px solid var(--brand-primary)}.brand-head img{max-height:48px;max-width:200px}.brand-head .name{font-family:var(--brand-heading-font);color:var(--brand-muted);font-size:9pt}`;
+/** The logo and the app's name across the top of the first page. */
+function brandHeader(brand, logoSrc) {
+    return `<header class="brand-head">${logoTag(brand, logoSrc)}<span class="name">${escape(brand.name)}</span></header>`;
+}
+function block(b) {
+    switch (b.type) {
+        case "heading": {
+            const tag = b.level === 3 ? "h3" : "h2";
+            return `<${tag}>${escape(b.text)}</${tag}>`;
+        }
+        case "paragraph":
+            return `<p>${escape(b.text)}</p>`;
+        case "note":
+            return `<div class="note">${escape(b.text)}</div>`;
+        case "list": {
+            const tag = b.ordered ? "ol" : "ul";
+            return `<${tag}>${b.items.map((i) => `<li>${escape(i)}</li>`).join("")}</${tag}>`;
+        }
+        case "table": {
+            const cls = (j) => (b.align?.[j] === "right" ? ' class="r"' : "");
+            const head = b.columns.map((c, j) => `<th${cls(j)}>${escape(c)}</th>`).join("");
+            const rows = b.rows.map((r) => `<tr>${r.map((c, j) => `<td${cls(j)}>${escape(c)}</td>`).join("")}</tr>`).join("");
+            return `<table><thead><tr>${head}</tr></thead><tbody>${rows}</tbody></table>`;
+        }
+        case "facts":
+            return `<dl class="facts">${b.items.map((f) => `<dt>${escape(f.label)}</dt><dd>${escape(f.value)}</dd>`).join("")}</dl>`;
+        case "pageBreak":
+            return `<div class="page-break"></div>`;
+    }
+}
+/** The whole standard-layout page. `logoSrc` is normally a data: URI. */
+export function standardPage(brand, doc, logoSrc) {
+    const sub = doc.subtitle ? `<p class="subtitle">${escape(doc.subtitle)}</p>` : "";
+    const date = doc.date ? `<p class="date">${escape(doc.date)}</p>` : `<div class="date"></div>`;
+    return (`<!doctype html><html><head>${brandHead(brand, doc.title)}<style>${STANDARD_CSS}${HEADER_CSS}</style></head><body>` +
+        `${brandHeader(brand, logoSrc)}<h1>${escape(doc.title)}</h1>${sub}${date}` +
+        `<main>${doc.blocks.map(block).join("")}</main></body></html>`);
+}
+/** The app's own HTML (trusted as given) inside the brand's page. */
+export function ownPage(brand, body, title, opts) {
+    const css = opts.standardStyles ? `<style>${STANDARD_CSS}</style>` : "";
+    const header = opts.header ? `<style>${HEADER_CSS}</style>${brandHeader(brand, opts.logoSrc)}` : "";
+    return `<!doctype html><html><head>${brandHead(brand, title)}${css}</head><body>${header}${body}</body></html>`;
+}
+/** Chrome's print footer: its own small page, so every style is inline. */
+export function footerTemplate(brand) {
+    let site = brand.siteUrl;
+    try {
+        site = new URL(brand.siteUrl).host;
+    }
+    catch {
+        // brand.siteUrl was checked; keep it as given.
+    }
+    const left = [brand.name, site, brand.footer].filter(Boolean).map((s) => escape(s)).join(" · ");
+    return (`<div style="width:100%;font-size:7.5pt;font-family:${escape(stack(brand.print.body))};color:${brand.colours.muted};` +
+        `padding:0 15mm;display:flex;justify-content:space-between;gap:12px">` +
+        `<span>${left}</span><span style="white-space:nowrap">Page <span class="pageNumber"></span> of <span class="totalPages"></span></span></div>`);
+}

package/dist/logo.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_LOGO_BYTES: number;
+/** The logo as a `data:` URI. PNG, JPEG or SVG only, at most 1 MiB, within `timeoutMs`. */
+export declare function logoDataUri(url: string, fetcher: typeof fetch, timeoutMs?: number): Promise<string>;

package/dist/logo.js

@@ -0,0 +1,43 @@
+// Fetches the brand logo once and inlines it as a data URI, so the browser
+// loads nothing from the logo's host and a slow host can't stall the print.
+import { WorkbenchPdfError } from "./errors.js";
+export const MAX_LOGO_BYTES = 1024 * 1024;
+function sniff(bytes) {
+    if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47)
+        return "image/png";
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    const head = new TextDecoder().decode(bytes.subarray(0, 512)).trimStart().toLowerCase();
+    if (head.startsWith("<svg") || (head.startsWith("<?xml") && head.includes("<svg")))
+        return "image/svg+xml";
+    return undefined;
+}
+function base64(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+const fail = (why, cause) => new WorkbenchPdfError("logo_unavailable", `logo: ${why}`, { cause });
+/** The logo as a `data:` URI. PNG, JPEG or SVG only, at most 1 MiB, within `timeoutMs`. */
+export async function logoDataUri(url, fetcher, timeoutMs = 10_000) {
+    let res;
+    try {
+        res = await fetcher(url, { redirect: "follow", signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (err) {
+        throw fail("could not be fetched", err);
+    }
+    if (!res.ok)
+        throw fail(`the host answered ${res.status}`);
+    const length = Number(res.headers.get("content-length") ?? "0");
+    if (length > MAX_LOGO_BYTES)
+        throw fail("larger than 1 MiB");
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.length > MAX_LOGO_BYTES)
+        throw fail("larger than 1 MiB");
+    const kind = sniff(bytes);
+    if (!kind)
+        throw fail("not PNG, JPEG or SVG");
+    return `data:${kind};base64,${base64(bytes)}`;
+}

package/dist/maker.d.ts

@@ -0,0 +1,71 @@
+import type { Brand, ResolvedBrand } from "@mccaskie-labs/workbench-config";
+import { type PdfDocument } from "./document.ts";
+/** A Browser Rendering binding: what `env.BROWSER` is. */
+export interface BrowserBinding {
+    fetch: typeof fetch;
+}
+/** The parts of a Puppeteer page the package uses. */
+export interface PageLike {
+    setJavaScriptEnabled(enabled: boolean): Promise<void>;
+    setRequestInterception(on: boolean): Promise<void>;
+    on(event: "request", handler: (request: RequestLike) => void): unknown;
+    setContent(html: string, options: {
+        waitUntil: "networkidle0";
+        timeout: number;
+    }): Promise<void>;
+    pdf(options: Record<string, unknown>): Promise<Uint8Array>;
+}
+export interface RequestLike {
+    url(): string;
+    isInterceptResolutionHandled?(): boolean;
+    continue(): Promise<void>;
+    abort(reason?: string): Promise<void>;
+}
+export interface BrowserLike {
+    newPage(): Promise<PageLike>;
+    close(): Promise<void>;
+}
+/** Opens a browser on the binding. Defaults to `@cloudflare/puppeteer`'s `launch`. */
+export type Launch = (binding: BrowserBinding) => Promise<BrowserLike>;
+export type PageSize = "A4" | "Letter";
+export interface PdfMakerOptions {
+    /** The Worker's Browser Rendering binding (`"browser": { "binding": "BROWSER" }` in wrangler.jsonc). */
+    browser: BrowserBinding | undefined;
+    /** The app's brand: `defineBrand(brandFile)` from workbench-config. */
+    brand: Brand | ResolvedBrand;
+    /** Default page size. A4 unless given. */
+    size?: PageSize;
+    /** Time allowed for one PDF, in ms. Default 30,000. */
+    timeoutMs?: number;
+    /** For tests. */
+    launch?: Launch;
+    /** For tests: fetches the logo. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+export interface PrintOptions {
+    size?: PageSize;
+    landscape?: boolean;
+}
+export interface HtmlOptions extends PrintOptions {
+    /** The PDF's title (document metadata). */
+    title: string;
+    /** The standard layout's typography under the app's HTML. Default true. */
+    standardStyles?: boolean;
+    /** The logo and name across the top of the first page. Default true. */
+    header?: boolean;
+    /** Let the page run its own script. Default false. */
+    javascript?: boolean;
+    /** https origins the page may load from, besides the brand's fonts, e.g. ["https://images.example.com"]. */
+    allowOrigins?: string[];
+}
+export interface PdfMaker {
+    /** The standard branded layout. */
+    document(doc: PdfDocument, options?: PrintOptions): Promise<Uint8Array>;
+    /** The app's own HTML (a body fragment, trusted as given) with the brand's fonts, colours and footer. */
+    html(body: string, options: HtmlOptions): Promise<Uint8Array>;
+    /** The standard layout's HTML, without printing: for previews and tests. */
+    renderDocument(doc: PdfDocument): Promise<string>;
+}
+/** Whether the page may load `url`. data: and about: always; https only from `origins`. */
+export declare function allowed(url: string, origins: readonly string[]): boolean;
+export declare function createPdfMaker(options: PdfMakerOptions): PdfMaker;

package/dist/maker.js

@@ -0,0 +1,164 @@
+// Prints a page to PDF in the app's own Worker through its Browser Rendering
+// binding. One browser per PDF, always closed. The page runs no script unless
+// the app asks, and may load nothing but data: URIs and the brand's fonts
+// (plus origins the app names), so content can't reach other hosts.
+import { printBrand } from "./brand.js";
+import { checkDocument } from "./document.js";
+import { WorkbenchPdfError } from "./errors.js";
+import { footerTemplate, ownPage, standardPage } from "./layout.js";
+import { logoDataUri } from "./logo.js";
+const GOOGLE_FONT_FILES = "https://fonts.gstatic.com";
+function fontOrigins(brand) {
+    const out = new Set();
+    for (const f of [brand.print.heading, brand.print.body]) {
+        if (!f.url)
+            continue;
+        const origin = new URL(f.url).origin;
+        out.add(origin);
+        if (origin === "https://fonts.googleapis.com")
+            out.add(GOOGLE_FONT_FILES);
+    }
+    return [...out];
+}
+function checkOrigins(list) {
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list))
+        throw new WorkbenchPdfError("invalid_document", "allowOrigins must be a list");
+    return list.map((o) => {
+        let url;
+        try {
+            url = new URL(o);
+        }
+        catch {
+            throw new WorkbenchPdfError("invalid_document", "allowOrigins must be https origins");
+        }
+        if (url.protocol !== "https:" || url.origin !== o.replace(/\/$/, ""))
+            throw new WorkbenchPdfError("invalid_document", "allowOrigins must be https origins");
+        return url.origin;
+    });
+}
+/** Whether the page may load `url`. data: and about: always; https only from `origins`. */
+export function allowed(url, origins) {
+    if (url.startsWith("data:") || url === "about:blank")
+        return true;
+    try {
+        const u = new URL(url);
+        return u.protocol === "https:" && origins.includes(u.origin);
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultLaunch(binding) {
+    const puppeteer = await import("@cloudflare/puppeteer");
+    return (await puppeteer.default.launch(binding));
+}
+function withTimeout(work, ms) {
+    let timer;
+    const limit = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new WorkbenchPdfError("timeout", `the PDF took longer than ${ms} ms`)), ms);
+    });
+    return Promise.race([work, limit]).finally(() => clearTimeout(timer));
+}
+const isLimit = (err) => /429|rate limit|limit exceeded|too many/i.test(String(err?.message ?? err));
+export function createPdfMaker(options) {
+    const brand = printBrand(options.brand);
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 120_000) {
+        throw new WorkbenchPdfError("invalid_document", "timeoutMs must be between 1,000 and 120,000");
+    }
+    const launch = options.launch ?? defaultLaunch;
+    const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+    const fonts = fontOrigins(brand);
+    let logo;
+    // Fetched once per maker; a failure is not kept, so the next PDF tries again.
+    const logoSrc = () => {
+        logo ??= logoDataUri(brand.logo.url, fetcher).catch((err) => {
+            logo = undefined;
+            throw err;
+        });
+        return logo;
+    };
+    async function print(html, opts) {
+        const size = opts.size ?? options.size ?? "A4";
+        if (size !== "A4" && size !== "Letter")
+            throw new WorkbenchPdfError("invalid_document", 'size must be "A4" or "Letter"');
+        if (!options.browser || typeof options.browser.fetch !== "function") {
+            throw new WorkbenchPdfError("browser_unavailable", "no Browser Rendering binding: add \"browser\": { \"binding\": \"BROWSER\" } to wrangler.jsonc");
+        }
+        let browser;
+        let gaveUp = false;
+        try {
+            const opening = launch(options.browser);
+            // A browser that opens after the time limit is closed, not left running.
+            opening.then((late) => {
+                if (gaveUp)
+                    void late.close().catch(() => undefined);
+            }, () => undefined);
+            browser = await withTimeout(opening, timeoutMs).catch((err) => {
+                gaveUp = true;
+                throw err;
+            });
+        }
+        catch (err) {
+            if (err instanceof WorkbenchPdfError)
+                throw err;
+            throw new WorkbenchPdfError("browser_unavailable", isLimit(err) ? "Browser Rendering limit reached; try again shortly" : "could not open a browser", { cause: err });
+        }
+        try {
+            return await withTimeout((async () => {
+                const page = await browser.newPage();
+                await page.setJavaScriptEnabled(opts.javascript);
+                await page.setRequestInterception(true);
+                page.on("request", (req) => {
+                    if (req.isInterceptResolutionHandled?.())
+                        return;
+                    void (allowed(req.url(), opts.origins) ? req.continue() : req.abort("blockedbyclient")).catch(() => undefined);
+                });
+                await page.setContent(html, { waitUntil: "networkidle0", timeout: timeoutMs });
+                const bytes = await page.pdf({
+                    format: size,
+                    landscape: opts.landscape === true,
+                    printBackground: true,
+                    displayHeaderFooter: true,
+                    headerTemplate: "<span></span>",
+                    footerTemplate: footerTemplate(brand),
+                    margin: { top: "15mm", bottom: "18mm", left: "15mm", right: "15mm" },
+                    timeout: timeoutMs,
+                });
+                return new Uint8Array(bytes);
+            })(), timeoutMs);
+        }
+        catch (err) {
+            if (err instanceof WorkbenchPdfError)
+                throw err;
+            const timedOut = /timeout|timed out/i.test(String(err?.message ?? err));
+            throw new WorkbenchPdfError(timedOut ? "timeout" : "render_failed", timedOut ? "the page did not finish loading" : "the browser failed while printing", { cause: err });
+        }
+        finally {
+            await browser.close().catch(() => undefined);
+        }
+    }
+    async function renderDocument(doc) {
+        checkDocument(doc);
+        return standardPage(brand, doc, await logoSrc());
+    }
+    return {
+        renderDocument,
+        async document(doc, opts = {}) {
+            const html = await renderDocument(doc);
+            return print(html, { ...opts, javascript: false, origins: fonts });
+        },
+        async html(body, opts) {
+            if (typeof body !== "string" || body.length > 5_000_000)
+                throw new WorkbenchPdfError("invalid_document", "html must be text of at most 5,000,000 characters");
+            if (typeof opts?.title !== "string" || opts.title.trim() === "")
+                throw new WorkbenchPdfError("invalid_document", "title is required");
+            const origins = [...fonts, ...checkOrigins(opts.allowOrigins)];
+            const header = opts.header !== false;
+            const page = ownPage(brand, body, opts.title, { standardStyles: opts.standardStyles !== false, header, logoSrc: header ? await logoSrc() : "" });
+            return print(page, { ...opts, javascript: opts.javascript === true, origins });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@mccaskie-labs/workbench-pdf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Branded PDFs for Workbench apps: the app's content printed with its logo, colours and fonts, in its own Worker through the Browser Rendering binding.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mccaskie-labs/workbench.git",
+    "directory": "packages/pdf"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.check.json && tsc -p test/tsconfig.json",
+    "test": "vitest run",
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs"
+  },
+  "dependencies": {
+    "@mccaskie-labs/workbench-config": "^0.1.13"
+  },
+  "devDependencies": {
+    "@cloudflare/puppeteer": "1.4.0",
+    "@types/node": "24.19.2",
+    "vitest": "^5.1.0",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "@cloudflare/puppeteer": "^1.4.0",
+    "zod": "^4.1.0"
+  }
+}