fullbleed 0.2.0 → 0.3.1

package/README.md

@@ -1,13 +1,20 @@
-# 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.
 
-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),
+Import `fullbleed` for Node.js or `fullbleed/browser` for a web application.
+
+This is an optional integration around the published **Fullbleed 2.5.10** engine.
+The package has its own version, **0.3.1**. This patch fixes inline text overlap
+and spacing in wrapped paragraphs, and keeps tracked labels at their intended
+width. Affected PDFs can change line breaks,
+pagination, and hashes; review saved baselines when upgrading.
+The browser entry renders in a Web Worker, and the Node API supports worker and
+process isolation. See the [browser guide](docs/browser.md),
+[inline wrapping checks](docs/inline-wrapping.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.
 
@@ -19,10 +26,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.2.0`.
+For a version-pinned installation, use `npm install --save-exact fullbleed@0.3.1`.
 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).
+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 +83,39 @@ 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
+
+For React, use the [React and TypeScript starter](examples/react) with automatic
+previews, editable templates, cancellation, and a reusable component-lifecycle hook.
+
+Start with the [complete browser application](examples/browser): editable HTML/CSS,
+invoice and report designs, previews, cancellation, and PDF downloads.
+
+
+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
@@ -101,8 +143,15 @@ Use registered font families in CSS. The engine can substitute an unavailable
 family. Its missing-glyph report checks resolved fonts and is not an exhaustive
 font-substitution or visual-validation report.
 
+Use bundled or explicitly registered fonts for PNG previews. PDFs using the
+unembedded built-in Helvetica or Times faces rely on PDF-reader fonts; the
+Fullbleed preview can omit their text. See the [retained inline checks](docs/inline-wrapping.md).
+
 ## 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.
@@ -193,6 +242,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/`.
@@ -201,6 +256,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

package/dist/THIRD_PARTY_NOTICES.txt

@@ -1,4 +1,4 @@
-fullbleed 2.5.8 / LICENSE
+fullbleed 2.5.10 / 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.8 / THIRD_PARTY_LICENSES.md
+fullbleed 2.5.10 / THIRD_PARTY_LICENSES.md
 
 <!-- SPDX-License-Identifier: MIT -->
 # Third-Party Licenses

package/dist/browser/asset-manifest.json

@@ -0,0 +1,67 @@
+{
+  "schema": "fullbleed.browser-assets.v1",
+  "packageVersion": "0.3.1",
+  "engineVersion": "2.5.10",
+  "files": {
+    "client.js": {
+      "source": "dist/browser/client.js",
+      "bytes": 12043,
+      "sha256": "60ea647aa3818c61a313f6a3c8ab8f269667fddc6ab85465d30c61408da0b765"
+    },
+    "worker.js": {
+      "source": "dist/browser/worker.js",
+      "bytes": 52109,
+      "sha256": "32734ecd472fe4c329869ccf58078e8dbb0269621f5b37b8a72116daace65a99"
+    },
+    "engine.wasm": {
+      "source": "dist/engine.wasm",
+      "bytes": 5075752,
+      "sha256": "4fcbecb954f6a5a64ea840795e74d719cc045d5ba35d5ffa730fcb46b3ce8b3c"
+    },
+    "THIRD_PARTY_NOTICES.txt": {
+      "source": "dist/THIRD_PARTY_NOTICES.txt",
+      "bytes": 57662,
+      "sha256": "d41ecdf3735cc3eb030949311ba830a503f339ddb0108fb0b2e452186bab354f"
+    },
+    "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.1";
+var engineVersion = "2.5.10";
+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
+};