fullbleed 0.1.4 → 0.2.0

package/README.md

@@ -4,11 +4,12 @@ Generate PDFs from static HTML and CSS in Node.js. The package includes the
 Fullbleed Rust engine compiled to WebAssembly and four font faces, so installing
 it does not require Python, Rust, a browser, or system fonts. MIT licensed.
 
-This is an optional integration around the published **Fullbleed 2.5.7** engine.
-The Node package has its own version, **0.1.4**. This release reduces embedded
-font metadata while preserving the retained glyph outlines, metrics, and font
-notices. See the [installed-package font checks](docs/font-subsets.md) for the
-fixtures and verification commands.
+This is an optional integration around the published **Fullbleed 2.5.8** engine.
+The Node package has its own version, **0.2.0**. It adds optional process isolation
+for server applications. The engine and default worker mode are unchanged from
+0.1.5. See the [process isolation guide](docs/process-isolation.md),
+[font-family checks](https://github.com/fullbleed-engine/fullbleed-node/blob/main/docs/font-families.md), and
+[embedded-font checks](https://github.com/fullbleed-engine/fullbleed-node/blob/main/docs/font-subsets.md) for the retained fixtures.
 
 ## Install and render
 
@@ -18,9 +19,9 @@ Use Node.js 22 or newer. Install the [npm package](https://www.npmjs.com/package
 npm install fullbleed
 ```
 
-For a version-pinned installation, use `npm install --save-exact fullbleed@0.1.4`.
-The npm tarball is byte-identical to the verified
-[GitHub release](https://github.com/fullbleed-engine/fullbleed-node/releases/tag/v0.1.4).
+For a version-pinned installation, use `npm install --save-exact fullbleed@0.2.0`.
+Package archives and retained PDF/PNG evidence are attached to each
+[GitHub release](https://github.com/fullbleed-engine/fullbleed-node/releases).
 See the [installation verification records](https://github.com/fullbleed-engine/fullbleed-node/tree/main/verification).
 
 Save this as `invoice.mjs` and run `node invoice.mjs`:
@@ -120,6 +121,7 @@ native engine.
 | `maxPages` | Reject larger documents. Default: 1000. |
 | `timeoutMs` | Deadline including initial engine loading. Default: 30000 ms. |
 | `signal` | An `AbortSignal` to cancel rendering. |
+| `isolation` | `'worker'` (default) or `'process'` for a separate Node process per call. |
 | `allowMissingGlyphs` | Default `false`: reject engine-reported missing glyphs. |
 
 Rendering runs in a dedicated worker. Concurrent calls use separate workers and
@@ -128,6 +130,13 @@ render failure, timeout, or cancellation. Awaiting jobs in sequence therefore
 does not overlap their worker lifetimes. A timeout or abort starts termination;
 settlement includes the time needed to stop the worker.
 
+Use `isolation: 'process'` when a render-process failure should become a rejected
+request while the calling application stays running. This mode runs the engine
+and its worker in a fresh Node process, and waits for process exit and IPC
+disconnection before settling. It requires a host that permits child processes
+and adds startup and memory overhead. It does not pool processes or retry jobs.
+See the [guide and failure checks](docs/process-isolation.md).
+
 Bound concurrency in a server according to its available memory;
 each worker's WebAssembly memory has a 512 MiB ceiling. HTML and CSS together are
 limited to 4,000,000 UTF-8 bytes; supplied fonts and assets together to 64 MiB.
@@ -141,6 +150,7 @@ try {
     html: '<h1>Monthly statement</h1>',
     maxPages: 20,
     timeoutMs: 10_000,
+    isolation: 'process',
     signal: AbortSignal.timeout(8_000),
   });
   // Return result.pdf from your HTTP handler, or write it to your storage.
@@ -152,8 +162,9 @@ try {
 
 Error codes include `INVALID_INPUT`, `MISSING_GLYPHS`, `PAGE_LIMIT`, `TIMEOUT`,
 `ABORTED`, `ENGINE_LOAD_FAILED`, `ENGINE_LIMIT`, `RENDER_FAILED`,
-`PREVIEW_FAILED`, and `WORKER_FAILED`. Failed or cancelled calls do not return a
-partial PDF. Caller-owned asset buffers are copied when a call starts.
+`PREVIEW_FAILED`, `WORKER_FAILED`, and `PROCESS_FAILED`. Process failures may also
+include `exitCode` and `signal`. Failed or cancelled calls do not return a partial
+PDF. Caller-owned asset buffers are copied when a call starts.
 
 This API covers ordinary document generation and previews. It does not expose
 PDF/A, PDF/UA, PDF/X, template overlays, or compiled VDP. Use the
@@ -180,6 +191,8 @@ python -m pip install pypdf==6.19.0 pypdfium2==5.14.0 fonttools==4.65.0 pillow==
 npm run verify:text
 npm run render:fonts
 npm run verify:fonts
+npm run render:families
+npm run verify:families
 ```
 
 The build records engine metadata, licenses, and artifact hashes in `dist/`.
@@ -196,7 +209,8 @@ the previous public npm release.
 An intermittent process crash observed on Linux with Node 24.21.0 remains under
 investigation in [issue #7](https://github.com/fullbleed-engine/fullbleed-node/issues/7).
 Version 0.1.3 fixes worker shutdown timing, but does not establish that this crash
-is resolved. See the [runtime investigation and diagnostic](docs/runtime-diagnostics.md)
+is resolved. Version 0.2.0 adds optional process fault containment; it does not
+claim to fix the native crash. See the [runtime investigation and diagnostic](docs/runtime-diagnostics.md)
 for the observed scope, retained results, and a synthetic reproducer.
 
 ## License and support

package/dist/THIRD_PARTY_NOTICES.txt

@@ -1,4 +1,4 @@
-fullbleed 2.5.7 / LICENSE
+fullbleed 2.5.8 / LICENSE
 
 MIT License
 
@@ -23,7 +23,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
-fullbleed 2.5.7 / THIRD_PARTY_LICENSES.md
+fullbleed 2.5.8 / THIRD_PARTY_LICENSES.md
 
 <!-- SPDX-License-Identifier: MIT -->
 # Third-Party Licenses

package/dist/build.json

@@ -1,7 +1,7 @@
 {
-  "packageVersion": "0.1.4",
-  "engineVersion": "2.5.7",
-  "engineSource": "https://crates.io/crates/fullbleed/2.5.7",
+  "packageVersion": "0.2.0",
+  "engineVersion": "2.5.8",
+  "engineSource": "https://crates.io/crates/fullbleed/2.5.8",
   "target": "wasm32-wasip1",
   "memoryMaximumBytes": 536870912,
   "fonts": [
@@ -13,7 +13,7 @@
   "dependencies": [
     {
       "name": "fullbleed",
-      "version": "2.5.7",
+      "version": "2.5.8",
       "source": "registry+https://github.com/rust-lang/crates.io-index",
       "license": "MIT"
     },
@@ -44,12 +44,12 @@
   ],
   "files": {
     "dist/engine.wasm": {
-      "bytes": 5064368,
-      "sha256": "3b5b0200268264b947f7b5bdc658a2d32d9fd160b8652f0ee6834e5296db9abb"
+      "bytes": 5069661,
+      "sha256": "2f41ac7c2d85f7724166ea0d466cc55b6d6f5ca0014014d667f54f7ac93577cb"
     },
     "dist/THIRD_PARTY_NOTICES.txt": {
       "bytes": 57660,
-      "sha256": "90c2828609b2a61323dfd97564a023123e38e1df7c9e9a9db0a29bb12aad1438"
+      "sha256": "5475f50666d3af5df89048cc1ddc98d153cd813019afbc213be20e4f3838911f"
     },
     "assets/fonts/BebasNeue-OFL.txt": {
       "bytes": 4337,

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,6 +1,6 @@
 {
   "name": "fullbleed",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Generate PDFs from HTML and CSS in Node.js with the Fullbleed Rust engine, bundled fonts, and optional PNG previews.",
   "type": "module",
   "main": "./src/index.cjs",
@@ -37,7 +37,9 @@
     "verify:pack": "node tools/verify-pack.mjs",
     "verify:text": "python tools/verify-installed-text.py",
     "render:fonts": "node tools/render-font-subsets.mjs",
-    "verify:fonts": "python tools/verify-font-subsets.py"
+    "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"
   },
   "dependencies": {
     "@bjorn3/browser_wasi_shim": "0.4.2"
@@ -65,7 +67,7 @@
     "access": "public"
   },
   "fullbleed": {
-    "engineVersion": "2.5.7"
+    "engineVersion": "2.5.8"
   },
   "devDependencies": {
     "@types/node": "22.20.5",

package/src/index.cjs

@@ -4,6 +4,7 @@ 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');
 
@@ -45,9 +46,9 @@ function runtime() {
 
 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']);
+  const supported = new Set(['html', 'css', 'fonts', 'assets', 'previewDpi', 'timeoutMs', 'maxPages', 'allowMissingGlyphs', 'signal', 'isolation']);
   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;
+  const { html, css = '', fonts = [], assets = {}, previewDpi = 0, timeoutMs = 30000, maxPages = 1000, allowMissingGlyphs = false, signal, isolation = 'worker' } = 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.');
@@ -56,6 +57,7 @@ function normalize(options) {
   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 (isolation !== 'worker' && isolation !== 'process') invalid('isolation must be worker or process.');
   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;
@@ -74,7 +76,124 @@ function normalize(options) {
     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}]`) };
   });
-  return { html, css: 'body { font-family: Inter; }\n' + css, customFonts, assetFiles, previewDpi, timeoutMs, maxPages, allowMissingGlyphs, signal };
+  return { html, css, customFonts, assetFiles, previewDpi, timeoutMs, maxPages, allowMissingGlyphs, signal, isolation };
+}
+
+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 }));
+      }
+    }
+  });
 }
 
 async function renderPdf(options) {
@@ -85,6 +204,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 +236,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();
+  });
+});