fullbleed 0.1.5 → 0.3.0

package/README.md

@@ -1,14 +1,17 @@
-# Fullbleed for Node.js
+# Fullbleed for Node.js and browsers
 
-Generate PDFs from static HTML and CSS in Node.js. The package includes the
+Generate PDFs from static HTML and CSS in Node.js or a browser worker. 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.
 
+Import `fullbleed` for Node.js or `fullbleed/browser` for a web application.
+
 This is an optional integration around the published **Fullbleed 2.5.8** engine.
-The Node package has its own version, **0.1.5**. Normal text now selects a custom
-family's regular face even when its italic face is supplied first. Review saved
-PDF baselines when upgrading: affected documents can change appearance and line
-breaks. See the [font-family checks](https://github.com/fullbleed-engine/fullbleed-node/blob/main/docs/font-families.md) and
+The package has its own version, **0.3.0**, and adds a browser entry point for
+rendering in a Web Worker. The Node API still supports worker and process
+isolation. See the [browser guide](docs/browser.md),
+[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
@@ -19,10 +22,12 @@ 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.5`.
-Release verification compares the npm tarball with the checked
-[GitHub release](https://github.com/fullbleed-engine/fullbleed-node/releases/tag/v0.1.5).
-See the [installation verification records](https://github.com/fullbleed-engine/fullbleed-node/tree/main/verification).
+For a version-pinned installation, use `npm install --save-exact fullbleed@0.3.0`.
+Package archives and retained PDF/PNG evidence are attached to each
+[GitHub release](https://github.com/fullbleed-engine/fullbleed-node/releases).
+The [installation verification records](https://github.com/fullbleed-engine/fullbleed-node/tree/main/verification)
+retain published-package checks by version, including output hashes and failure
+recovery. Use the record for the version you are evaluating.
 
 Save this as `invoice.mjs` and run `node invoice.mjs`:
 
@@ -74,6 +79,32 @@ for the worker and bundled assets, and a standalone-server verification script.
 The route bounds rendering and returns private PDF attachments from fictional
 data; connect your own authenticated record lookup when adapting it.
 
+## Use it in a browser
+
+Copy the browser runtime into your application's static directory:
+
+```sh
+npx fullbleed-browser-assets public/fullbleed
+```
+
+Then use the separate browser entry from a page served over HTTPS or localhost:
+
+```javascript
+import { createRenderer } from 'fullbleed/browser';
+
+const renderer = createRenderer({ assetBaseUrl: '/fullbleed/' });
+const result = await renderer.renderPdf({
+  html: '<h1>Your document</h1>',
+  css: 'h1 { color: #175c52 }',
+  maxPages: 20,
+});
+const pdf = new Blob([result.pdf], { type: 'application/pdf' });
+```
+
+The result uses browser byte arrays. The worker loads the shipped engine/fonts
+from your site and renders locally, with cancellation, deadlines and structured
+errors. See the [browser API, download example and hosting requirements](docs/browser.md).
+
 ## Fonts and assets
 
 Supply file bytes explicitly. Additional fonts are registered alongside the
@@ -103,6 +134,9 @@ font-substitution or visual-validation report.
 
 ## API
 
+This section describes the Node entry. The browser entry returns browser byte
+arrays through a configured renderer; see its [API guide](docs/browser.md).
+
 `await renderPdf(options)` returns `{ pdf, previews, pages, missingGlyphs,
 engineVersion }`. PDF and PNG values are Node `Buffer` objects. Previews are
 generated from the finalized PDF and are empty when disabled.
@@ -121,6 +155,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
@@ -129,6 +164,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.
@@ -142,6 +184,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.
@@ -153,8 +196,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
@@ -183,6 +227,12 @@ npm run render:fonts
 npm run verify:fonts
 npm run render:families
 npm run verify:families
+npm run verify:browser:prepare
+python -m pip install -r tools/browser-requirements.txt
+python -m playwright install chrome firefox webkit
+python tools/check-browser.py --browser chrome --label local
+python tools/check-browser.py --browser firefox --label local
+python tools/check-browser.py --browser webkit --label local
 ```
 
 The build records engine metadata, licenses, and artifact hashes in `dist/`.
@@ -191,6 +241,8 @@ fonts, and image assets; compares native and WebAssembly PDF/PNG bytes; checks
 error recovery; and installs the packed tarball into a separate directory with
 spaces in its path. CI exercises Node 22, 24, and 26 on Windows, Linux, and macOS.
 Retained release evidence describes the verified fixtures and scope.
+Browser CI uses the same packed artifact in Chrome, Firefox and Playwright WebKit,
+including actual downloads, finalized previews, asset failures and recovery.
 The font check reads PDFs from the isolated tarball installation, checks the
 embedded TrueType programs against their source fonts, and compares two
 independent text readers. CI also compares text and native/PDFium pixels with
@@ -199,7 +251,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/browser/asset-manifest.json

@@ -0,0 +1,67 @@
+{
+  "schema": "fullbleed.browser-assets.v1",
+  "packageVersion": "0.3.0",
+  "engineVersion": "2.5.8",
+  "files": {
+    "client.js": {
+      "source": "dist/browser/client.js",
+      "bytes": 12042,
+      "sha256": "9de6e9b58387b419bd9469d9ac462907cd1f17c787dc89c86ee5e2c96309c0bf"
+    },
+    "worker.js": {
+      "source": "dist/browser/worker.js",
+      "bytes": 52108,
+      "sha256": "732050b295547a95b2eef88926c64f442fe3cb399282bcfc3f7feb08393b35e5"
+    },
+    "engine.wasm": {
+      "source": "dist/engine.wasm",
+      "bytes": 5069661,
+      "sha256": "e95cc9132029b9c42ad684d898063b4efc043fa0b7b9fe2e7867f3eb3a17ef58"
+    },
+    "THIRD_PARTY_NOTICES.txt": {
+      "source": "dist/THIRD_PARTY_NOTICES.txt",
+      "bytes": 57660,
+      "sha256": "5475f50666d3af5df89048cc1ddc98d153cd813019afbc213be20e4f3838911f"
+    },
+    "LICENSE.txt": {
+      "source": "LICENSE",
+      "bytes": 1079,
+      "sha256": "36a2115938f6e68cf0d87eccff7a6a3e57c17017e909cbd640d51aff1fa0c5a9"
+    },
+    "fonts/BebasNeue-OFL.txt": {
+      "source": "assets/fonts/BebasNeue-OFL.txt",
+      "bytes": 4337,
+      "sha256": "72082f6cb4d04be2ecf7cc7d9e1e7d73787f0af8a5a278a47cade70c16b78341"
+    },
+    "fonts/BebasNeue-Regular.ttf": {
+      "source": "assets/fonts/BebasNeue-Regular.ttf",
+      "bytes": 61400,
+      "sha256": "08e4623805102d819f58601e46e345648846075e363b2ceb23313c2d1c83ec73"
+    },
+    "fonts/DMSerifDisplay-Italic.ttf": {
+      "source": "assets/fonts/DMSerifDisplay-Italic.ttf",
+      "bytes": 71208,
+      "sha256": "df74c0ac387baeaeb0fe4f2324e1668e6a3ed8c09cd9796fe162c71753e19e45"
+    },
+    "fonts/DMSerifDisplay-OFL.txt": {
+      "source": "assets/fonts/DMSerifDisplay-OFL.txt",
+      "bytes": 4512,
+      "sha256": "aa49c876a28d8c0b0a3027d6c25b9c607eee8c0fb96165011d42a6ace1408fe1"
+    },
+    "fonts/DMSerifDisplay-Regular.ttf": {
+      "source": "assets/fonts/DMSerifDisplay-Regular.ttf",
+      "bytes": 76580,
+      "sha256": "8cc3643535edf039aa5d95440a8542735e9197e4f4b8d9303e980fefbf5ab616"
+    },
+    "fonts/Inter-OFL.txt": {
+      "source": "assets/fonts/Inter-OFL.txt",
+      "bytes": 4377,
+      "sha256": "5b9321a4298cfeb6b34354164a1c3afc3db114569984c502b9b35d988fd58c57"
+    },
+    "fonts/Inter-Variable.ttf": {
+      "source": "assets/fonts/Inter-Variable.ttf",
+      "bytes": 876576,
+      "sha256": "29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031"
+    }
+  }
+}

package/dist/browser/client.js

@@ -0,0 +1,225 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __commonJS = (cb, mod) => function __require() {
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// <define:__FULLBLEED_FONT_NAMES__>
+var init_define_FULLBLEED_FONT_NAMES = __esm({
+  "<define:__FULLBLEED_FONT_NAMES__>"() {
+  }
+});
+
+// <define:__FULLBLEED_RUNTIME_FILES__>
+var init_define_FULLBLEED_RUNTIME_FILES = __esm({
+  "<define:__FULLBLEED_RUNTIME_FILES__>"() {
+  }
+});
+
+// src/render-input.cjs
+var require_render_input = __commonJS({
+  "src/render-input.cjs"(exports, module) {
+    "use strict";
+    init_define_FULLBLEED_FONT_NAMES();
+    init_define_FULLBLEED_RUNTIME_FILES();
+    var FullbleedError2 = class extends Error {
+      constructor(code, message, options) {
+        super(message, options);
+        this.name = "FullbleedError";
+        this.code = code;
+      }
+    };
+    var invalid2 = (message) => {
+      throw new FullbleedError2("INVALID_INPUT", message);
+    };
+    var sourceLimit = 4e6;
+    var assetLimit = 64 * 1024 * 1024;
+    function normalize(options, { browser = false } = {}) {
+      if (!options || typeof options !== "object" || Array.isArray(options)) invalid2("Pass an options object with an html string.");
+      const supported = /* @__PURE__ */ new Set(["html", "css", "fonts", "assets", "previewDpi", "timeoutMs", "maxPages", "allowMissingGlyphs", "signal"]);
+      if (!browser) supported.add("isolation");
+      for (const key of Object.keys(options)) if (!supported.has(key)) invalid2(`Unknown option: ${key}`);
+      const { html, css = "", fonts = [], assets = {}, previewDpi = 0, timeoutMs = 3e4, maxPages = 1e3, allowMissingGlyphs = false, signal, isolation = "worker" } = options;
+      if (typeof html !== "string" || !html.trim()) invalid2("html must be a nonempty string.");
+      if (typeof css !== "string") invalid2("css must be a string.");
+      if (new TextEncoder().encode(html).byteLength + new TextEncoder().encode(css).byteLength > sourceLimit) invalid2("HTML and CSS together must not exceed 4,000,000 UTF-8 bytes.");
+      if (!Number.isInteger(previewDpi) || previewDpi !== 0 && (previewDpi < 36 || previewDpi > 300)) invalid2("previewDpi must be 0 (disabled) or an integer from 36 to 300.");
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) invalid2("timeoutMs must be a positive integer no greater than 2147483647.");
+      if (!Number.isSafeInteger(maxPages) || maxPages < 1) invalid2("maxPages must be a positive integer.");
+      if (typeof allowMissingGlyphs !== "boolean") invalid2("allowMissingGlyphs must be a boolean.");
+      if (signal !== void 0 && !(signal instanceof AbortSignal)) invalid2("signal must be an AbortSignal.");
+      if (isolation !== "worker" && isolation !== "process") invalid2("isolation must be worker or process.");
+      if (!Array.isArray(fonts)) invalid2("fonts must be an array of font byte arrays.");
+      if (!assets || typeof assets !== "object" || Array.isArray(assets)) invalid2("assets must map relative names to byte arrays.");
+      let assetBytes = 0;
+      function bytes(value, label) {
+        if (!(value instanceof Uint8Array) || !value.byteLength) invalid2(`${label} must be a nonempty Uint8Array or Buffer.`);
+        assetBytes += value.byteLength;
+        if (assetBytes > assetLimit) invalid2("Custom fonts and assets together must not exceed 64 MiB.");
+        return Uint8Array.from(value);
+      }
+      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 === "..")) invalid2(`Invalid asset path: ${name}`);
+        for (let i = 1; i < segments.length; i++) if (fileNames.has(segments.slice(0, i).join("/"))) invalid2(`Asset is both a file and a directory: ${name}`);
+        return { name: "assets/" + name, data: bytes(assets[name], `assets[${name}]`) };
+      });
+      return { html, css, customFonts, assetFiles, previewDpi, timeoutMs, maxPages, allowMissingGlyphs, signal, isolation };
+    }
+    module.exports = { FullbleedError: FullbleedError2, normalize };
+  }
+});
+
+// src/browser.js
+init_define_FULLBLEED_FONT_NAMES();
+init_define_FULLBLEED_RUNTIME_FILES();
+var import_render_input = __toESM(require_render_input(), 1);
+var version = "0.3.0";
+var engineVersion = "2.5.8";
+var FullbleedError = import_render_input.default.FullbleedError;
+var invalid = (message) => {
+  throw new FullbleedError("INVALID_INPUT", message);
+};
+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(options2) {
+    const start = Date.now();
+    const job = import_render_input.default.normalize(options2, { 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);
+        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 });
+}
+export {
+  FullbleedError,
+  createRenderer,
+  engineVersion,
+  version
+};