satoru-render 1.0.11 → 1.0.13

package/dist/workers-parent.js

@@ -250,6 +250,14 @@ let LogLevel = /* @__PURE__ */ function(LogLevel) {
 }({});
 //#endregion
 //#region src/core.ts
+const DIAGNOSTIC_CODES = {
+	LIMIT_TIMEOUT: "LIMIT_TIMEOUT",
+	LIMIT_RESOURCE_SIZE: "LIMIT_RESOURCE_SIZE",
+	LIMIT_TOTAL_SIZE: "LIMIT_TOTAL_SIZE",
+	LIMIT_RESOURCE_COUNT: "LIMIT_RESOURCE_COUNT",
+	LIMIT_PROTOCOL_BLOCKED: "LIMIT_PROTOCOL_BLOCKED",
+	LIMIT_HOST_BLOCKED: "LIMIT_HOST_BLOCKED"
+};
 const emojiUrl = "https://cdn.jsdelivr.net/npm/@fontsource/noto-color-emoji/files/noto-color-emoji-emoji-400-normal.woff2";
 const DEFAULT_FONT_MAP = {
 	"sans-serif": "https://fonts.googleapis.com/css2?family=Noto+Sans+JP",
@@ -502,34 +510,29 @@ var SatoruBase = class {
 	}
 	async render(options) {
 		let { format = "svg", value, url, baseUrl } = options;
-		const profileEnabled = options.profile === true;
+		const profileEnabled = options.profile === true || options.diagnostics === true;
 		const profile = {};
 		const now = () => typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+		const startTime = now();
+		const limits = options.limits ?? {};
+		let totalResourceBytes = 0;
+		let resourceCount = 0;
 		const addProfile = (name, elapsed) => {
 			if (!profileEnabled) return;
 			profile[name] = (profile[name] ?? 0) + elapsed;
 		};
-		if (format === "pdf" && Array.isArray(value) && value.length > 1) {
-			const pagePdfs = [];
-			const SatoruClass = this.constructor;
-			for (const html of value) {
-				const pagePdf = await (await SatoruClass.create()).render({
-					...options,
-					value: html,
-					format: "pdf"
-				});
-				pagePdfs.push(pagePdf);
-			}
-			const mod = await this.getModule();
-			const instancePtr = mod.create_instance();
-			try {
-				const result = mod.merge_pdfs(instancePtr, pagePdfs);
-				if (!result) return new Uint8Array();
-				return new Uint8Array(result);
-			} finally {
-				mod.destroy_instance(instancePtr);
-			}
-		}
+		const diagnosticsReport = options.diagnostics ? {
+			version: 1,
+			format,
+			width: options.width,
+			height: options.height,
+			mediaType: options.mediaType ?? "screen",
+			timings: profile,
+			resources: [],
+			fonts: [],
+			warnings: [],
+			errors: []
+		} : null;
 		let mod = await this.getModule();
 		const { width, height = 0, fonts, images, css, logLevel, onLog } = options;
 		if (!options.userAgent) options.userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
@@ -547,6 +550,7 @@ var SatoruBase = class {
 		this.currentFontMap = options.fontMap ?? DEFAULT_FONT_MAP;
 		const instancePtr = mod.create_instance();
 		mod.set_font_map(instancePtr, this.currentFontMap);
+		mod.set_collect_profile_enabled(instancePtr, profileEnabled);
 		try {
 			const defaultResolver = (r) => this.resolveDefaultResource(r, baseUrl, options.userAgent);
 			const resolver = options.resolveResource ? async (r) => {
@@ -555,12 +559,120 @@ var SatoruBase = class {
 			const cachedResolver = async (r) => {
 				const cacheKey = `${r.type}:${r.url}:${r.characters ?? ""}`;
 				const cached = this.resourceCache.get(cacheKey);
+				let resourceDiag;
+				if (diagnosticsReport) {
+					resourceDiag = {
+						type: r.type,
+						url: r.url,
+						name: r.name,
+						status: "pending"
+					};
+					diagnosticsReport.resources.push(resourceDiag);
+				}
 				if (cached) {
 					addProfile("resourceCacheHitsCount", 1);
+					if (resourceDiag) {
+						resourceDiag.status = "loaded";
+						if (cached instanceof Uint8Array) resourceDiag.bytes = cached.byteLength;
+					}
 					return cached;
 				}
+				if (limits.maxResourceCount && resourceCount >= limits.maxResourceCount) {
+					const msg = `Maximum resource count (${limits.maxResourceCount}) exceeded`;
+					if (resourceDiag) {
+						resourceDiag.status = "skipped";
+						resourceDiag.reason = msg;
+						diagnosticsReport?.errors.push({
+							code: DIAGNOSTIC_CODES.LIMIT_RESOURCE_COUNT,
+							message: msg,
+							source: r.url
+						});
+					}
+					return null;
+				}
+				if (limits.allowedProtocols || limits.allowedHosts || limits.blockedHosts) try {
+					const urlObj = new URL(r.url);
+					if (limits.allowedProtocols && !limits.allowedProtocols.includes(urlObj.protocol)) {
+						const msg = `Protocol ${urlObj.protocol} is blocked`;
+						if (resourceDiag) {
+							resourceDiag.status = "skipped";
+							resourceDiag.reason = msg;
+							diagnosticsReport?.errors.push({
+								code: DIAGNOSTIC_CODES.LIMIT_PROTOCOL_BLOCKED,
+								message: msg,
+								source: r.url
+							});
+						}
+						return null;
+					}
+					if (limits.allowedHosts && !limits.allowedHosts.includes(urlObj.hostname)) {
+						const msg = `Host ${urlObj.hostname} is not in allowed list`;
+						if (resourceDiag) {
+							resourceDiag.status = "skipped";
+							resourceDiag.reason = msg;
+							diagnosticsReport?.errors.push({
+								code: DIAGNOSTIC_CODES.LIMIT_HOST_BLOCKED,
+								message: msg,
+								source: r.url
+							});
+						}
+						return null;
+					}
+					if (limits.blockedHosts && limits.blockedHosts.includes(urlObj.hostname)) {
+						const msg = `Host ${urlObj.hostname} is blocked`;
+						if (resourceDiag) {
+							resourceDiag.status = "skipped";
+							resourceDiag.reason = msg;
+							diagnosticsReport?.errors.push({
+								code: DIAGNOSTIC_CODES.LIMIT_HOST_BLOCKED,
+								message: msg,
+								source: r.url
+							});
+						}
+						return null;
+					}
+				} catch (e) {}
 				const resolveStart = now();
-				const result = await resolver(r);
+				let result = null;
+				try {
+					result = await resolver(r);
+					if (resourceDiag) {
+						resourceDiag.status = result ? "loaded" : "failed";
+						if (result) {
+							const bytes = result instanceof Uint8Array ? result.byteLength : result.buffer ? result.byteLength : "css" in result ? result.css.byteLength + result.fonts.reduce((acc, f) => acc + f.data.byteLength, 0) : 0;
+							resourceDiag.bytes = bytes;
+							if (limits.maxResourceBytes && bytes > limits.maxResourceBytes) {
+								const msg = `Resource size (${bytes} bytes) exceeds limit (${limits.maxResourceBytes})`;
+								resourceDiag.status = "skipped";
+								resourceDiag.reason = msg;
+								diagnosticsReport?.errors.push({
+									code: DIAGNOSTIC_CODES.LIMIT_RESOURCE_SIZE,
+									message: msg,
+									source: r.url
+								});
+								return null;
+							}
+							if (limits.maxTotalResourceBytes && totalResourceBytes + bytes > limits.maxTotalResourceBytes) {
+								const msg = `Total resource size exceeds limit (${limits.maxTotalResourceBytes})`;
+								resourceDiag.status = "skipped";
+								resourceDiag.reason = msg;
+								diagnosticsReport?.errors.push({
+									code: DIAGNOSTIC_CODES.LIMIT_TOTAL_SIZE,
+									message: msg,
+									source: r.url
+								});
+								return null;
+							}
+							totalResourceBytes += bytes;
+							resourceCount++;
+						}
+					}
+				} catch (e) {
+					if (resourceDiag) {
+						resourceDiag.status = "failed";
+						resourceDiag.reason = e.message || String(e);
+					}
+				}
 				addProfile("resolveResources", now() - resolveStart);
 				if (result) {
 					if (result instanceof Uint8Array) this.resourceCache.set(cacheKey, result);
@@ -590,14 +702,34 @@ var SatoruBase = class {
 			};
 			const inputHtmls = Array.isArray(value) ? value : [value];
 			const processedHtmls = [];
+			const utf8Decoder = new TextDecoder();
+			const utf8Encoder = new TextEncoder();
 			const resolvedResources = /* @__PURE__ */ new Set();
 			for (const rawHtml of inputHtmls) {
 				let processedHtml = rawHtml;
 				for (let i = 0; i < 10; i++) {
+					if (options.signal?.aborted) throw new Error("Render aborted");
+					if (typeof limits.timeoutMs !== "undefined" && now() - startTime >= limits.timeoutMs) {
+						const msg = `Render timed out after ${limits.timeoutMs}ms`;
+						diagnosticsReport?.errors.push({
+							code: DIAGNOSTIC_CODES.LIMIT_TIMEOUT,
+							message: msg
+						});
+						throw new Error(msg);
+					}
 					addProfile("collectResourcesCount", 1);
 					const collectStart = now();
 					mod.collect_resources(instancePtr, processedHtml, width, height, options.mediaType === "print" ? 1 : 0);
-					addProfile("collectResources", now() - collectStart);
+					const collectElapsed = now() - collectStart;
+					addProfile("collectResources", collectElapsed);
+					addProfile(`collectResourcesRound${i + 1}`, collectElapsed);
+					if (profileEnabled) try {
+						const collectProfile = JSON.parse(mod.get_collect_profile(instancePtr));
+						for (const [key, value] of Object.entries(collectProfile)) {
+							addProfile(key, value);
+							addProfile(`${key}Round${i + 1}`, value);
+						}
+					} catch {}
 					const pendingStart = now();
 					const binary = mod.get_pending_resources(instancePtr);
 					addProfile("getPendingResources", now() - pendingStart);
@@ -613,15 +745,15 @@ var SatoruBase = class {
 						const redraw_on_ready = view.getUint8(offset++) !== 0;
 						const urlLen = view.getUint32(offset, true);
 						offset += 4;
-						const url = new TextDecoder().decode(new Uint8Array(binary.buffer, binary.byteOffset + offset, urlLen));
+						const url = utf8Decoder.decode(new Uint8Array(binary.buffer, binary.byteOffset + offset, urlLen));
 						offset += urlLen;
 						const nameLen = view.getUint32(offset, true);
 						offset += 4;
-						const name = new TextDecoder().decode(new Uint8Array(binary.buffer, binary.byteOffset + offset, nameLen));
+						const name = utf8Decoder.decode(new Uint8Array(binary.buffer, binary.byteOffset + offset, nameLen));
 						offset += nameLen;
 						const charsLen = view.getUint32(offset, true);
 						offset += 4;
-						const characters = new TextDecoder().decode(new Uint8Array(binary.buffer, binary.byteOffset + offset, charsLen));
+						const characters = utf8Decoder.decode(new Uint8Array(binary.buffer, binary.byteOffset + offset, charsLen));
 						offset += charsLen;
 						let type = "font";
 						if (typeInt === 2) type = "image";
@@ -636,16 +768,31 @@ var SatoruBase = class {
 					}
 					const pending = resources.filter((r) => {
 						const key = `${r.type}:${r.url}:${r.characters ?? ""}`;
+						if (r.type === "font" && resolvedResources.has(`font:${r.url}:`)) return false;
 						return !resolvedResources.has(key);
 					});
+					addProfile("pendingResourcesCount", pending.length);
+					addProfile(`pendingResourcesRound${i + 1}Count`, pending.length);
+					for (const r of pending) if (r.type === "font") {
+						addProfile("pendingFontResourcesCount", 1);
+						addProfile(`pendingFontResourcesRound${i + 1}Count`, 1);
+					} else if (r.type === "css") {
+						addProfile("pendingCssResourcesCount", 1);
+						addProfile(`pendingCssResourcesRound${i + 1}Count`, 1);
+					} else if (r.type === "image") {
+						addProfile("pendingImageResourcesCount", 1);
+						addProfile(`pendingImageResourcesRound${i + 1}Count`, 1);
+					}
 					addProfile("parsePendingResources", now() - parseStart);
 					if (pending.length === 0) break;
+					addProfile("pendingResourceRoundsCount", 1);
 					const loadStart = now();
 					await Promise.all(pending.map(async (r) => {
 						try {
 							if (r.url.startsWith("data:")) return;
 							const key = `${r.type}:${r.url}:${r.characters ?? ""}`;
 							resolvedResources.add(key);
+							if (r.type === "font") resolvedResources.add(`font:${r.url}:`);
 							const data = await cachedResolver({ ...r });
 							if (!data) return;
 							if (typeof data === "object" && "css" in data && "fonts" in data) {
@@ -661,7 +808,7 @@ var SatoruBase = class {
 							if (data instanceof Uint8Array || ArrayBuffer.isView(data)) {
 								let finalUint8 = data instanceof Uint8Array ? data : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
 								if (r.type === "css") {
-									const cssText = new TextDecoder().decode(finalUint8);
+									const cssText = utf8Decoder.decode(finalUint8);
 									const isAbsolute = /^[a-z][a-z0-9+.-]*:/i.test(r.url) || r.url.startsWith("data:");
 									let cssBaseUrl = r.url;
 									if (!isAbsolute && baseUrl) try {
@@ -677,7 +824,7 @@ var SatoruBase = class {
 												return match;
 											}
 										});
-										finalUint8 = new TextEncoder().encode(rewrittenCss);
+										finalUint8 = utf8Encoder.encode(rewrittenCss);
 									}
 								}
 								await loadResourceData(r, finalUint8);
@@ -709,6 +856,15 @@ var SatoruBase = class {
 				pdf: 3
 			};
 			const renderStart = now();
+			if (options.signal?.aborted) throw new Error("Render aborted");
+			if (typeof limits.timeoutMs !== "undefined" && now() - startTime >= limits.timeoutMs) {
+				const msg = `Render timed out after ${limits.timeoutMs}ms`;
+				diagnosticsReport?.errors.push({
+					code: DIAGNOSTIC_CODES.LIMIT_TIMEOUT,
+					message: msg
+				});
+				throw new Error(msg);
+			}
 			const result = processedHtmls.length === 1 ? mod.render_from_state(instancePtr, width, height, formatMap[format] ?? 0, {
 				svgTextToPaths: options.textToPaths ?? true,
 				outputWidth: options.outputWidth ?? 0,
@@ -721,7 +877,19 @@ var SatoruBase = class {
 				fitPositionX: options.fitPosition?.x ?? .5,
 				fitPositionY: options.fitPosition?.y ?? .5,
 				backgroundColor: this.parseColor(options.backgroundColor),
-				mediaType: options.mediaType === "print" ? 1 : 0
+				mediaType: options.mediaType === "print" ? 1 : 0,
+				pdfTitle: options.pdfTitle ?? "",
+				pdfAuthor: options.pdfAuthor ?? "",
+				pdfSubject: options.pdfSubject ?? "",
+				pdfKeywords: options.pdfKeywords ?? "",
+				pdfCreator: options.pdfCreator ?? "",
+				pdfProducer: options.pdfProducer ?? "",
+				pdfMarginTop: options.pdfMargin?.top ?? 0,
+				pdfMarginRight: options.pdfMargin?.right ?? 0,
+				pdfMarginBottom: options.pdfMargin?.bottom ?? 0,
+				pdfMarginLeft: options.pdfMargin?.left ?? 0,
+				pdfHeader: options.pdfHeader ?? "",
+				pdfFooter: options.pdfFooter ?? ""
 			}) : mod.render(instancePtr, processedHtmls, width, height, formatMap[format] ?? 0, {
 				svgTextToPaths: options.textToPaths ?? true,
 				outputWidth: options.outputWidth ?? 0,
@@ -734,25 +902,55 @@ var SatoruBase = class {
 				fitPositionX: options.fitPosition?.x ?? .5,
 				fitPositionY: options.fitPosition?.y ?? .5,
 				backgroundColor: this.parseColor(options.backgroundColor),
-				mediaType: options.mediaType === "print" ? 1 : 0
+				mediaType: options.mediaType === "print" ? 1 : 0,
+				pdfTitle: options.pdfTitle ?? "",
+				pdfAuthor: options.pdfAuthor ?? "",
+				pdfSubject: options.pdfSubject ?? "",
+				pdfKeywords: options.pdfKeywords ?? "",
+				pdfCreator: options.pdfCreator ?? "",
+				pdfProducer: options.pdfProducer ?? "",
+				pdfMarginTop: options.pdfMargin?.top ?? 0,
+				pdfMarginRight: options.pdfMargin?.right ?? 0,
+				pdfMarginBottom: options.pdfMargin?.bottom ?? 0,
+				pdfMarginLeft: options.pdfMargin?.left ?? 0,
+				pdfHeader: options.pdfHeader ?? "",
+				pdfFooter: options.pdfFooter ?? ""
 			});
 			addProfile("wasmRender", now() - renderStart);
 			if (!result) {
 				options.onProfile?.(profile);
+				if (diagnosticsReport) {
+					try {
+						diagnosticsReport.fonts = JSON.parse(mod.get_font_diagnostics(instancePtr));
+					} catch {}
+					options.onDiagnostics?.(diagnosticsReport);
+				}
 				if (format === "svg") return "";
 				return new Uint8Array();
 			}
 			if (format === "svg") {
 				const decodeStart = now();
-				const svg = new TextDecoder().decode(result);
+				const svg = utf8Decoder.decode(result);
 				addProfile("decodeResult", now() - decodeStart);
 				options.onProfile?.(profile);
+				if (diagnosticsReport) {
+					try {
+						diagnosticsReport.fonts = JSON.parse(mod.get_font_diagnostics(instancePtr));
+					} catch {}
+					options.onDiagnostics?.(diagnosticsReport);
+				}
 				return svg;
 			}
 			const copyStart = now();
 			const bytes = new Uint8Array(result);
 			addProfile("copyResult", now() - copyStart);
 			options.onProfile?.(profile);
+			if (diagnosticsReport) {
+				try {
+					diagnosticsReport.fonts = JSON.parse(mod.get_font_diagnostics(instancePtr));
+				} catch {}
+				options.onDiagnostics?.(diagnosticsReport);
+			}
 			return bytes;
 		} finally {
 			mod.destroy_instance(instancePtr);
@@ -923,8 +1121,18 @@ var Satoru = class Satoru extends SatoruBase {
 *                      Defaults to the bundled workers.js in the same directory.
 * @param params.maxParallel Maximum number of parallel workers
 */
+/**
+* Create a Satoru worker proxy using worker-lib.
+* @param params Initialization parameters
+* @param params.worker Optional: Path to the worker file, a URL, or a factory function.
+*                      Defaults to the bundled workers.js in the same directory.
+* @param params.maxParallel Maximum number of parallel workers (default: 4)
+* @param params.timeoutMs Optional: Default timeout in milliseconds for each render job.
+*                         If a render job times out, the pool is reset to prevent hung workers.
+* @param params.onWorkerLog Optional: Global callback to intercept logs emitted by the worker threads.
+*/
 const createSatoruWorker = (params) => {
-	const { worker, maxParallel = 4 } = params ?? {};
+	const { worker, maxParallel = 4, timeoutMs, onWorkerLog } = params ?? {};
 	const factory = () => {
 		let w$1;
 		if (worker) w$1 = typeof worker === "function" ? worker() : worker;
@@ -936,14 +1144,85 @@ const createSatoruWorker = (params) => {
 		return w$1;
 	};
 	const workerInstance = createWorker(factory, maxParallel);
+	let totalPendingJobs = 0;
+	let completedJobs = 0;
+	let failedJobs = 0;
+	let totalJobTimeMs = 0;
+	/**
+	* Retrieve operational stats of the worker pool.
+	*/
+	const getStats = () => ({
+		workerCount: maxParallel,
+		activeJobs: Math.min(totalPendingJobs, maxParallel),
+		queuedJobs: Math.max(0, totalPendingJobs - maxParallel),
+		completedJobs,
+		failedJobs,
+		avgJobTimeMs: completedJobs > 0 ? totalJobTimeMs / completedJobs : 0
+	});
+	/**
+	* Reset the worker pool by terminating all running workers and recreating them.
+	* Useful to clear hung workers or reset statistics.
+	*/
+	const reset = () => {
+		workerInstance.setLimit(0);
+		workerInstance.setLimit(maxParallel);
+		totalPendingJobs = 0;
+		completedJobs = 0;
+		failedJobs = 0;
+		totalJobTimeMs = 0;
+	};
 	return new Proxy(workerInstance, { get(target, prop, receiver) {
+		if (prop === "getStats") return getStats;
+		if (prop === "reset") return reset;
 		if (prop === "render") return async (options) => {
-			return await target.execute("render", options);
+			totalPendingJobs++;
+			const startTime = Date.now();
+			const jobTimeoutMs = options.limits?.timeoutMs ?? timeoutMs;
+			const originalOnLog = options.onLog;
+			const mergedOnLog = (level, message) => {
+				if (originalOnLog) originalOnLog(level, message);
+				if (onWorkerLog) onWorkerLog(level, message);
+			};
+			const mergedOptions = {
+				...options,
+				onLog: mergedOnLog
+			};
+			let timeoutId;
+			let timeoutPromise;
+			if (jobTimeoutMs !== void 0 && jobTimeoutMs > 0) timeoutPromise = new Promise((_, reject) => {
+				timeoutId = setTimeout(() => {
+					reset();
+					reject(/* @__PURE__ */ new Error(`Render timed out after ${jobTimeoutMs}ms`));
+				}, jobTimeoutMs);
+			});
+			try {
+				const executePromise = target.execute("render", mergedOptions);
+				const result = await (timeoutPromise ? Promise.race([executePromise, timeoutPromise]) : executePromise);
+				completedJobs++;
+				totalJobTimeMs += Date.now() - startTime;
+				return result;
+			} catch (e) {
+				failedJobs++;
+				throw e;
+			} finally {
+				if (timeoutId) clearTimeout(timeoutId);
+				totalPendingJobs--;
+			}
 		};
 		if (prop in target) return Reflect.get(target, prop, receiver);
-		return (...args) => target.execute(prop, ...args);
+		return async (...args) => {
+			totalPendingJobs++;
+			try {
+				return await target.execute(prop, ...args);
+			} finally {
+				totalPendingJobs--;
+			}
+		};
 	} });
 };
-const { close, render, launchWorker, setLimit, waitAll, waitReady } = createSatoruWorker({ maxParallel: 1 });
+const defaultWorker = createSatoruWorker({ maxParallel: 1 });
+const { close, render, launchWorker, setLimit, waitAll, waitReady } = defaultWorker;
+const reset = () => defaultWorker.reset();
+const getStats = () => defaultWorker.getStats();
 //#endregion
-export { DEFAULT_FONT_MAP, LogLevel, Satoru, SatoruBase, close, createSatoruWorker, launchWorker, render, resolveGoogleFonts, setLimit, waitAll, waitReady };
+export { DEFAULT_FONT_MAP, DIAGNOSTIC_CODES, LogLevel, Satoru, SatoruBase, close, createSatoruWorker, getStats, launchWorker, render, reset, resolveGoogleFonts, setLimit, waitAll, waitReady };

package/dist/workers.d.ts

@@ -1,8 +1,9 @@
 export type { SatoruWorker } from "./child-workers.js";
-import { type RenderOptions } from "./index.js";
-export { type RenderOptions } from "./index.js";
+import { type RenderOptions, type WorkerPoolStats } from "./core.js";
+export { type RenderOptions } from "./core.js";
 export { Satoru } from "./index.js";
 export * from "./index.js";
+import { LogLevel } from "./log-level.js";
 export * from "./log-level.js";
 /**
  * Create a Satoru worker proxy using worker-lib.
@@ -11,9 +12,21 @@ export * from "./log-level.js";
  *                      Defaults to the bundled workers.js in the same directory.
  * @param params.maxParallel Maximum number of parallel workers
  */
+/**
+ * Create a Satoru worker proxy using worker-lib.
+ * @param params Initialization parameters
+ * @param params.worker Optional: Path to the worker file, a URL, or a factory function.
+ *                      Defaults to the bundled workers.js in the same directory.
+ * @param params.maxParallel Maximum number of parallel workers (default: 4)
+ * @param params.timeoutMs Optional: Default timeout in milliseconds for each render job.
+ *                         If a render job times out, the pool is reset to prevent hung workers.
+ * @param params.onWorkerLog Optional: Global callback to intercept logs emitted by the worker threads.
+ */
 export declare const createSatoruWorker: (params?: {
     worker?: string | URL | (() => Worker | string | URL);
     maxParallel?: number;
+    timeoutMs?: number;
+    onWorkerLog?: (level: LogLevel, message: string) => void;
 }) => Omit<{
     execute: <K extends "render">(name: K, ...value: Parameters<{
         render(options: RenderOptions): Promise<string | Uint8Array<ArrayBufferLike>>;
@@ -27,6 +40,28 @@ export declare const createSatoruWorker: (params?: {
     launchWorker: () => Promise<void[]>;
 }, "execute"> & {
     render(options: RenderOptions): Promise<string | Uint8Array<ArrayBufferLike>>;
+} & {
+    /**
+     * Retrieve operational stats of the worker pool.
+     */
+    getStats: () => WorkerPoolStats;
+    /**
+     * Reset the worker pool by terminating all running workers and recreating them.
+     */
+    reset: () => void;
+    /**
+     * Close and terminate all workers in the pool immediately.
+     */
+    close: () => void;
+    /**
+     * Wait for all running tasks in the pool to complete.
+     */
+    waitAll: () => Promise<void>;
+    /**
+     * Wait until there is an available worker slot in the pool.
+     */
+    waitReady: (retryTime?: number) => Promise<void>;
 };
-declare const close: () => void, render: (options: RenderOptions) => Promise<string | Uint8Array<ArrayBufferLike>>, launchWorker: () => Promise<void[]>, setLimit: (newLimit: number) => void, waitAll: () => Promise<void>, waitReady: (retryTime?: number) => Promise<void>;
-export { close, render, launchWorker, setLimit, waitAll, waitReady };
+export declare const close: (() => void) & (() => void), render: (options: RenderOptions) => Promise<string | Uint8Array<ArrayBufferLike>>, launchWorker: () => Promise<void[]>, setLimit: (newLimit: number) => void, waitAll: (() => Promise<void>) & (() => Promise<void>), waitReady: ((retryTime?: number) => Promise<void>) & ((retryTime?: number) => Promise<void>);
+export declare const reset: () => void;
+export declare const getStats: () => WorkerPoolStats;