fullbleed 0.3.2 → 0.4.0

package/README.md

@@ -15,9 +15,9 @@ Using Vue? The [Vue and TypeScript starter](examples/vue) includes editable
 templates, automatic previews, downloads, and a reusable `usePdfPreview` composable.
 
 This is an optional integration around the published **Fullbleed 2.5.11** engine.
-The package has its own version, **0.3.2**. This patch fixes blank previews of
-unembedded Standard 14 fonts, including Helvetica, Times, and Courier. Preview
-pixels change for those fonts; review saved preview baselines when upgrading.
+The package has its own version, **0.4.0**. Node applications can use a shared
+render queue to bound active renders and waiting requests, include queue time in
+deadlines, cancel waiting jobs, and stop rendering cleanly during shutdown.
 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),
@@ -33,7 +33,7 @@ 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.3.2`.
+For a version-pinned installation, use `npm install --save-exact fullbleed@0.4.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)
@@ -157,6 +157,36 @@ cover the twelve Latin faces, an embedded-font control, and the blank-preview
 failure in public 0.3.1. Font provenance and complete license notices ship with
 both the npm package and copied browser runtime.
 
+## Limit concurrent renders
+
+Create one queue per application process and reuse it across requests:
+
+```javascript
+import { createRenderQueue } from 'fullbleed';
+
+const documents = createRenderQueue({ concurrency: 2, maxQueue: 4 });
+const result = await documents.renderPdf({
+  html: '<h1>Queued invoice</h1>',
+  isolation: 'process',
+  timeoutMs: 30_000,
+});
+// Return result.pdf from your request handler.
+// At application shutdown, cancel outstanding work and await cleanup:
+await documents.close();
+```
+
+This queue admits two active renders and four waiting requests. Further requests
+reject with `QUEUE_FULL`, so a server can return a busy response. Waiting jobs
+can be aborted and their deadlines include the wait. Slots stay occupied until
+their worker or child process has exited. `close()` rejects new work, cancels
+accepted jobs with `QUEUE_CLOSED`, and waits for cleanup.
+
+Choose limits for your host and document sizes. The queue bounds job counts, not
+total memory, and each application process has its own queue. It is an in-memory
+admission control; use your application's durable job system for persistence and
+delivery. See the [queue guide and retained checks](docs/render-queue.md) and the
+[six-invoice batch example](examples/render-queue.mjs).
+
 ## API
 
 This section describes the Node entry. The browser entry returns browser byte
@@ -225,6 +255,14 @@ Error codes include `INVALID_INPUT`, `MISSING_GLYPHS`, `PAGE_LIMIT`, `TIMEOUT`,
 include `exitCode` and `signal`. Failed or cancelled calls do not return a partial
 PDF. Caller-owned asset buffers are copied when a call starts.
 
+`createRenderQueue({ concurrency?, maxQueue? })` exposes `renderPdf()` with the
+same options and result. Defaults are one active render and sixteen waiting
+jobs. `maxQueue: 0` rejects buffering. Accepted calls snapshot their strings and
+asset/font bytes immediately. The queue adds `QUEUE_FULL` and `QUEUE_CLOSED`,
+read-only `activeCount`, `pendingCount`, and `closed` properties, and an
+idempotent asynchronous `close()` method. It does not reuse workers or change
+the standalone `renderPdf()` concurrency behavior.
+
 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
 [Python or Rust APIs](https://docs.fullbleed.dev/) for those workflows and their

package/dist/browser/asset-manifest.json

@@ -1,22 +1,22 @@
 {
   "schema": "fullbleed.browser-assets.v1",
-  "packageVersion": "0.3.2",
+  "packageVersion": "0.4.0",
   "engineVersion": "2.5.11",
   "files": {
     "client.js": {
       "source": "dist/browser/client.js",
       "bytes": 12043,
-      "sha256": "35639759feb84bd52c8cc3f8e077387b59815f319f2d3dff66c354ca88175ff3"
+      "sha256": "bf508fad7b4a3e2c542a54c088dce513f7b3356a8dd5e4be31cd3f6c73b63682"
     },
     "worker.js": {
       "source": "dist/browser/worker.js",
       "bytes": 52109,
-      "sha256": "b58e511fedc84369196e7f90a35cdc0338ca375de0c888b39dbdb7d4f9fbef39"
+      "sha256": "0fadb05bcb74518a119f78353072633791c2ce9a4e2bbd189e5b6d6e78de6353"
     },
     "engine.wasm": {
       "source": "dist/engine.wasm",
       "bytes": 5585689,
-      "sha256": "90caf8a1fe493a32cdc0d3d2e55db7986c9c4b4994d6d080c0cdd3aec1727bbd"
+      "sha256": "cf8b2ad0493ee32a86871341805c1a5284ad6d2c14bb395593efa4a7c2db2cec"
     },
     "THIRD_PARTY_NOTICES.txt": {
       "source": "dist/THIRD_PARTY_NOTICES.txt",

package/dist/browser/client.js

@@ -109,7 +109,7 @@ var require_render_input = __commonJS({
 init_define_FULLBLEED_FONT_NAMES();
 init_define_FULLBLEED_RUNTIME_FILES();
 var import_render_input = __toESM(require_render_input(), 1);
-var version = "0.3.2";
+var version = "0.4.0";
 var engineVersion = "2.5.11";
 var FullbleedError = import_render_input.default.FullbleedError;
 var invalid = (message) => {

package/dist/browser/worker.js

@@ -2,7 +2,7 @@
 var define_FULLBLEED_FONT_NAMES_default = ["Inter-Variable.ttf", "DMSerifDisplay-Regular.ttf", "DMSerifDisplay-Italic.ttf", "BebasNeue-Regular.ttf"];
 
 // <define:__FULLBLEED_RUNTIME_FILES__>
-var define_FULLBLEED_RUNTIME_FILES_default = { "engine.wasm": { bytes: 5585689, sha256: "90caf8a1fe493a32cdc0d3d2e55db7986c9c4b4994d6d080c0cdd3aec1727bbd" }, "fonts/Inter-Variable.ttf": { bytes: 876576, sha256: "29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031" }, "fonts/DMSerifDisplay-Regular.ttf": { bytes: 76580, sha256: "8cc3643535edf039aa5d95440a8542735e9197e4f4b8d9303e980fefbf5ab616" }, "fonts/DMSerifDisplay-Italic.ttf": { bytes: 71208, sha256: "df74c0ac387baeaeb0fe4f2324e1668e6a3ed8c09cd9796fe162c71753e19e45" }, "fonts/BebasNeue-Regular.ttf": { bytes: 61400, sha256: "08e4623805102d819f58601e46e345648846075e363b2ceb23313c2d1c83ec73" } };
+var define_FULLBLEED_RUNTIME_FILES_default = { "engine.wasm": { bytes: 5585689, sha256: "cf8b2ad0493ee32a86871341805c1a5284ad6d2c14bb395593efa4a7c2db2cec" }, "fonts/Inter-Variable.ttf": { bytes: 876576, sha256: "29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031" }, "fonts/DMSerifDisplay-Regular.ttf": { bytes: 76580, sha256: "8cc3643535edf039aa5d95440a8542735e9197e4f4b8d9303e980fefbf5ab616" }, "fonts/DMSerifDisplay-Italic.ttf": { bytes: 71208, sha256: "df74c0ac387baeaeb0fe4f2324e1668e6a3ed8c09cd9796fe162c71753e19e45" }, "fonts/BebasNeue-Regular.ttf": { bytes: 61400, sha256: "08e4623805102d819f58601e46e345648846075e363b2ceb23313c2d1c83ec73" } };
 
 // node_modules/@bjorn3/browser_wasi_shim/dist/wasi_defs.js
 var CLOCKID_REALTIME = 0;
@@ -1438,7 +1438,7 @@ async function runEngine(job) {
 }
 
 // src/browser-worker.js
-var version = "0.3.2";
+var version = "0.4.0";
 var engineVersion = "2.5.11";
 var files = define_FULLBLEED_RUNTIME_FILES_default;
 var fontNames = define_FULLBLEED_FONT_NAMES_default;

package/dist/build.json

@@ -1,5 +1,5 @@
 {
-  "packageVersion": "0.3.2",
+  "packageVersion": "0.4.0",
   "engineVersion": "2.5.11",
   "engineSource": "https://crates.io/crates/fullbleed/2.5.11",
   "target": "wasm32-wasip1",
@@ -45,7 +45,7 @@
   "files": {
     "dist/engine.wasm": {
       "bytes": 5585689,
-      "sha256": "90caf8a1fe493a32cdc0d3d2e55db7986c9c4b4994d6d080c0cdd3aec1727bbd"
+      "sha256": "cf8b2ad0493ee32a86871341805c1a5284ad6d2c14bb395593efa4a7c2db2cec"
     },
     "dist/THIRD_PARTY_NOTICES.txt": {
       "bytes": 81572,
@@ -101,15 +101,15 @@
     },
     "dist/browser/client.js": {
       "bytes": 12043,
-      "sha256": "35639759feb84bd52c8cc3f8e077387b59815f319f2d3dff66c354ca88175ff3"
+      "sha256": "bf508fad7b4a3e2c542a54c088dce513f7b3356a8dd5e4be31cd3f6c73b63682"
     },
     "dist/browser/worker.js": {
       "bytes": 52109,
-      "sha256": "b58e511fedc84369196e7f90a35cdc0338ca375de0c888b39dbdb7d4f9fbef39"
+      "sha256": "0fadb05bcb74518a119f78353072633791c2ce9a4e2bbd189e5b6d6e78de6353"
     },
     "dist/browser/asset-manifest.json": {
       "bytes": 2399,
-      "sha256": "48d17f6481ff27e82e6cd2c93626e9ccd5cd7cc563fc577b62b9bae22de5b906"
+      "sha256": "febca55c5dc4212ec745090dd55b89abffab753df6159e0699ce3e85c2b41a4e"
     }
   }
 }

package/dist/index.d.cts

@@ -10,7 +10,7 @@ export interface RenderOptions {
   assets?: Readonly<Record<string, Uint8Array>>;
   /** 0 disables previews (default); otherwise 36–300 DPI. */
   previewDpi?: number;
-  /** Includes initial engine loading. Default: 30000 ms. */
+  /** Includes queue wait and initial engine loading. Default: 30000 ms. */
   timeoutMs?: number;
   /** Reject documents larger than this. Default: 1000. */
   maxPages?: number;
@@ -37,5 +37,23 @@ export class FullbleedError extends Error {
   constructor(code: string, message: string, options?: ErrorOptions);
 }
 export function renderPdf(options: RenderOptions): Promise<RenderResult>;
+export interface RenderQueueOptions {
+  /** Maximum simultaneous renders in this queue. Default: 1. */
+  concurrency?: number;
+  /** Maximum waiting requests, excluding active renders. Default: 16; 0 rejects instead of waiting. */
+  maxQueue?: number;
+}
+export interface RenderQueue {
+  /** Render in FIFO start order, or reject with QUEUE_FULL/QUEUE_CLOSED. Inputs are copied at admission. */
+  renderPdf(options: RenderOptions): Promise<RenderResult>;
+  /** Stop admission, cancel accepted jobs and await worker/process cleanup. Idempotent. */
+  close(): Promise<void>;
+  readonly concurrency: number;
+  readonly maxQueue: number;
+  readonly activeCount: number;
+  readonly pendingCount: number;
+  readonly closed: boolean;
+}
+export function createRenderQueue(options?: RenderQueueOptions): RenderQueue;
 export const engineVersion: string;
 export const version: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullbleed",
-  "version": "0.3.2",
+  "version": "0.4.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",

package/src/index.cjs

@@ -9,6 +9,7 @@ const { pathToFileURL } = require('node:url');
 const pkg = require('../package.json');
 
 const { FullbleedError, normalize } = require('./render-input.cjs');
+const { createQueue } = require('./render-queue.cjs');
 const hash = bytes => createHash('sha256').update(bytes).digest('hex');
 const root = join(__dirname, '..');
 let runtimePromise;
@@ -156,6 +157,11 @@ async function renderPdf(options) {
   if (Number(process.versions.node.split('.')[0]) < 22) throw new FullbleedError('UNSUPPORTED_NODE', 'Fullbleed requires Node.js 22 or newer.');
   const start = Date.now();
   const job = normalize(options);
+  return renderJob(job, start);
+}
+
+async function renderJob(job, start) {
+  if (Number(process.versions.node.split('.')[0]) < 22) throw new FullbleedError('UNSUPPORTED_NODE', 'Fullbleed requires Node.js 22 or newer.');
   const aborted = () => new FullbleedError('ABORTED', 'PDF rendering was aborted.');
   if (job.signal?.aborted) throw aborted();
   const remaining = job.timeoutMs - (Date.now() - start);
@@ -211,6 +217,7 @@ async function renderPdf(options) {
 }
 
 exports.renderPdf = renderPdf;
+exports.createRenderQueue = options => createQueue(renderJob, options);
 exports.FullbleedError = FullbleedError;
 exports.engineVersion = pkg.fullbleed.engineVersion;
 exports.version = pkg.version;

package/src/index.d.ts

@@ -10,7 +10,7 @@ export interface RenderOptions {
   assets?: Readonly<Record<string, Uint8Array>>;
   /** 0 disables previews (default); otherwise 36–300 DPI. */
   previewDpi?: number;
-  /** Includes initial engine loading. Default: 30000 ms. */
+  /** Includes queue wait and initial engine loading. Default: 30000 ms. */
   timeoutMs?: number;
   /** Reject documents larger than this. Default: 1000. */
   maxPages?: number;
@@ -37,5 +37,23 @@ export class FullbleedError extends Error {
   constructor(code: string, message: string, options?: ErrorOptions);
 }
 export function renderPdf(options: RenderOptions): Promise<RenderResult>;
+export interface RenderQueueOptions {
+  /** Maximum simultaneous renders in this queue. Default: 1. */
+  concurrency?: number;
+  /** Maximum waiting requests, excluding active renders. Default: 16; 0 rejects instead of waiting. */
+  maxQueue?: number;
+}
+export interface RenderQueue {
+  /** Render in FIFO start order, or reject with QUEUE_FULL/QUEUE_CLOSED. Inputs are copied at admission. */
+  renderPdf(options: RenderOptions): Promise<RenderResult>;
+  /** Stop admission, cancel accepted jobs and await worker/process cleanup. Idempotent. */
+  close(): Promise<void>;
+  readonly concurrency: number;
+  readonly maxQueue: number;
+  readonly activeCount: number;
+  readonly pendingCount: number;
+  readonly closed: boolean;
+}
+export function createRenderQueue(options?: RenderQueueOptions): RenderQueue;
 export const engineVersion: string;
 export const version: string;

package/src/index.js

@@ -1,3 +1,3 @@
 // SPDX-License-Identifier: MIT
 import api from './index.cjs';
-export const { renderPdf, FullbleedError, engineVersion, version } = api;
+export const { renderPdf, createRenderQueue, FullbleedError, engineVersion, version } = api;

package/src/render-queue.cjs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MIT
+'use strict';
+const { FullbleedError, normalize } = require('./render-input.cjs');
+
+const failure = (code, message) => new FullbleedError(code, message);
+const closedError = () => failure('QUEUE_CLOSED', 'The rendering queue is closed.');
+const abortedError = () => failure('ABORTED', 'PDF rendering was aborted.');
+
+function createQueue(run, options = {}) {
+  const invalid = message => { throw failure('INVALID_INPUT', message); };
+  if (!options || typeof options !== 'object' || Array.isArray(options)) invalid('Pass queue options as an object.');
+  for (const key of Object.keys(options)) {
+    if (key !== 'concurrency' && key !== 'maxQueue') invalid(`Unknown queue option: ${key}`);
+  }
+  const { concurrency = 1, maxQueue = 16 } = options;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) invalid('concurrency must be a positive safe integer.');
+  if (!Number.isSafeInteger(maxQueue) || maxQueue < 0) invalid('maxQueue must be a nonnegative safe integer.');
+  const pending = [];
+  const active = new Set();
+  let closed = false, closePromise, resolveClose;
+
+  function finishClose() {
+    if (closed && active.size === 0 && pending.length === 0) resolveClose();
+  }
+
+  function cleanup(entry) {
+    clearTimeout(entry.timer);
+    entry.sourceSignal?.removeEventListener('abort', entry.onAbort);
+  }
+
+  function cancel(entry, error) {
+    if (entry.state === 'settled') return;
+    if (entry.state === 'active') {
+      entry.stopError ??= error;
+      entry.controller.abort();
+      return;
+    }
+    pending.splice(pending.indexOf(entry), 1);
+    entry.state = 'settled';
+    cleanup(entry);
+    entry.reject(error);
+    pump();
+    finishClose();
+  }
+
+  function complete(entry, error, result) {
+    // run() settles only after its worker or process exits. Keep the slot
+    // occupied through that cleanup, including failure and cancellation.
+    active.delete(entry);
+    entry.state = 'settled';
+    cleanup(entry);
+    error = entry.stopError ?? error;
+    if (error) entry.reject(error); else entry.resolve(result);
+    pump();
+    finishClose();
+  }
+
+  function pump() {
+    if (closed) return;
+    while (active.size < concurrency && pending.length) {
+      const entry = pending.shift();
+      entry.state = 'active';
+      clearTimeout(entry.timer);
+      active.add(entry);
+      Promise.resolve().then(() => run(entry.job, entry.start)).then(
+        result => complete(entry, null, result),
+        error => complete(entry, error),
+      );
+    }
+  }
+
+  function admissionError() {
+    if (closed) return closedError();
+    if (active.size >= concurrency && pending.length >= maxQueue) {
+      return failure('QUEUE_FULL', 'The rendering queue has no available slot.');
+    }
+  }
+
+  function renderPdf(options) {
+    let error = admissionError();
+    if (error) return Promise.reject(error);
+    const start = Date.now();
+    let job;
+    try { job = normalize(options); } catch (error) { return Promise.reject(error); }
+    // Getters on the input can invoke application code during normalization.
+    // Recheck admission before retaining the copied document buffers.
+    error = admissionError();
+    if (error) return Promise.reject(error);
+    if (job.signal?.aborted) return Promise.reject(abortedError());
+    const remaining = job.timeoutMs - (Date.now() - start);
+    if (remaining <= 0) return Promise.reject(failure('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`));
+    const sourceSignal = job.signal;
+    const controller = new AbortController();
+    job.signal = controller.signal;
+    return new Promise((resolve, reject) => {
+      const entry = { job, start, sourceSignal, controller, resolve, reject, state: 'pending' };
+      entry.onAbort = () => cancel(entry, abortedError());
+      pending.push(entry);
+      entry.timer = setTimeout(() => cancel(entry,
+        failure('TIMEOUT', `PDF rendering exceeded ${job.timeoutMs} ms.`)), remaining);
+      sourceSignal?.addEventListener('abort', entry.onAbort, { once: true });
+      if (sourceSignal?.aborted) entry.onAbort();
+      else pump();
+    });
+  }
+
+  function close() {
+    if (closed) return closePromise;
+    closed = true;
+    closePromise = new Promise(resolve => { resolveClose = resolve; });
+    for (const entry of [...pending, ...active]) cancel(entry, closedError());
+    finishClose();
+    return closePromise;
+  }
+
+  return Object.freeze({
+    renderPdf, close, concurrency, maxQueue,
+    get activeCount() { return active.size; },
+    get pendingCount() { return pending.length; },
+    get closed() { return closed; },
+  });
+}
+
+module.exports = { createQueue };