blitz-pdf 0.1.6 → 0.1.8

package/licenses/Unifont-OFL.txt

@@ -0,0 +1,90 @@
+The SIL Open Font License version 1.1 is copied below, and is also
+available with a FAQ at http://scripts.sil.org/OFL.
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/licenses/font-sources.json

@@ -0,0 +1,106 @@
+[
+  {
+    "family": "Noto Sans Tamil",
+    "source": "https://raw.githubusercontent.com/notofonts/notofonts.github.io/93fac8abebe6c7fed0c5b7d2456d8fa484fa146c/fonts/NotoSansTamil/full/ttf/NotoSansTamil-Regular.ttf",
+    "sourceSha256": "0afbc221964b6048c6d771c525be474d21b288a621dce0fafedd695cc5c98e4e",
+    "sha256": "e967d7cc71373113bc7330cca8bbceee43d75499c9cfe2c77d0a163cc5c9c56c",
+    "license": "licenses/Noto-OFL.txt",
+    "copyright": "Copyright 2022 The Noto Project Authors (https://github.com/notofonts/tamil)",
+    "path": "tests/fixtures/fonts/NotoSansTamil-Regular.woff2"
+  },
+  {
+    "family": "Noto Emoji",
+    "source": "https://raw.githubusercontent.com/google/fonts/8b0a1d0f5983c89bc2b93f1b5fb55f9e252744b5/ofl/notoemoji/NotoEmoji%5Bwght%5D.ttf",
+    "sourceSha256": "de6c18832938afc99caf132b39d6a30a19bac7f2e812e28db2535b4608d27551",
+    "sha256": "12f3b7927fe6381c6fd45bf0bd635e6858348171a129145ef40dc4774790f8b5",
+    "license": "licenses/NotoEmoji-OFL.txt",
+    "copyright": "Copyright 2013 Google LLC",
+    "instance": {
+      "wght": 400
+    },
+    "path": "assets/fonts/NotoEmoji-Regular.woff2"
+  },
+  {
+    "family": "Unifont",
+    "source": "https://unifoundry.com/pub/unifont/unifont-18.0.01/font-builds/unifont-18.0.01.otf",
+    "sourceSha256": "88d0a14d4aa9a96419720b39ba5da921a59560d76d4ec7d523acc06ed85cd3c2",
+    "sha256": "b3afcc1a7d3088985b29709c9f63bb76f730dd17c506e6974cb31f8568048dc4",
+    "license": "licenses/Unifont-OFL.txt",
+    "copyright": "Copyright © 1998-2026 Roman Czyborra, Paul Hardy, Qianqian Fang, Andrew Miller, Johnnie Weaver, David Corbett, Ælla Chiana Moskopp, Rebecca Bettencourt, Ho-Seok Ee, et al.",
+    "path": "assets/fonts/unifont-18.0.01.woff2",
+    "conversion": "CFF straight-line contours converted losslessly to TrueType outlines, with reversed contour winding; WOFF2 compressed without subsetting. See scripts/build-unicode-fallbacks.py."
+  },
+  {
+    "family": "Unifont Upper",
+    "source": "https://unifoundry.com/pub/unifont/unifont-18.0.01/font-builds/unifont_upper-18.0.01.otf",
+    "sourceSha256": "472201e45a050bff4c7658208b8c73e34ebce3764b287a5a46c7774038ef9391",
+    "sha256": "6b1456aedb95104af8b384783b31c060c91d5b772e0859b057e5592913977343",
+    "license": "licenses/Unifont-OFL.txt",
+    "copyright": "Copyright © 1998-2026 Roman Czyborra, Paul Hardy, Qianqian Fang, Andrew Miller, Johnnie Weaver, David Corbett, Ælla Chiana Moskopp, Rebecca Bettencourt, Ho-Seok Ee, et al.",
+    "path": "assets/fonts/unifont_upper-18.0.01.woff2",
+    "conversion": "CFF straight-line contours converted losslessly to TrueType outlines, with reversed contour winding; WOFF2 compressed without subsetting. See scripts/build-unicode-fallbacks.py."
+  },
+  {
+    "family": "Noto Sans",
+    "source": "https://raw.githubusercontent.com/notofonts/notofonts.github.io/93fac8abebe6c7fed0c5b7d2456d8fa484fa146c/fonts/NotoSans/full/ttf/NotoSans-Regular.ttf",
+    "sourceSha256": "f5f552c8c5edb61fe6efb824baf4d4de47b1a8689ab4925ff43f7bd6a4ebece5",
+    "sha256": "5e69b5d9791d13fcf54b306bd7db7210691981363e8366844b61d08bf53b35fc",
+    "copyright": "Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)",
+    "license": "licenses/Noto-OFL.txt",
+    "path": "assets/fonts/NotoSans-Regular.woff2"
+  },
+  {
+    "family": "Noto Sans",
+    "source": "https://raw.githubusercontent.com/notofonts/notofonts.github.io/93fac8abebe6c7fed0c5b7d2456d8fa484fa146c/fonts/NotoSans/full/ttf/NotoSans-Bold.ttf",
+    "sourceSha256": "3a08a47daa00cade516425c15c57615aef2fd418ec9811a7b9f465088f92cc05",
+    "sha256": "682022f287c5e97ab0fcf000b4dcefe468287cf0e474faafdf6b521dca549ecf",
+    "copyright": "Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)",
+    "license": "licenses/Noto-OFL.txt",
+    "path": "assets/fonts/NotoSans-Bold.woff2"
+  },
+  {
+    "family": "Noto Sans",
+    "source": "https://raw.githubusercontent.com/notofonts/notofonts.github.io/93fac8abebe6c7fed0c5b7d2456d8fa484fa146c/fonts/NotoSans/full/ttf/NotoSans-Italic.ttf",
+    "sourceSha256": "126522ae1bb9cd92120287fc47dfc74ef981e73931d93e52c565fb7e09b2d74a",
+    "sha256": "d4650f9a6687babedc858c2bab9b66f3af0482edf913773ec467d1c2e9c0180c",
+    "copyright": "Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)",
+    "license": "licenses/Noto-OFL.txt",
+    "path": "assets/fonts/NotoSans-Italic.woff2"
+  },
+  {
+    "family": "Noto Sans",
+    "source": "https://raw.githubusercontent.com/notofonts/notofonts.github.io/93fac8abebe6c7fed0c5b7d2456d8fa484fa146c/fonts/NotoSans/full/ttf/NotoSans-BoldItalic.ttf",
+    "sourceSha256": "2e34b41a4b9c234b1be7dff6d06cba18811ecb694b41350873edf0ec16a0f0fa",
+    "sha256": "2b74d12f0c0ab38db4149e3fedb039eba6e72cce7ec094ab904fbb7a99d48bfb",
+    "copyright": "Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)",
+    "license": "licenses/Noto-OFL.txt",
+    "path": "assets/fonts/NotoSans-BoldItalic.woff2"
+  },
+  {
+    "family": "Noto Sans Mono",
+    "source": "https://raw.githubusercontent.com/notofonts/notofonts.github.io/93fac8abebe6c7fed0c5b7d2456d8fa484fa146c/fonts/NotoSansMono/unhinted/ttf/NotoSansMono-Regular.ttf",
+    "sourceSha256": "87f8ce0522a6c99b743ee5fc75b4073cfdd575639119672828b7b9944b65b4f4",
+    "sha256": "b97922da952ad3f7ee7280c83d9929456bed8d4fd832dddef01e595422508891",
+    "copyright": "Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)",
+    "license": "licenses/Noto-OFL.txt",
+    "path": "assets/fonts/NotoSansMono-Regular.woff2"
+  },
+  {
+    "family": "Noto Sans CJK JP",
+    "source": "https://raw.githubusercontent.com/notofonts/noto-cjk/Sans2.004/Sans/OTF/Japanese/NotoSansCJKjp-Regular.otf",
+    "sourceSha256": "68a3fc98800b2a27b371f2fb79991daf3633bd89309d4ffaa6946fd587f375b5",
+    "sha256": "e24935ccb42dde87a7fc8f10929fc9c214fb6daa90637eb6c65db81eb3daea43",
+    "copyright": "© 2014-2021 Adobe (http://www.adobe.com/).",
+    "license": "licenses/NotoCJK-OFL.txt",
+    "path": "assets/fonts/NotoSansCJKjp-Regular.woff2"
+  },
+  {
+    "family": "Noto Sans CJK JP",
+    "source": "https://raw.githubusercontent.com/notofonts/noto-cjk/Sans2.004/Sans/OTF/Japanese/NotoSansCJKjp-Bold.otf",
+    "sourceSha256": "e53dcb0dcb2922e45d01aae1ebd2f382bb81d4229b18b6b883bd170678af1f76",
+    "sha256": "39b13feaef2327a3fce9b12f4c67bc5c069b0a97e8e11e03b062260f6c2cdbbf",
+    "copyright": "© 2014-2021 Adobe (http://www.adobe.com/).",
+    "license": "licenses/NotoCJK-OFL.txt",
+    "path": "assets/fonts/NotoSansCJKjp-Bold.woff2"
+  }
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blitz-pdf",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Render HTML and CSS to PDF with Blitz and WebAssembly in Node.js, Bun, and browsers.",
   "type": "module",
   "license": "MIT",

package/src/api.ts

@@ -3,8 +3,8 @@ import { createAssetLoader } from "./assets.js";
 import { normalizeOptions } from "./options.js";
 import { render, validateHtml } from "./render.js";
 import { compileWasm } from "./wasm.js";
-import { renderInWorker, type SpawnWorker } from "./worker-host.js";
-import type { InitOptions, PdfOptions, WasmSource } from "./types.js";
+import { createWorkerPool, type SpawnWorker } from "./worker-host.js";
+import type { InitOptions, PdfOptions, PdfWorkerPool, PdfWorkerPoolOptions, WasmSource } from "./types.js";
 
 export interface ApiConfig {
   defaultSource: () => Promise<WasmSource> | WasmSource;
@@ -15,6 +15,7 @@ export interface ApiConfig {
 export function createApi({ defaultSource, prepare = async source => source, spawnWorker }: ApiConfig) {
   let compiled: Promise<WebAssembly.Module> | undefined;
   let ready: Promise<void> | undefined;
+  let defaultPool: PdfWorkerPool | undefined;
 
   function compile(source?: WasmSource): Promise<WebAssembly.Module> {
     if (compiled) return compiled;
@@ -43,13 +44,37 @@ export function createApi({ defaultSource, prepare = async source => source, spa
     return render(html, normalized, assetResolver && createAssetLoader(assetResolver));
   }
 
-  /** Like `renderPdf`, but layout and serialization run in a new worker. An `assets` function still runs on the calling thread. */
+  /** Create an owned pool, with independent concurrency and shutdown. No workers start until needed. */
+  function createPdfWorkerPool(options: PdfWorkerPoolOptions = {}): PdfWorkerPool {
+    const pool = createWorkerPool(spawnWorker, options);
+    // Include compilation in accepted work so close also drains renders waiting for WASM.
+    const pending = new Set<Promise<Uint8Array>>();
+    let closing: Promise<void> | undefined;
+    return {
+      renderPdf(html: string, options: PdfOptions = {}): Promise<Uint8Array> {
+        if (closing) return Promise.reject(new Error("PDF worker pool is closed"));
+        const work = (async () => {
+          validateHtml(html);
+          const { assetResolver, ...normalized } = normalizeOptions(options);
+          return pool.render(await compile(), html, normalized, assetResolver);
+        })();
+        pending.add(work);
+        void work.then(() => pending.delete(work), () => pending.delete(work));
+        return work;
+      },
+      close(): Promise<void> {
+        closing ??= Promise.allSettled([...pending]).then(() => pool.close());
+        return closing;
+      },
+    };
+  }
+
+  /** Render in the shared bounded pool. An assets function still runs on the calling thread. */
   async function renderPdfInWorker(html: string, options: PdfOptions = {}): Promise<Uint8Array> {
-    validateHtml(html);
-    const { assetResolver, ...normalized } = normalizeOptions(options);
-    return renderInWorker(spawnWorker, await compile(), html, normalized, assetResolver);
+    defaultPool ??= createPdfWorkerPool();
+    return defaultPool.renderPdf(html, options);
   }
 
   async function getEngineVersion(): Promise<string> { await init(); return engine_version(); }
-  return { init, renderPdf, renderPdfInWorker, getWasmModule, getEngineVersion };
+  return { init, renderPdf, renderPdfInWorker, createPdfWorkerPool, getWasmModule, getEngineVersion };
 }

package/src/browser.ts

@@ -1,7 +1,8 @@
 import { createApi } from "./api.js";
 
 export type { AssetData, AssetMap, AssetResolver, AttachmentRelationship, BinaryData, InitOptions, Length, PageFormat, PageNumberOptions, PdfAttachment, PdfDate, PdfMetadata, PdfOptions, PdfXmpProperty, PdfXmpSchema, WasmSource } from "./types.js";
-export const { init, renderPdf, renderPdfInWorker, getWasmModule, getEngineVersion } = createApi({
+export type { PdfWorkerPool, PdfWorkerPoolOptions } from "./types.js";
+export const { init, renderPdf, renderPdfInWorker, createPdfWorkerPool, getWasmModule, getEngineVersion } = createApi({
   defaultSource: () => new URL("../wasm/blitz_pdf_bg.wasm", import.meta.url),
   spawnWorker: events => {
     const worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });

package/src/node.ts

@@ -3,7 +3,8 @@ import { Worker } from "node:worker_threads";
 import { createApi } from "./api.js";
 
 export type { AssetData, AssetMap, AssetResolver, AttachmentRelationship, BinaryData, InitOptions, Length, PageFormat, PageNumberOptions, PdfAttachment, PdfDate, PdfMetadata, PdfOptions, PdfXmpProperty, PdfXmpSchema, WasmSource } from "./types.js";
-export const { init, renderPdf, renderPdfInWorker, getWasmModule, getEngineVersion } = createApi({
+export type { PdfWorkerPool, PdfWorkerPoolOptions } from "./types.js";
+export const { init, renderPdf, renderPdfInWorker, createPdfWorkerPool, getWasmModule, getEngineVersion } = createApi({
   defaultSource: () => readFile(new URL("../wasm/blitz_pdf_bg.wasm", import.meta.url)),
   prepare: async source => {
     if (source instanceof URL && source.protocol === "file:") return readFile(source);
@@ -16,6 +17,10 @@ export const { init, renderPdf, renderPdfInWorker, getWasmModule, getEngineVersi
     worker.on("error", events.error);
     worker.on("messageerror", events.error);
     worker.on("exit", code => events.error(new Error(`Render worker exited with code ${code}`)));
-    return { post: (message, transfer) => worker.postMessage(message, transfer), terminate: () => void worker.terminate() };
+    return {
+      post: (message, transfer) => worker.postMessage(message, transfer),
+      terminate: async () => { await worker.terminate(); },
+      ref: () => { worker.ref(); }, unref: () => { worker.unref(); },
+    };
   },
 });

package/src/types.ts

@@ -105,7 +105,8 @@ export interface PdfOptions {
   baseUrl?: string;
   /** Resource map or async loader, called once per absolute URL per render. Data URLs are handled internally. */
   assets?: AssetMap | AssetResolver;
-  /** Additional static TTF, OTF, WOFF, or WOFF2 fonts, using their internal family names. */
+  /** Additional static TTF, OTF, WOFF, or WOFF2 fonts, using their internal family names.
+   * Automatically used as fallbacks when the requested font lacks a glyph. */
   fonts?: readonly BinaryData[];
   /** PDF document title. */
   title?: string;
@@ -122,3 +123,18 @@ export interface PdfOptions {
   /** Reject larger documents. Default: 100; maximum: 1000. */
   maxPages?: number;
 }
+/** Limits for a pool of reusable, independent PDF engines. */
+export interface PdfWorkerPoolOptions {
+  /** Maximum simultaneous renders. Default: 4. */
+  maxWorkers?: number;
+  /** Release an unused worker after this many milliseconds. Default: 30000; 0 disables reuse. */
+  idleTimeoutMs?: number;
+  /** Recreate a worker after this many documents to bound retained engine memory. Default: 100. */
+  maxJobsPerWorker?: number;
+}
+
+export interface PdfWorkerPool {
+  renderPdf(html: string, options?: PdfOptions): Promise<Uint8Array>;
+  /** Stop accepting work, finish accepted renders, and release every worker. Idempotent. */
+  close(): Promise<void>;
+}

package/src/worker-host.ts

@@ -1,45 +1,164 @@
 import { createAssetLoader } from "./assets.js";
 import type { RenderOptions } from "./render.js";
-import type { AssetResolver } from "./types.js";
+import type { AssetResolver, PdfWorkerPoolOptions } from "./types.js";
 import type { HostMessage, WorkerMessage } from "./worker-protocol.js";
 
 export interface WorkerEvents {
   message(message: WorkerMessage): void;
-  /** Crashes, unreadable messages, or an exit before the render settled. */
+  /** Crashes, unreadable messages, or an unexpected exit, including while idle. */
   error(error: unknown): void;
 }
 
 export interface WorkerHandle {
   post(message: HostMessage, transfer: ArrayBuffer[]): void;
-  terminate(): void;
+  terminate(): void | Promise<void>;
+  ref?(): void;
+  unref?(): void;
 }
 
 export type SpawnWorker = (events: WorkerEvents) => WorkerHandle;
 
-/** Renders in a fresh worker that instantiates the precompiled module, then terminates it. */
-export function renderInWorker(spawn: SpawnWorker, module: WebAssembly.Module, html: string,
-  options: RenderOptions, resolver: AssetResolver | undefined): Promise<Uint8Array> {
-  return new Promise<Uint8Array>((resolve, reject) => {
-    const load = resolver && createAssetLoader(resolver);
-    let settled = false;
-    const settle = (callback: () => void) => {
-      if (settled) return;
-      settled = true;
-      worker.terminate();
-      callback();
-    };
-    const worker: WorkerHandle = spawn({
-      message(message) {
-        if (message.type === "done") settle(() => resolve(message.pdf));
-        else if (message.type === "error") settle(() => reject(message.error));
-        else if (!load) settle(() => reject(new Error("Render worker requested assets without a resolver")));
-        else load(message.urls).then(
-          data => { if (!settled) worker.post({ type: "assets", data }, data.map(bytes => bytes.buffer as ArrayBuffer)); },
-          (error: unknown) => settle(() => reject(error)),
-        );
-      },
-      error(error) { settle(() => reject(error)); },
-    });
-    worker.post({ type: "render", module, html, options, external: load !== undefined }, []);
-  });
+interface Job {
+  id: number;
+  message: Extract<HostMessage, { type: "render" }>;
+  load: ReturnType<typeof createAssetLoader> | undefined;
+  resolve(pdf: Uint8Array): void;
+  reject(error: unknown): void;
+}
+
+interface Slot {
+  worker?: WorkerHandle;
+  job?: Job;
+  timer?: ReturnType<typeof setTimeout>;
+  completed: number;
+  retired: boolean;
+}
+
+function integer(value: number, min: number, max: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be an integer from ${min} to ${max}`);
+  }
+  return value;
+}
+
+/** Jobs have their own resolver and document; only the initialized engine survives. */
+export function createWorkerPool(spawn: SpawnWorker, options: PdfWorkerPoolOptions = {}) {
+  const maxWorkers = integer(options.maxWorkers ?? 4, 1, Number.MAX_SAFE_INTEGER, "maxWorkers");
+  const idleTimeoutMs = integer(options.idleTimeoutMs ?? 30_000, 0, 2_147_483_647, "idleTimeoutMs");
+  const maxJobs = integer(options.maxJobsPerWorker ?? 100, 1, Number.MAX_SAFE_INTEGER, "maxJobsPerWorker");
+  const slots = new Set<Slot>();
+  const queue: Job[] = [];
+  const terminating = new Set<Promise<void>>();
+  let nextId = 0;
+  let closing: Promise<void> | undefined;
+  let resolveClosed: (() => void) | undefined;
+  let pumping = false;
+
+  function checkClosed() {
+    if (closing && queue.length === 0 && slots.size === 0 && terminating.size === 0) resolveClosed?.();
+  }
+
+  function retire(slot: Slot) {
+    if (slot.retired) return;
+    slot.retired = true;
+    clearTimeout(slot.timer);
+    slots.delete(slot);
+    // Observe asynchronous termination before close resolves; late exit events are ignored.
+    const done = Promise.resolve().then(() => slot.worker?.terminate()).then(() => {}, () => {});
+    terminating.add(done);
+    void done.then(() => { terminating.delete(done); checkClosed(); });
+  }
+
+  function fail(slot: Slot, error: unknown) {
+    if (slot.retired) return;
+    const job = slot.job;
+    delete slot.job;
+    retire(slot);
+    job?.reject(error);
+    pump();
+  }
+
+  function release(slot: Slot) {
+    slot.completed++;
+    if (slot.completed >= maxJobs || idleTimeoutMs === 0 || (closing && queue.length === 0)) {
+      retire(slot);
+    } else if (queue.length === 0) {
+      slot.worker?.unref?.();
+      slot.timer = setTimeout(() => { retire(slot); checkClosed(); }, idleTimeoutMs);
+      // A warm worker and its eviction timer must not keep a CLI alive.
+      slot.timer.unref?.();
+    }
+    pump();
+  }
+
+  function message(slot: Slot, value: WorkerMessage) {
+    const job = slot.job;
+    if (slot.retired || !job || value.id !== job.id) return;
+    if (value.type === "done") {
+      delete slot.job;
+      release(slot);
+      job.resolve(value.pdf);
+    } else if (value.type === "error") {
+      fail(slot, value.error);
+    } else if (!job.load) {
+      fail(slot, new Error("Render worker requested assets without a resolver"));
+    } else {
+      void job.load(value.urls).then(data => {
+        // Resolver promises can finish after a crash or retirement. Never send them to another job.
+        if (slot.retired || slot.job !== job) return;
+        try {
+          slot.worker!.post({ type: "assets", id: job.id, data }, data.map(bytes => bytes.buffer as ArrayBuffer));
+        } catch (error) { fail(slot, error); }
+      }, error => { if (!slot.retired && slot.job === job) fail(slot, error); });
+    }
+  }
+
+  function pump() {
+    if (pumping) return;
+    pumping = true;
+    try {
+      while (queue.length > 0) {
+        let slot = [...slots].find(candidate => !candidate.job);
+        if (!slot && slots.size >= maxWorkers) break;
+        const job = queue.shift()!;
+        if (!slot) {
+          slot = { completed: 0, retired: false, job };
+          slots.add(slot);
+          const created = slot;
+          try {
+            created.worker = spawn({ message: value => message(created, value), error: error => fail(created, error) });
+          } catch (error) { fail(created, error); continue; }
+        } else {
+          clearTimeout(slot.timer);
+          delete slot.timer;
+          slot.job = job;
+        }
+        try {
+          slot.worker!.ref?.();
+          slot.worker!.post(job.message, []);
+        } catch (error) { fail(slot, error); }
+      }
+      if (closing && queue.length === 0) for (const slot of slots) if (!slot.job) retire(slot);
+    } finally { pumping = false; }
+    checkClosed();
+  }
+
+  return {
+    render(module: WebAssembly.Module, html: string, options: RenderOptions, resolver?: AssetResolver): Promise<Uint8Array> {
+      if (closing) return Promise.reject(new Error("PDF worker pool is closed"));
+      return new Promise((resolve, reject) => {
+        const id = ++nextId;
+        queue.push({ id, message: { type: "render", id, module, html, options, external: resolver !== undefined },
+          load: resolver ? createAssetLoader(resolver) : undefined, resolve, reject });
+        pump();
+      });
+    },
+    close(): Promise<void> {
+      if (!closing) {
+        closing = new Promise(resolve => { resolveClosed = resolve; });
+        pump();
+      }
+      return closing;
+    },
+  };
 }

package/src/worker-protocol.ts

@@ -1,10 +1,10 @@
 import type { RenderOptions } from "./render.js";
 
 export type HostMessage =
-  | { type: "render"; module: WebAssembly.Module; html: string; options: RenderOptions; external: boolean }
-  | { type: "assets"; data: Uint8Array[] };
+  | { type: "render"; id: number; module: WebAssembly.Module; html: string; options: RenderOptions; external: boolean }
+  | { type: "assets"; id: number; data: Uint8Array[] };
 
 export type WorkerMessage =
-  | { type: "assets"; urls: string[] }
-  | { type: "done"; pdf: Uint8Array }
-  | { type: "error"; error: unknown };
+  | { type: "assets"; id: number; urls: string[] }
+  | { type: "done"; id: number; pdf: Uint8Array }
+  | { type: "error"; id: number; error: unknown };

package/src/worker-runtime.ts

@@ -7,29 +7,43 @@ export interface WorkerEndpoint {
   onMessage(handler: (message: HostMessage) => void): void;
 }
 
-/** Worker side of `renderPdfInWorker`: one render per worker; asset bytes come from the host. */
+/** One document at a time; retain the initialized engine and its bundled-font cache. */
 export function serve(endpoint: WorkerEndpoint): void {
+  let initialized = false;
+  let activeId: number | undefined;
   let receiveAssets: ((data: Uint8Array[]) => void) | undefined;
   endpoint.onMessage(async message => {
     if (message.type === "assets") {
+      if (message.id !== activeId) return;
       const receive = receiveAssets;
       receiveAssets = undefined;
       receive?.(message.data);
       return;
     }
+    if (activeId !== undefined) {
+      endpoint.post({ type: "error", id: message.id, error: new Error("Worker already has an active document") }, []);
+      return;
+    }
+    activeId = message.id;
     try {
-      initSync({ module: message.module });
+      if (!initialized) {
+        initSync({ module: message.module });
+        initialized = true;
+      }
       const load = message.external
         ? (urls: string[]) => new Promise<Uint8Array[]>(resolve => {
           receiveAssets = resolve;
-          endpoint.post({ type: "assets", urls }, []);
+          endpoint.post({ type: "assets", id: message.id, urls }, []);
         })
         : undefined;
       const pdf = await render(message.html, message.options, load);
-      endpoint.post({ type: "done", pdf }, [pdf.buffer as ArrayBuffer]);
+      endpoint.post({ type: "done", id: message.id, pdf }, [pdf.buffer as ArrayBuffer]);
     } catch (error) {
-      try { endpoint.post({ type: "error", error }, []); }
-      catch { endpoint.post({ type: "error", error: new Error(String(error)) }, []); }
+      try { endpoint.post({ type: "error", id: message.id, error }, []); }
+      catch { endpoint.post({ type: "error", id: message.id, error: new Error(String(error)) }, []); }
+    } finally {
+      activeId = undefined;
+      receiveAssets = undefined;
     }
   });
 }