fullbleed 0.1.5 → 0.3.0

package/dist/build.json

@@ -1,5 +1,5 @@
 {
-  "packageVersion": "0.1.5",
+  "packageVersion": "0.3.0",
   "engineVersion": "2.5.8",
   "engineSource": "https://crates.io/crates/fullbleed/2.5.8",
   "target": "wasm32-wasip1",
@@ -78,6 +78,18 @@
     "assets/fonts/Inter-Variable.ttf": {
       "bytes": 876576,
       "sha256": "29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031"
+    },
+    "dist/browser/client.js": {
+      "bytes": 12042,
+      "sha256": "9de6e9b58387b419bd9469d9ac462907cd1f17c787dc89c86ee5e2c96309c0bf"
+    },
+    "dist/browser/worker.js": {
+      "bytes": 52108,
+      "sha256": "732050b295547a95b2eef88926c64f442fe3cb399282bcfc3f7feb08393b35e5"
+    },
+    "dist/browser/asset-manifest.json": {
+      "bytes": 2398,
+      "sha256": "3438e91fa80490ff6bee2ed058c9e62abd91f4c2084bc5536d180a1f7ff14216"
     }
   }
 }

package/dist/index.d.cts

@@ -17,6 +17,8 @@ export interface RenderOptions {
   /** Default false: missing glyphs reject the job instead of silently emitting them. */
   allowMissingGlyphs?: boolean;
   signal?: AbortSignal;
+  /** Default: worker. Process starts a fresh Node child and waits for its exit. */
+  isolation?: 'worker' | 'process';
 }
 
 export interface RenderResult {
@@ -29,6 +31,9 @@ export interface RenderResult {
 
 export class FullbleedError extends Error {
   readonly code: string;
+  /** Present on PROCESS_FAILED errors after the child closes. */
+  readonly exitCode?: number | null;
+  readonly signal?: NodeJS.Signals | null;
   constructor(code: string, message: string, options?: ErrorOptions);
 }
 export function renderPdf(options: RenderOptions): Promise<RenderResult>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fullbleed",
-  "version": "0.1.5",
-  "description": "Generate PDFs from HTML and CSS in Node.js with the Fullbleed Rust engine, bundled fonts, and optional PNG previews.",
+  "version": "0.3.0",
+  "description": "Generate PDFs from HTML and CSS in Node.js or a browser worker with the Fullbleed Rust engine, bundled fonts, and optional PNG previews.",
   "type": "module",
   "main": "./src/index.cjs",
   "types": "./src/index.d.ts",
@@ -15,6 +15,10 @@
         "types": "./dist/index.d.cts",
         "default": "./src/index.cjs"
       }
+    },
+    "./browser": {
+      "types": "./src/browser.d.ts",
+      "default": "./dist/browser/client.js"
     }
   },
   "engines": {
@@ -31,7 +35,7 @@
     "build": "node tools/build.mjs",
     "prepack": "node tools/check-build.mjs",
     "test": "node --test test/*.test.mjs",
-    "check:types": "tsc -p tsconfig.json",
+    "check:types": "tsc -p tsconfig.json && tsc -p tsconfig.browser.json",
     "verify:native": "node tools/verify-native.mjs",
     "example": "node examples/invoice.mjs",
     "verify:pack": "node tools/verify-pack.mjs",
@@ -39,7 +43,9 @@
     "render:fonts": "node tools/render-font-subsets.mjs",
     "verify:fonts": "python tools/verify-font-subsets.py",
     "render:families": "node tools/render-font-families.mjs",
-    "verify:families": "python tools/verify-font-families.py output/font-families"
+    "verify:families": "python tools/verify-font-families.py output/font-families",
+    "build:browser": "node tools/build-browser.mjs",
+    "verify:browser:prepare": "node tools/prepare-browser-check.mjs"
   },
   "dependencies": {
     "@bjorn3/browser_wasi_shim": "0.4.2"
@@ -71,6 +77,10 @@
   },
   "devDependencies": {
     "@types/node": "22.20.5",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "esbuild": "0.28.2"
+  },
+  "bin": {
+    "fullbleed-browser-assets": "src/copy-browser-assets.cjs"
   }
 }

package/src/browser-worker.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+import { runEngine } from './engine-runner.js';
+
+const version = __FULLBLEED_PACKAGE_VERSION__;
+const engineVersion = __FULLBLEED_ENGINE_VERSION__;
+const files = __FULLBLEED_RUNTIME_FILES__;
+const fontNames = __FULLBLEED_FONT_NAMES__;
+const hex = bytes => Array.from(new Uint8Array(bytes), value => value.toString(16).padStart(2, '0')).join('');
+
+async function load(name) {
+  const url = new URL(name, self.location.href);
+  url.searchParams.set('v', version);
+  const response = await fetch(url, { credentials: 'omit', redirect: 'error' });
+  if (!response.ok) throw new Error(`Could not load ${name} (HTTP ${response.status}).`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.length !== files[name].bytes || hex(await crypto.subtle.digest('SHA-256', bytes)) !== files[name].sha256) {
+    throw new Error(`Bundled asset failed verification: ${name}.`);
+  }
+  return bytes;
+}
+
+self.addEventListener('message', async ({ data }) => {
+  let result;
+  try {
+    if (data?.type !== 'render') throw new Error('Invalid render request.');
+    const [wasm, ...fontBytes] = await Promise.all([load('engine.wasm'), ...fontNames.map(name => load('fonts/' + name))]);
+    const module = await WebAssembly.compile(wasm);
+    if (!WebAssembly.Module.imports(module).every(item => item.module === 'wasi_snapshot_preview1' && !item.name.startsWith('sock_'))) {
+      throw new Error('Unexpected WebAssembly host imports.');
+    }
+    result = await runEngine({ ...data.job, module,
+      fonts: [...fontNames.map((name, i) => ({ name: 'fonts/' + name, data: fontBytes[i] })), ...data.job.fonts] });
+  } catch (cause) {
+    result = { ok: false, code: 'ENGINE_LOAD_FAILED', message: 'Could not load the bundled Fullbleed engine: ' + cause.message };
+  }
+  self.postMessage({ type: 'result', engineVersion, ...result }, result.ok ? [result.pdf.buffer, ...result.previews.map(page => page.buffer)] : []);
+  self.close();
+}, { once: true });
+self.postMessage({ type: 'ready', protocol: 1, version, engineVersion });

package/src/browser.d.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+export interface BrowserRendererOptions {
+  /** Same-origin directory URL ending in /, containing the copied browser assets. */
+  assetBaseUrl: string | URL;
+}
+export interface BrowserRenderOptions {
+  html: string;
+  css?: string;
+  /** Additional TrueType font bytes; use the font family names in CSS. */
+  fonts?: readonly Uint8Array[];
+  /** Relative names referenced as assets/name.svg in document HTML/CSS. */
+  assets?: Readonly<Record<string, Uint8Array>>;
+  /** 0 disables previews (default); otherwise 36–300 DPI. */
+  previewDpi?: number;
+  /** Includes worker startup and asset loading. Default: 30000 ms. */
+  timeoutMs?: number;
+  maxPages?: number;
+  allowMissingGlyphs?: boolean;
+  signal?: AbortSignal;
+}
+export interface BrowserRenderResult {
+  pdf: Uint8Array<ArrayBuffer>;
+  previews: Uint8Array<ArrayBuffer>[];
+  pages: number;
+  missingGlyphs: number;
+  engineVersion: string;
+}
+export interface BrowserRenderer {
+  renderPdf(options: BrowserRenderOptions): Promise<BrowserRenderResult>;
+}
+export class FullbleedError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string, options?: ErrorOptions);
+}
+export function createRenderer(options: BrowserRendererOptions): BrowserRenderer;
+export const version: string;
+export const engineVersion: string;

package/src/browser.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MIT
+import input from './render-input.cjs';
+
+export const version = __FULLBLEED_PACKAGE_VERSION__;
+export const engineVersion = __FULLBLEED_ENGINE_VERSION__;
+export const FullbleedError = input.FullbleedError;
+const invalid = message => { throw new FullbleedError('INVALID_INPUT', message); };
+
+/** Create a browser renderer using the assets copied to your site's static directory. */
+export function createRenderer(options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) invalid('Pass an assetBaseUrl pointing to your hosted Fullbleed assets.');
+  for (const key of Object.keys(options)) if (key !== 'assetBaseUrl') invalid(`Unknown renderer option: ${key}`);
+  if (typeof globalThis.Worker !== 'function' || !globalThis.location || !globalThis.crypto?.subtle || !globalThis.WebAssembly) {
+    throw new FullbleedError('UNSUPPORTED_BROWSER', 'Use a browser with Web Workers, WebAssembly and Web Crypto over HTTPS or localhost.');
+  }
+  if (typeof options.assetBaseUrl !== 'string' && !(options.assetBaseUrl instanceof URL)) invalid('assetBaseUrl must be a URL or URL string.');
+  let base;
+  try { base = new URL(options.assetBaseUrl, globalThis.location.href); }
+  catch { invalid('assetBaseUrl is not a valid URL.'); }
+  if (!['http:', 'https:'].includes(base.protocol) || base.origin !== globalThis.location.origin || base.username || base.password || base.search || base.hash || !base.pathname.endsWith('/')) {
+    invalid('assetBaseUrl must be a same-origin HTTP(S) directory URL ending in /, without credentials, a query or a fragment.');
+  }
+  const entry = new URL('worker.js', base);
+  entry.searchParams.set('v', version);
+
+  async function renderPdf(options) {
+    const start = Date.now();
+    const job = input.normalize(options, { browser: true });
+    const aborted = () => new FullbleedError('ABORTED', 'PDF rendering was aborted.');
+    if (job.signal?.aborted) throw aborted();
+    const remaining = job.timeoutMs - (Date.now() - start);
+    if (remaining <= 0) throw new FullbleedError('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`);
+    return new Promise((resolve, reject) => {
+      let worker, timer, settled = false, ready = false;
+      const finish = (error, result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        job.signal?.removeEventListener('abort', abort);
+        // A caller may synchronously abort while a Worker constructor is being
+        // instrumented. Let its handle be assigned before requesting termination.
+        queueMicrotask(() => {
+          try { worker?.terminate(); }
+          catch (cause) { reject(new FullbleedError('WORKER_FAILED', 'Could not stop the render worker.', { cause })); return; }
+          if (error) reject(error); else resolve(result);
+        });
+      };
+      const abort = () => finish(aborted());
+      timer = setTimeout(() => finish(new FullbleedError('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`)), remaining);
+      job.signal?.addEventListener('abort', abort, { once: true });
+      if (job.signal?.aborted) { abort(); return; }
+      try {
+        worker = new Worker(entry.href, { type: 'module', name: 'Fullbleed PDF renderer', credentials: 'omit' });
+        worker.addEventListener('error', event => {
+          event.preventDefault();
+          finish(new FullbleedError('WORKER_FAILED', 'The rendering worker could not run. Check the copied assets and the site content security policy.'));
+        });
+        worker.addEventListener('messageerror', () => finish(new FullbleedError('WORKER_FAILED', 'The rendering worker returned an unreadable response.')));
+        worker.addEventListener('message', ({ data }) => {
+          if (settled) return;
+          if (!ready) {
+            if (data?.type !== 'ready' || data.protocol !== 1 || data.version !== version || data.engineVersion !== engineVersion) {
+              finish(new FullbleedError('VERSION_MISMATCH', 'The hosted browser assets do not match this package. Copy the assets again and deploy them together.'));
+              return;
+            }
+            ready = true;
+            try {
+              worker.postMessage({ type: 'render', job: {
+                html: job.html, css: 'body { font-family: Inter; }\n' + job.css,
+                fonts: job.customFonts, assets: job.assetFiles, previewDpi: job.previewDpi,
+                maxPages: job.maxPages, allowMissingGlyphs: job.allowMissingGlyphs,
+              } });
+            } catch (cause) { finish(new FullbleedError('WORKER_FAILED', 'Could not send the document to the rendering worker.', { cause })); }
+            return;
+          }
+          if (data?.type !== 'result' || typeof data.ok !== 'boolean') {
+            finish(new FullbleedError('WORKER_FAILED', 'The rendering worker returned an invalid response.'));
+            return;
+          }
+          if (!data.ok) {
+            finish(typeof data.code === 'string' && typeof data.message === 'string'
+              ? new FullbleedError(data.code, data.message)
+              : new FullbleedError('WORKER_FAILED', 'The rendering worker returned an invalid error.'));
+            return;
+          }
+          if (!(data.pdf instanceof Uint8Array) || new TextDecoder().decode(data.pdf.subarray(0, 5)) !== '%PDF-'
+            || !Number.isSafeInteger(data.pages) || data.pages < 1 || data.pages > job.maxPages
+            || !Array.isArray(data.previews) || data.previews.length !== (job.previewDpi ? data.pages : 0)
+            || !data.previews.every(bytes => bytes instanceof Uint8Array && [137, 80, 78, 71, 13, 10, 26, 10].every((value, i) => bytes[i] === value))
+            || !Number.isSafeInteger(data.missingGlyphs) || data.missingGlyphs < 0 || data.engineVersion !== engineVersion) {
+            finish(new FullbleedError('WORKER_FAILED', 'The rendering worker returned an invalid result.'));
+            return;
+          }
+          finish(null, { pdf: data.pdf, previews: data.previews, pages: data.pages, missingGlyphs: data.missingGlyphs, engineVersion });
+        });
+        if (job.signal?.aborted) abort();
+      } catch (cause) {
+        finish(new FullbleedError('WORKER_FAILED', 'Could not start the rendering worker.', { cause }));
+      }
+    });
+  }
+  return Object.freeze({ renderPdf });
+}

package/src/copy-browser-assets.cjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+'use strict';
+const { readFile, writeFile, mkdir } = require('node:fs/promises');
+const { resolve, join, dirname, relative, isAbsolute } = require('node:path');
+const { createHash } = require('node:crypto');
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    console.log('Usage: fullbleed-browser-assets OUTPUT_DIRECTORY\nCopies the browser client, worker, engine, fonts and license notices. Existing runtime files in the named directory are replaced.');
+    return;
+  }
+  if (args.length !== 1 || args[0].startsWith('-') || !args[0].trim()) throw new Error('Pass one output directory, for example: fullbleed-browser-assets public/fullbleed');
+  const root = resolve(__dirname, '..');
+  const destination = resolve(args[0]);
+  const inside = relative(root, destination);
+  if (!inside || (!inside.startsWith('..') && !isAbsolute(inside))) throw new Error('Choose an output directory outside the installed Fullbleed package.');
+  const manifest = JSON.parse(await readFile(join(root, 'dist/browser/asset-manifest.json'), 'utf8'));
+  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  if (manifest.schema !== 'fullbleed.browser-assets.v1' || manifest.packageVersion !== pkg.version || manifest.engineVersion !== pkg.fullbleed.engineVersion) throw new Error('The browser build does not match the installed package.');
+  const files = [];
+  for (const [name, record] of Object.entries(manifest.files)) {
+    for (const path of [name, record.source]) {
+      if (typeof path !== 'string' || /[\\:\0]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) throw new Error('The browser asset manifest contains an invalid path.');
+    }
+    const data = await readFile(join(root, record.source));
+    if (data.length !== record.bytes || createHash('sha256').update(data).digest('hex') !== record.sha256) throw new Error('The installed browser asset failed verification: ' + name);
+    files.push({ name, data, bytes: record.bytes, sha256: record.sha256 });
+  }
+  // Verify the complete installed set before writing any output files.
+  for (const file of files) {
+    const path = join(destination, file.name);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, file.data);
+  }
+  await writeFile(join(destination, 'build.json'), JSON.stringify({ schema: manifest.schema,
+    packageVersion: pkg.version, engineVersion: manifest.engineVersion,
+    files: Object.fromEntries(files.map(({ name, bytes, sha256 }) => [name, { bytes, sha256 }])) }, null, 2) + '\n');
+  console.log(JSON.stringify({ ok: true, directory: destination, packageVersion: pkg.version,
+    engineVersion: manifest.engineVersion, files: files.length + 1, bytes: files.reduce((sum, file) => sum + file.bytes, 0) }));
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/src/engine-runner.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+import { WASI, File, OpenFile, Directory, ConsoleStdout, PreopenDirectory } from '@bjorn3/browser_wasi_shim';
+
+export async function runEngine(job) {
+  try {
+    const root = new PreopenDirectory('.', new Map());
+    const put = (path, data) => {
+      const parts = path.split('/');
+      let directory = root.dir;
+      for (const part of parts.slice(0, -1)) {
+        if (!directory.contents.has(part)) directory.contents.set(part, new Directory(new Map()));
+        directory = directory.contents.get(part);
+      }
+      directory.contents.set(parts.at(-1), new File(data));
+    };
+    const encoder = new TextEncoder();
+    put('input.html', encoder.encode(job.html));
+    put('style.css', encoder.encode(job.css));
+    for (const file of [...job.fonts, ...job.assets]) put(file.name, file.data);
+    let log = '';
+    const collect = line => { if (log.length < 4000) log += String(line).slice(0, 4000 - log.length) + '\n'; };
+    const wasi = new WASI(['fullbleed', String(job.maxPages), String(job.previewDpi), job.allowMissingGlyphs ? 'allow' : 'reject', ...job.fonts.map(f => f.name)], [], [
+      new OpenFile(new File([])), ConsoleStdout.lineBuffered(collect), ConsoleStdout.lineBuffered(collect), root,
+    ], { debug: false });
+    const instance = await WebAssembly.instantiate(job.module, { wasi_snapshot_preview1: wasi.wasiImport });
+    const status = wasi.start(instance);
+    if (status !== 0) {
+      const code = ['PAGE_LIMIT', 'MISSING_GLYPHS', 'PREVIEW_FAILED'].find(c => log.includes(c + ':')) ?? 'RENDER_FAILED';
+      return { ok: false, code, message: log.trim() || `The engine exited with code ${status}.` };
+    } else {
+      const read = name => {
+        const file = root.dir.contents.get(name);
+        if (!(file instanceof File)) throw new Error(`Missing engine output: ${name}`);
+        return Uint8Array.from(file.data);
+      };
+      const report = JSON.parse(new TextDecoder().decode(read('result.json')));
+      const pdf = read('document.pdf');
+      if (new TextDecoder().decode(pdf.slice(0, 5)) !== '%PDF-') throw new Error('Engine output is not a PDF.');
+      const previews = job.previewDpi ? Array.from({ length: report.pages }, (_, i) => read(`preview-${i + 1}.png`)) : [];
+      return { ok: true, pdf, previews, ...report };
+    }
+  } catch (cause) {
+    const code = cause instanceof WebAssembly.RuntimeError || cause instanceof RangeError ? 'ENGINE_LIMIT' : 'RENDER_FAILED';
+    return { ok: false, code, message: cause.message || String(cause) };
+  }
+}

package/src/index.cjs

@@ -4,20 +4,12 @@ const { readFile } = require('node:fs/promises');
 const { createHash } = require('node:crypto');
 const { join } = require('node:path');
 const { Worker } = require('node:worker_threads');
+const { fork } = require('node:child_process');
 const { pathToFileURL } = require('node:url');
 const pkg = require('../package.json');
 
-class FullbleedError extends Error {
-  constructor(code, message, options) {
-    super(message, options);
-    this.name = 'FullbleedError';
-    this.code = code;
-  }
-}
-const invalid = message => { throw new FullbleedError('INVALID_INPUT', message); };
+const { FullbleedError, normalize } = require('./render-input.cjs');
 const hash = bytes => createHash('sha256').update(bytes).digest('hex');
-const sourceLimit = 4_000_000;
-const assetLimit = 64 * 1024 * 1024;
 const root = join(__dirname, '..');
 let runtimePromise;
 
@@ -43,38 +35,121 @@ function runtime() {
   return runtimePromise;
 }
 
-function normalize(options) {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) invalid('Pass an options object with an html string.');
-  const supported = new Set(['html', 'css', 'fonts', 'assets', 'previewDpi', 'timeoutMs', 'maxPages', 'allowMissingGlyphs', 'signal']);
-  for (const key of Object.keys(options)) if (!supported.has(key)) invalid(`Unknown option: ${key}`);
-  const { html, css = '', fonts = [], assets = {}, previewDpi = 0, timeoutMs = 30000, maxPages = 1000, allowMissingGlyphs = false, signal } = options;
-  if (typeof html !== 'string' || !html.trim()) invalid('html must be a nonempty string.');
-  if (typeof css !== 'string') invalid('css must be a string.');
-  if (Buffer.byteLength(html) + Buffer.byteLength(css) > sourceLimit) invalid('HTML and CSS together must not exceed 4,000,000 UTF-8 bytes.');
-  if (!Number.isInteger(previewDpi) || (previewDpi !== 0 && (previewDpi < 36 || previewDpi > 300))) invalid('previewDpi must be 0 (disabled) or an integer from 36 to 300.');
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) invalid('timeoutMs must be a positive integer no greater than 2147483647.');
-  if (!Number.isSafeInteger(maxPages) || maxPages < 1) invalid('maxPages must be a positive integer.');
-  if (typeof allowMissingGlyphs !== 'boolean') invalid('allowMissingGlyphs must be a boolean.');
-  if (signal !== undefined && !(signal instanceof AbortSignal)) invalid('signal must be an AbortSignal.');
-  if (!Array.isArray(fonts)) invalid('fonts must be an array of font byte arrays.');
-  if (!assets || typeof assets !== 'object' || Array.isArray(assets)) invalid('assets must map relative names to byte arrays.');
-  let assetBytes = 0;
-  function bytes(value, label) {
-    if (!(value instanceof Uint8Array) || !value.byteLength) invalid(`${label} must be a nonempty Uint8Array or Buffer.`);
-    assetBytes += value.byteLength;
-    if (assetBytes > assetLimit) invalid('Custom fonts and assets together must not exceed 64 MiB.');
-    return Uint8Array.from(value); // Snapshot caller-owned buffers before any await.
-  }
-  const customFonts = fonts.map((font, i) => ({ name: `fonts/custom-${i}.ttf`, data: bytes(font, `fonts[${i}]`) }));
-  const names = Object.keys(assets);
-  const fileNames = new Set(names);
-  const assetFiles = names.map(name => {
-    const segments = name.split('/');
-    if (!name || /[\\:\0]/.test(name) || segments.some(s => !s || s === '.' || s === '..')) invalid(`Invalid asset path: ${name}`);
-    for (let i = 1; i < segments.length; i++) if (fileNames.has(segments.slice(0, i).join('/'))) invalid(`Asset is both a file and a directory: ${name}`);
-    return { name: 'assets/' + name, data: bytes(assets[name], `assets[${name}]`) };
+function renderProcess(job, remaining) {
+  return new Promise((resolve, reject) => {
+    let child, timer, closed = false, failure, reply, exited, disconnected = false;
+    const timeout = () => new FullbleedError('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`);
+    const cleanup = () => {
+      clearTimeout(timer);
+      job.signal?.removeEventListener('abort', abort);
+    };
+    const stop = error => {
+      if (closed || failure) return;
+      failure = error;
+      // Cancellation can occur synchronously inside fork instrumentation. Wait
+      // until the returned process handle has been assigned before killing it.
+      queueMicrotask(() => {
+        if (!closed && child?.pid) child.kill('SIGKILL');
+      });
+    };
+    const abort = () => stop(new FullbleedError('ABORTED', 'PDF rendering was aborted.'));
+    timer = setTimeout(() => stop(timeout()), remaining);
+    job.signal?.addEventListener('abort', abort, { once: true });
+    if (job.signal?.aborted) {
+      cleanup();
+      reject(new FullbleedError('ABORTED', 'PDF rendering was aborted.'));
+      return;
+    }
+    try {
+      const env = { ...process.env };
+      // The bundled child needs no application preloads, inspector, eval script,
+      // or custom loader. Avoid replaying them in a fresh application process.
+      for (const key of Object.keys(env)) if (key.toUpperCase() === 'NODE_OPTIONS') delete env[key];
+      child = fork(join(__dirname, 'process-worker.cjs'), [], {
+        execPath: process.execPath, execArgv: [], env,
+        serialization: 'advanced', stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        windowsHide: true,
+      });
+      child.on('error', cause => stop(new FullbleedError('PROCESS_FAILED', 'The rendering process failed.', { cause })));
+      child.on('message', message => {
+        if (reply || message?.type !== 'result' || typeof message.ok !== 'boolean') {
+          stop(new FullbleedError('PROCESS_FAILED', 'The rendering process returned an invalid response.'));
+          return;
+        }
+        const result = message.result;
+        if (message.ok
+          ? !(result?.pdf instanceof Uint8Array) || Buffer.from(result.pdf.subarray(0, 5)).toString() !== '%PDF-'
+            || !Number.isSafeInteger(result.pages) || result.pages < 1 || result.pages > job.maxPages
+            || !Array.isArray(result.previews) || result.previews.length !== (job.previewDpi ? result.pages : 0)
+            || !Array.from(result.previews).every(bytes => bytes instanceof Uint8Array
+              && Buffer.from(bytes.subarray(0, 8)).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+            || !Number.isSafeInteger(result.missingGlyphs) || result.missingGlyphs < 0
+            || result.engineVersion !== pkg.fullbleed.engineVersion
+          : typeof message.code !== 'string' || typeof message.message !== 'string') {
+          stop(new FullbleedError('PROCESS_FAILED', 'The rendering process returned an invalid result.'));
+          return;
+        }
+        reply = message;
+      });
+      const finish = (code, signal) => {
+        if (closed) return;
+        closed = true;
+        cleanup();
+        // Receiving PDF bytes is insufficient: a native crash during shutdown
+        // must reject the request, even if its result was sent before the crash.
+        if (!failure && (code !== 0 || signal || !reply)) {
+          failure = new FullbleedError('PROCESS_FAILED',
+            `Rendering process exited without completing successfully (code ${code}, signal ${signal ?? 'none'}).`);
+        }
+        if (failure) {
+          if (failure.code === 'PROCESS_FAILED') {
+            failure.exitCode = code;
+            failure.signal = signal;
+          }
+          reject(failure);
+        } else if (!reply.ok) {
+          reject(new FullbleedError(reply.code, reply.message));
+        } else {
+          const result = reply.result;
+          resolve({ pdf: Buffer.from(result.pdf), previews: result.previews.map(bytes => Buffer.from(bytes)),
+            pages: result.pages, missingGlyphs: result.missingGlyphs, engineVersion: result.engineVersion });
+        }
+      };
+      // All stdio is ignored except IPC. Waiting for both exit and disconnect
+      // drains messages and proves the process has stopped. On Windows, an
+      // interrupted IPC write can omit 'close' even after both these events.
+      child.once('exit', (code, signal) => {
+        exited = { code, signal };
+        if (disconnected) finish(code, signal);
+      });
+      child.once('disconnect', () => {
+        disconnected = true;
+        if (exited) finish(exited.code, exited.signal);
+      });
+      // A spawn error emits close without exit.
+      child.once('close', finish);
+      if (failure || job.signal?.aborted) {
+        if (!failure) abort();
+        return;
+      }
+      child.send({ type: 'render', options: {
+        html: job.html, css: job.css, fonts: job.customFonts.map(font => font.data),
+        assets: Object.fromEntries(job.assetFiles.map(file => [file.name.slice('assets/'.length), file.data])),
+        previewDpi: job.previewDpi, maxPages: job.maxPages, allowMissingGlyphs: job.allowMissingGlyphs,
+        timeoutMs: remaining,
+      } }, error => {
+        if (error) stop(new FullbleedError('PROCESS_FAILED', 'Could not send the rendering request.', { cause: error }));
+      });
+    } catch (cause) {
+      if (child) {
+        stop(new FullbleedError('PROCESS_FAILED', 'Could not start the rendering request.', { cause }));
+      } else {
+        closed = true;
+        cleanup();
+        reject(new FullbleedError('PROCESS_FAILED', 'Could not start the rendering process.', { cause }));
+      }
+    }
   });
-  return { html, css: 'body { font-family: Inter; }\n' + css, customFonts, assetFiles, previewDpi, timeoutMs, maxPages, allowMissingGlyphs, signal };
 }
 
 async function renderPdf(options) {
@@ -85,6 +160,7 @@ async function renderPdf(options) {
   if (job.signal?.aborted) throw aborted();
   const remaining = job.timeoutMs - (Date.now() - start);
   if (remaining <= 0) throw new FullbleedError('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`);
+  if (job.isolation === 'process') return renderProcess(job, remaining);
   return new Promise((resolve, reject) => {
     let worker, timer, settled = false;
     const finish = async (error, result) => {
@@ -116,7 +192,7 @@ async function renderPdf(options) {
         eval: true,
         workerData: {
           module: loaded.module, fonts: [...loaded.fonts, ...job.customFonts], assets: job.assetFiles,
-          html: job.html, css: job.css, previewDpi: job.previewDpi, maxPages: job.maxPages,
+          html: job.html, css: 'body { font-family: Inter; }\n' + job.css, previewDpi: job.previewDpi, maxPages: job.maxPages,
           allowMissingGlyphs: job.allowMissingGlyphs,
         },
       });

package/src/index.d.ts

@@ -17,6 +17,8 @@ export interface RenderOptions {
   /** Default false: missing glyphs reject the job instead of silently emitting them. */
   allowMissingGlyphs?: boolean;
   signal?: AbortSignal;
+  /** Default: worker. Process starts a fresh Node child and waits for its exit. */
+  isolation?: 'worker' | 'process';
 }
 
 export interface RenderResult {
@@ -29,6 +31,9 @@ export interface RenderResult {
 
 export class FullbleedError extends Error {
   readonly code: string;
+  /** Present on PROCESS_FAILED errors after the child closes. */
+  readonly exitCode?: number | null;
+  readonly signal?: NodeJS.Signals | null;
   constructor(code: string, message: string, options?: ErrorOptions);
 }
 export function renderPdf(options: RenderOptions): Promise<RenderResult>;

package/src/process-worker.cjs

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+'use strict';
+const { renderPdf } = require('./index.cjs');
+const controller = new AbortController();
+process.once('disconnect', () => controller.abort());
+process.once('message', async message => {
+  let reply;
+  try {
+    if (message?.type !== 'render') throw new Error('Invalid render request.');
+    const result = await renderPdf({ ...message.options, isolation: 'worker', signal: controller.signal });
+    reply = { type: 'result', ok: true, result };
+  } catch (error) {
+    reply = { type: 'result', ok: false, code: error.code ?? 'RENDER_FAILED', message: error.message };
+  }
+  if (!process.connected) return;
+  process.send(reply, error => {
+    if (error) process.exitCode = 1;
+    if (process.connected) process.disconnect();
+  });
+});