@nitpicker/core 0.6.4 → 0.7.0

package/README.md

@@ -4,10 +4,48 @@
 
 ## 概要
 
-`.nitpicker` アーカイブ内の各ページに対して、analyze プラグインを並列実行するためのエンジンです。プラグインの検出・読み込み・Worker スレッドでの実行を担当します。
+`.nitpicker` アーカイブ内の各ページに対して、analyze プラグインを並列実行するためのエンジンです。プラグインの検出・読み込み・Worker スレッドプールでの実行を担当します。
 
 このパッケージは [Nitpicker](../../README.md) モノレポの内部パッケージです。単体での利用は想定していません。
 
+## プラグイン作者向け
+
+analyze プラグインは `definePlugin()` で定義します。
+
+```ts
+import { definePlugin } from '@nitpicker/core';
+
+type Options = {
+	keywords: string[];
+};
+
+export default definePlugin((options: Options) => {
+	return {
+		label: 'キーワード検索',
+		// 並列度を宣言できる。省略時は os.cpus().length
+		// 重いプラグイン（Chrome 起動など）は小さく設定する
+		concurrency: 4,
+		headers: {
+			found: 'Keywords Found',
+		},
+		async eachPage({ window }) {
+			const text = window.document.body.textContent ?? '';
+			const count = options.keywords.filter((k) => text.includes(k)).length;
+			return {
+				page: { found: { value: count } },
+			};
+		},
+	};
+});
+```
+
+### `concurrency` の指針
+
+- **省略**: `os.cpus().length`（CPU コア数）が使われる。軽量な DOM 解析のみのプラグインはこのままで良い
+- **小さく設定すべきケース**: Chrome や Puppeteer などの重いプロセスを起動するプラグインは 2〜4 程度に絞る。例えば `@nitpicker/analyze-lighthouse` は Chrome 1 プロセス ≒ 300〜500MB を消費するため `concurrency: 2`
+
+詳細は [CONTRIBUTING.md](../../../CONTRIBUTING.md) と [ARCHITECTURE.md](../../../ARCHITECTURE.md) を参照。
+
 ## ライセンス
 
 Apache-2.0

package/lib/core.d.ts

@@ -1,5 +1,4 @@
 export { Nitpicker } from './nitpicker.js';
 export { definePlugin } from './hooks/define-plugin.js';
 export { readPluginLabels } from './read-plugin-labels.js';
-export { runInWorker } from './worker/run-in-worker.js';
 export * from './types.js';

package/lib/core.js

@@ -1,5 +1,4 @@
 export { Nitpicker } from './nitpicker.js';
 export { definePlugin } from './hooks/define-plugin.js';
 export { readPluginLabels } from './read-plugin-labels.js';
-export { runInWorker } from './worker/run-in-worker.js';
 export * from './types.js';

package/lib/nitpicker.d.ts

@@ -12,15 +12,17 @@ export { definePlugin } from './hooks/define-plugin.js';
  *
  * ## Architecture decisions
  *
- * - **Worker threads for `eachPage`**: DOM-heavy analysis (JSDOM + axe-core,
- *   markuplint, etc.) runs in isolated Worker threads so that a crashing plugin
- *   cannot take down the main process and memory from JSDOM windows is reclaimed
- *   when the Worker exits. See {@link ./worker/run-in-worker.ts!runInWorker}.
+ * - **Worker pool per plugin**: Each plugin gets its own long-lived
+ *   {@link ./worker/worker-pool.ts!WorkerPool}, sized by either the plugin's
+ *   declared `concurrency` or {@link DEFAULT_CONCURRENCY} (CPU core count).
+ *   Workers are spawned once and reused across every page, so the V8 isolate
+ *   / JSDOM module / plugin module boot cost is paid only `concurrency`
+ *   times per plugin instead of once per page.
  *
- * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially,
- *   and for each plugin, pages are processed in parallel (limit: 50) using
- *   a bounded Promise pool. This enables per-plugin progress tracking via
- *   {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}.
+ * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially.
+ *   For each plugin, pages are submitted to that plugin's pool, which queues
+ *   them and dispatches to idle workers. This enables per-plugin progress
+ *   tracking via {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}.
  *
  * - **Cache layer**: Results are cached per `pluginName:url` using
  *   `@d-zero/shared/cache` so that re-running analysis after a partial failure
@@ -57,16 +59,17 @@ export declare class Nitpicker extends EventEmitter<NitpickerEvent> {
      * Runs all configured analyze plugins (or a filtered subset) against
      * every page in the archive.
      *
-     * Plugins are processed **sequentially** (one at a time), while pages
-     * within each plugin are processed in **parallel** (bounded to
-     * {@link CONCURRENCY_LIMIT}). This architecture enables per-plugin
-     * progress tracking via Lanes.
+     * Plugins are processed **sequentially** (one at a time). For each plugin,
+     * pages are processed in **parallel** through a dedicated long-lived
+     * {@link ./worker/worker-pool.ts!WorkerPool} sized either by the plugin's
+     * declared concurrency or by {@link DEFAULT_CONCURRENCY}. This architecture
+     * enables per-plugin progress tracking via Lanes.
      *
      * The analysis proceeds in two phases:
      *
-     * 1. **`eachPage` phase** - For each plugin with `eachPage`, spawns
-     *    Worker threads via a bounded Promise pool to analyze all pages.
-     *    Progress is displayed via Lanes if provided in options.
+     * 1. **`eachPage` phase** - For each plugin with `eachPage`, dispatches
+     *    page analysis tasks to the plugin's worker pool. Progress is
+     *    displayed via Lanes if provided in options.
      *
      * 2. **`eachUrl` phase** - For all plugins with `eachUrl`, runs
      *    sequentially in the main thread. These are lightweight checks

package/lib/nitpicker.js

@@ -8,18 +8,27 @@ import { importModules } from './import-modules.js';
 import { loadPluginSettings } from './load-plugin-settings.js';
 import { Table } from './table.js';
 import { UrlEventBus } from './url-event-bus.js';
-import { runInWorker } from './worker/run-in-worker.js';
+import { WorkerPool } from './worker/worker-pool.js';
 export { definePlugin } from './hooks/define-plugin.js';
 const __filename = new URL(import.meta.url).pathname;
 const __dirname = path.dirname(__filename);
 /**
- * Resolved path to the compiled Worker entry point.
- * This file is loaded by `runInWorker()` in a `new Worker(...)` call.
+ * Resolved path to the compiled per-page analysis module.
+ * Each task posted to the pool carries this path so the worker can
+ * dynamically import it (cached after first import).
  * @see {@link ./page-analysis-worker.ts} for the source
  */
 const pageAnalysisWorkerPath = path.resolve(__dirname, 'page-analysis-worker.js');
-/** Maximum number of concurrent Worker threads per plugin. */
-const CONCURRENCY_LIMIT = 50;
+/**
+ * Resolved path to the compiled long-lived worker thread script.
+ * Used as the `workerPath` when constructing {@link WorkerPool} instances.
+ */
+const workerPath = path.resolve(__dirname, 'worker/worker.js');
+/**
+ * Default concurrency used when a plugin does not declare its own value.
+ * Tracks the number of CPU cores so that worker pools scale with the host.
+ */
+const DEFAULT_CONCURRENCY = Math.max(1, os.cpus().length);
 /**
  * Core orchestrator for running analyze plugins against a `.nitpicker` archive.
  *
@@ -30,15 +39,17 @@ const CONCURRENCY_LIMIT = 50;
  *
  * ## Architecture decisions
  *
- * - **Worker threads for `eachPage`**: DOM-heavy analysis (JSDOM + axe-core,
- *   markuplint, etc.) runs in isolated Worker threads so that a crashing plugin
- *   cannot take down the main process and memory from JSDOM windows is reclaimed
- *   when the Worker exits. See {@link ./worker/run-in-worker.ts!runInWorker}.
+ * - **Worker pool per plugin**: Each plugin gets its own long-lived
+ *   {@link ./worker/worker-pool.ts!WorkerPool}, sized by either the plugin's
+ *   declared `concurrency` or {@link DEFAULT_CONCURRENCY} (CPU core count).
+ *   Workers are spawned once and reused across every page, so the V8 isolate
+ *   / JSDOM module / plugin module boot cost is paid only `concurrency`
+ *   times per plugin instead of once per page.
  *
- * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially,
- *   and for each plugin, pages are processed in parallel (limit: 50) using
- *   a bounded Promise pool. This enables per-plugin progress tracking via
- *   {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}.
+ * - **Plugin-outer, page-inner loop**: Plugins are processed sequentially.
+ *   For each plugin, pages are submitted to that plugin's pool, which queues
+ *   them and dispatches to idle workers. This enables per-plugin progress
+ *   tracking via {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}.
  *
  * - **Cache layer**: Results are cached per `pluginName:url` using
  *   `@d-zero/shared/cache` so that re-running analysis after a partial failure
@@ -94,16 +105,17 @@ export class Nitpicker extends EventEmitter {
      * Runs all configured analyze plugins (or a filtered subset) against
      * every page in the archive.
      *
-     * Plugins are processed **sequentially** (one at a time), while pages
-     * within each plugin are processed in **parallel** (bounded to
-     * {@link CONCURRENCY_LIMIT}). This architecture enables per-plugin
-     * progress tracking via Lanes.
+     * Plugins are processed **sequentially** (one at a time). For each plugin,
+     * pages are processed in **parallel** through a dedicated long-lived
+     * {@link ./worker/worker-pool.ts!WorkerPool} sized either by the plugin's
+     * declared concurrency or by {@link DEFAULT_CONCURRENCY}. This architecture
+     * enables per-plugin progress tracking via Lanes.
      *
      * The analysis proceeds in two phases:
      *
-     * 1. **`eachPage` phase** - For each plugin with `eachPage`, spawns
-     *    Worker threads via a bounded Promise pool to analyze all pages.
-     *    Progress is displayed via Lanes if provided in options.
+     * 1. **`eachPage` phase** - For each plugin with `eachPage`, dispatches
+     *    page analysis tasks to the plugin's worker pool. Progress is
+     *    displayed via Lanes if provided in options.
      *
      * 2. **`eachUrl` phase** - For all plugins with `eachUrl`, runs
      *    sequentially in the main thread. These are lightweight checks
@@ -170,7 +182,7 @@ export class Nitpicker extends EventEmitter {
         await this.archive.getPagesWithRefs(100_000, async (pages) => {
             const urlEmitter = new UrlEventBus();
             // Phase 1: eachPage plugins (sequentially, pages in parallel)
-            for (const [pluginSeqIndex, { plugin }] of eachPagePlugins.entries()) {
+            for (const [pluginSeqIndex, { plugin, modIndex }] of eachPagePlugins.entries()) {
                 const laneId = pluginLaneIds.get(plugin.name);
                 const label = pluginLabels.get(plugin.name) ?? plugin.name;
                 let done = 0;
@@ -182,87 +194,101 @@ export class Nitpicker extends EventEmitter {
                     lanes?.update(laneId, `${label}: ${done}/${pages.length} (${pluginPercent}%)%braille%`);
                 };
                 updateProgress();
-                // Bounded Promise pool (replaces deal())
-                const executing = new Set();
+                const pluginConcurrency = Math.max(1, analyzeMods[modIndex]?.concurrency ?? DEFAULT_CONCURRENCY);
+                const pool = new WorkerPool({
+                    size: pluginConcurrency,
+                    workerPath,
+                });
                 let pluginPageDataCount = 0;
                 let pluginErrorCount = 0;
-                for (const [pageIndex, page] of pages.entries()) {
-                    const task = (async () => {
-                        try {
-                            const cacheKey = `${plugin.name}:${page.url.href}`;
-                            const cached = await cache.load(cacheKey);
-                            if (cached) {
-                                const { pages: cachedPages, violations } = cached;
-                                if (cachedPages) {
-                                    table.addData(cachedPages);
-                                    pluginPageDataCount += Object.keys(cachedPages).length;
+                try {
+                    // Bound the number of in-flight IIFEs so HTML strings loaded
+                    // via page.getHtml() do not pile up on the main thread while
+                    // they wait for a worker. A small buffer above pool size keeps
+                    // the pool continuously fed without staging too much HTML.
+                    const inFlight = new Set();
+                    const highWater = pluginConcurrency * 2;
+                    for (const [pageIndex, page] of pages.entries()) {
+                        const task = (async () => {
+                            try {
+                                const cacheKey = `${plugin.name}:${page.url.href}`;
+                                const cached = await cache.load(cacheKey);
+                                if (cached) {
+                                    const { pages: cachedPages, violations } = cached;
+                                    if (cachedPages) {
+                                        table.addData(cachedPages);
+                                        pluginPageDataCount += Object.keys(cachedPages).length;
+                                    }
+                                    if (violations) {
+                                        for (const v of violations) {
+                                            allViolations.push(v);
+                                        }
+                                        pluginViolationCount += violations.length;
+                                    }
+                                    done++;
+                                    updateProgress();
+                                    return;
                                 }
-                                if (violations) {
-                                    for (const v of violations) {
+                                const html = await page.getHtml();
+                                if (!html) {
+                                    done++;
+                                    updateProgress();
+                                    return;
+                                }
+                                const report = await pool.run({
+                                    filePath: pageAnalysisWorkerPath,
+                                    num: pageIndex,
+                                    total: pages.length,
+                                    emitter: urlEmitter,
+                                    initialData: {
+                                        plugin,
+                                        pages: {
+                                            html,
+                                            url: page.url,
+                                        },
+                                    },
+                                });
+                                const tablePages = {};
+                                if (report?.page) {
+                                    tablePages[page.url.href] = report.page;
+                                    table.addDataToUrl(page.url, report.page);
+                                    pluginPageDataCount++;
+                                }
+                                await cache.store(cacheKey, {
+                                    pages: Object.keys(tablePages).length > 0 ? tablePages : undefined,
+                                    violations: report?.violations,
+                                });
+                                if (report?.violations) {
+                                    for (const v of report.violations) {
                                         allViolations.push(v);
                                     }
-                                    pluginViolationCount += violations.length;
+                                    pluginViolationCount += report.violations.length;
                                 }
                                 done++;
                                 updateProgress();
-                                return;
                             }
-                            const html = await page.getHtml();
-                            if (!html) {
+                            catch (error) {
+                                pluginErrorCount++;
                                 done++;
                                 updateProgress();
-                                return;
-                            }
-                            const report = await runInWorker({
-                                filePath: pageAnalysisWorkerPath,
-                                num: pageIndex,
-                                total: pages.length,
-                                emitter: urlEmitter,
-                                initialData: {
-                                    plugin,
-                                    pages: {
-                                        html,
-                                        url: page.url,
-                                    },
-                                },
-                            });
-                            const tablePages = {};
-                            if (report?.page) {
-                                tablePages[page.url.href] = report.page;
-                                table.addDataToUrl(page.url, report.page);
-                                pluginPageDataCount++;
+                                const message = error instanceof Error ? error.message : String(error);
+                                await this.emit('error', {
+                                    message: `[${plugin.name}] Failed to analyze ${page.url.href}: ${message}`,
+                                    error: error instanceof Error ? error : null,
+                                });
                             }
-                            await cache.store(cacheKey, {
-                                pages: Object.keys(tablePages).length > 0 ? tablePages : undefined,
-                                violations: report?.violations,
-                            });
-                            if (report?.violations) {
-                                for (const v of report.violations) {
-                                    allViolations.push(v);
-                                }
-                                pluginViolationCount += report.violations.length;
-                            }
-                            done++;
-                            updateProgress();
-                        }
-                        catch (error) {
-                            pluginErrorCount++;
-                            done++;
-                            updateProgress();
-                            const message = error instanceof Error ? error.message : String(error);
-                            await this.emit('error', {
-                                message: `[${plugin.name}] Failed to analyze ${page.url.href}: ${message}`,
-                                error: error instanceof Error ? error : null,
-                            });
+                        })();
+                        inFlight.add(task);
+                        task.then(() => inFlight.delete(task), () => inFlight.delete(task));
+                        if (inFlight.size >= highWater) {
+                            await Promise.race(inFlight);
                         }
-                    })();
-                    executing.add(task);
-                    task.then(() => executing.delete(task), () => executing.delete(task));
-                    if (executing.size >= CONCURRENCY_LIMIT) {
-                        await Promise.race(executing);
                     }
+                    await Promise.all(inFlight);
+                }
+                finally {
+                    await pool.terminate();
                 }
-                await Promise.all(executing);
                 // Warn when plugin produced no page data at all
                 if (pluginPageDataCount === 0 && pages.length > 0) {
                     const errorDetail = pluginErrorCount > 0 ? ` (${pluginErrorCount} errors occurred)` : '';

package/lib/page-analysis-worker.d.ts

@@ -2,17 +2,18 @@
  * Worker thread module for per-page single-plugin execution.
  *
  * This is the default export loaded by {@link ./worker/runner.ts!runner}
- * when analyzing a single page with a single plugin. It:
+ * for each task dispatched by the {@link ./worker/worker-pool.ts!WorkerPool}. It:
  *
  * 1. Dynamically imports the configured plugin via {@link importModules}
+ *    (cached after the first task on the same worker)
  * 2. If the plugin implements `eachPage`:
  *    - Creates a JSDOM instance from the raw HTML
  *    - Calls the plugin's `eachPage` hook with the DOM window
  *    - Closes the JSDOM window to free memory
  * 3. Returns the plugin result as {@link ReportPage} or `null`
  *
- * Each Worker invocation handles exactly one plugin, so the calling code
- * can track per-plugin progress independently.
+ * One invocation processes exactly one plugin × one page, even though
+ * the worker hosting this module handles many tasks over its lifetime.
  * @module
  */
 import type { Plugin, ReportPage } from './types.js';
@@ -20,10 +21,11 @@ import type { UrlEventBus } from './url-event-bus.js';
 import type { ExURL as URL } from '@d-zero/shared/parse-url';
 /**
  * Initial data payload for the page analysis worker.
- * Passed via `workerData` and consumed by the default export.
+ * Wrapped inside the `task` message dispatched by the {@link ./worker/worker-pool.ts!WorkerPool}
+ * and consumed by this module's default export.
  *
  * Uses `type` instead of `interface` because this type must satisfy the
- * `Record<string, unknown>` constraint required by the Worker data serialization.
+ * `Record<string, unknown>` constraint required by the Worker message serialization.
  */
 export type PageAnalysisWorkerData = {
     /** Single analyze plugin to execute against the page. */

package/lib/page-analysis-worker.js

@@ -2,17 +2,18 @@
  * Worker thread module for per-page single-plugin execution.
  *
  * This is the default export loaded by {@link ./worker/runner.ts!runner}
- * when analyzing a single page with a single plugin. It:
+ * for each task dispatched by the {@link ./worker/worker-pool.ts!WorkerPool}. It:
  *
  * 1. Dynamically imports the configured plugin via {@link importModules}
+ *    (cached after the first task on the same worker)
  * 2. If the plugin implements `eachPage`:
  *    - Creates a JSDOM instance from the raw HTML
  *    - Calls the plugin's `eachPage` hook with the DOM window
  *    - Closes the JSDOM window to free memory
  * 3. Returns the plugin result as {@link ReportPage} or `null`
  *
- * Each Worker invocation handles exactly one plugin, so the calling code
- * can track per-plugin progress independently.
+ * One invocation processes exactly one plugin × one page, even though
+ * the worker hosting this module handles many tasks over its lifetime.
  * @module
  */
 import { JSDOM } from 'jsdom';

package/lib/types.d.ts

@@ -119,6 +119,17 @@ export interface AnalyzePlugin<T extends string = string> {
      * Shown instead of the raw package name (e.g. `"axe: アクセシビリティチェック"`).
      */
     label?: string;
+    /**
+     * Maximum number of pages this plugin processes in parallel.
+     *
+     * Each plugin is allocated its own {@link ../worker/worker-pool.ts!WorkerPool}
+     * sized to this value. Heavy plugins (e.g. Lighthouse, which spawns a
+     * full Chrome instance per page) should set a small number; lightweight
+     * DOM-only plugins can leave it unset.
+     *
+     * When omitted, the orchestrator falls back to `os.cpus().length`.
+     */
+    concurrency?: number;
     /**
      * Column header definitions contributed by this plugin.
      * Keys are column identifiers (`T`), values are human-readable labels
@@ -188,7 +199,7 @@ export interface ReportPage<T extends string> {
  * ran `eachPage` for a single page.
  * @template T - Column key union.
  * @see {@link ./page-analysis-worker.ts} for the Worker entry point that produces this
- * @see {@link ./worker/run-in-worker.ts!runInWorker} for the main-thread consumer
+ * @see {@link ./worker/worker-pool.ts!WorkerPool} for the main-thread consumer
  */
 export interface ReportPages<T extends string> {
     /** Per-URL table data from all plugins. */

package/lib/url-event-bus.d.ts

@@ -20,13 +20,14 @@ export interface UrlEventBusEvent {
  *   UrlEventBus. The Worker thread entry point ({@link ./worker/worker.ts})
  *   listens for these and forwards them to the main thread via `parentPort.postMessage`.
  *
- * - **In the main thread**: {@link ./worker/run-in-worker.ts!runInWorker} creates its own
- *   UrlEventBus and re-emits `'url'` messages received from the Worker.
+ * - **In the main thread**: {@link ./worker/worker-pool.ts!WorkerPool} routes
+ *   `'url'` messages received from workers to the per-task UrlEventBus
+ *   supplied by the caller.
  *
- * This indirection allows the same plugin code to work both in Worker threads
- * and in direct execution mode (when `useWorker` is `false`).
- * @see {@link ./worker/worker.ts} for Worker-side forwarding
- * @see {@link ./worker/run-in-worker.ts!runInWorker} for main-thread re-emission
+ * This indirection lets plugin code work the same way regardless of which
+ * worker in the pool is currently processing a given page.
+ * @see {@link ./worker/worker.ts} for worker-side forwarding
+ * @see {@link ./worker/worker-pool.ts!WorkerPool} for main-thread routing
  */
 export declare class UrlEventBus extends EventEmitter<UrlEventBusEvent> {
 }

package/lib/url-event-bus.js

@@ -8,13 +8,14 @@ import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-awa
  *   UrlEventBus. The Worker thread entry point ({@link ./worker/worker.ts})
  *   listens for these and forwards them to the main thread via `parentPort.postMessage`.
  *
- * - **In the main thread**: {@link ./worker/run-in-worker.ts!runInWorker} creates its own
- *   UrlEventBus and re-emits `'url'` messages received from the Worker.
+ * - **In the main thread**: {@link ./worker/worker-pool.ts!WorkerPool} routes
+ *   `'url'` messages received from workers to the per-task UrlEventBus
+ *   supplied by the caller.
  *
- * This indirection allows the same plugin code to work both in Worker threads
- * and in direct execution mode (when `useWorker` is `false`).
- * @see {@link ./worker/worker.ts} for Worker-side forwarding
- * @see {@link ./worker/run-in-worker.ts!runInWorker} for main-thread re-emission
+ * This indirection lets plugin code work the same way regardless of which
+ * worker in the pool is currently processing a given page.
+ * @see {@link ./worker/worker.ts} for worker-side forwarding
+ * @see {@link ./worker/worker-pool.ts!WorkerPool} for main-thread routing
  */
 export class UrlEventBus extends EventEmitter {
 }

package/lib/worker/runner.d.ts

@@ -12,8 +12,8 @@ import type { UrlEventBus } from '../url-event-bus.js';
  * The `filePath` field is deleted from `data` before passing it to the
  * module function, so the module only receives its own domain-specific data.
  *
- * This function is called both from the Worker thread ({@link ./worker.ts})
- * and as a direct fallback when `useWorker` is `false` in {@link ./run-in-worker.ts}.
+ * This function is called from the Worker thread ({@link ./worker.ts}) for
+ * every task delivered by the {@link ./worker-pool.ts!WorkerPool}.
  * @template I - Shape of the caller's initial data (minus the worker infrastructure fields).
  * @template R - Return type of the plugin module's default export.
  * @param data - Combined worker data containing the module path and plugin-specific payload.

package/lib/worker/runner.js

@@ -10,8 +10,8 @@
  * The `filePath` field is deleted from `data` before passing it to the
  * module function, so the module only receives its own domain-specific data.
  *
- * This function is called both from the Worker thread ({@link ./worker.ts})
- * and as a direct fallback when `useWorker` is `false` in {@link ./run-in-worker.ts}.
+ * This function is called from the Worker thread ({@link ./worker.ts}) for
+ * every task delivered by the {@link ./worker-pool.ts!WorkerPool}.
  * @template I - Shape of the caller's initial data (minus the worker infrastructure fields).
  * @template R - Return type of the plugin module's default export.
  * @param data - Combined worker data containing the module path and plugin-specific payload.

package/lib/worker/types.d.ts

@@ -1,13 +1,13 @@
 /**
- * Data payload passed to a Worker thread via `workerData`.
+ * Data payload sent inside a `task` message from {@link ./worker-pool.ts!WorkerPool} to a worker.
  *
  * This type merges the worker infrastructure fields (`filePath`, `num`, `total`)
  * with the caller-supplied initial data (`I`). The `filePath` points to the
  * module whose default export will be invoked by the {@link ../runner.ts!runner}.
  * @template I - Shape of the additional data the caller provides
  *   (e.g. {@link ../../page-analysis-worker.ts!PageAnalysisWorkerData}).
- * @see {@link ../run-in-worker.ts!runInWorker} for where this payload is constructed
- * @see {@link ../runner.ts!runner} for where it is consumed
+ * @see {@link ./worker-pool.ts!WorkerPool.run} for where this payload is constructed
+ * @see {@link ./runner.ts!runner} for where it is consumed
  */
 export type WorkerData<I extends Record<string, unknown>> = {
     /**

package/lib/worker/worker-pool.d.ts

@@ -0,0 +1,82 @@
+import type { UrlEventBus } from '../url-event-bus.js';
+/**
+ * Per-task payload sent into the pool's `run()` method.
+ * @template I - Shape of the per-task data merged into the worker message.
+ */
+export interface PoolTaskParams<I extends Record<string, unknown>> {
+    /** Absolute path to the module to dynamically import inside the worker. */
+    readonly filePath: string;
+    /** Zero-based index of the current item (for progress display). */
+    readonly num: number;
+    /** Total number of items in the batch (for progress display). */
+    readonly total: number;
+    /** Event bus to receive `'url'` events forwarded from the worker. */
+    readonly emitter: UrlEventBus;
+    /** Plugin-specific data delivered to the dynamically imported module. */
+    readonly initialData: I;
+}
+/** Constructor options for {@link WorkerPool}. */
+export interface WorkerPoolOptions {
+    /** Number of long-lived worker threads to maintain. Must be >= 1. */
+    readonly size: number;
+    /** Absolute path to the worker entry script (compiled `worker.js`). */
+    readonly workerPath: string;
+}
+/**
+ * Long-lived pool of Worker threads that share execution across many tasks.
+ *
+ * Replaces the previous "one worker per page" model where every analyzed page
+ * paid the cost of spawning a new V8 isolate, importing JSDOM, importing the
+ * plugin module, and tearing it all down. With the pool, each worker is
+ * created once at the start of an analyze run and processes tasks via
+ * message passing until the pool is terminated.
+ *
+ * ## Why this matters
+ *
+ * On a 750-page archive with `CONCURRENCY_LIMIT = 50`, the old model spawned
+ * 50 workers nearly simultaneously and repeated this every time a worker
+ * finished, producing recurring "boot waves" that drove peak memory above
+ * 20GB. The pool model performs N initial boots and then reuses those V8
+ * isolates for the rest of the run, eliminating the recurring cost entirely.
+ *
+ * ## Message protocol (Pool ↔ Worker)
+ *
+ * | Direction        | `type`        | Payload                          |
+ * |------------------|---------------|----------------------------------|
+ * | Pool → Worker    | `'task'`      | `{ taskId, data }`               |
+ * | Pool → Worker    | `'shutdown'`  | (none)                           |
+ * | Worker → Pool    | `'url'`       | `{ taskId, url }` (forwarded)    |
+ * | Worker → Pool    | `'result'`    | `{ taskId, result, error? }`     |
+ *
+ * Each task carries a unique numeric `taskId` so that responses and URL
+ * notifications from a worker can be routed back to the correct caller.
+ */
+export declare class WorkerPool {
+    #private;
+    /**
+     * Constructs a pool with the given size and worker entry script.
+     * @param options - Pool size and worker entry script path.
+     */
+    constructor(options: WorkerPoolOptions);
+    /**
+     * Submits a task to the pool. Resolves with the worker's `result` payload
+     * once a worker has finished processing it. The task may be queued if all
+     * workers are currently busy.
+     * @template I - Shape of the per-task `initialData` payload.
+     * @template R - Expected result type returned by the worker module.
+     * @param params - Task payload (file path, batch indices, emitter, data).
+     * @returns The worker's result.
+     */
+    run<I extends Record<string, unknown>, R>(params: PoolTaskParams<I>): Promise<R>;
+    /**
+     * Rejects every queued or in-flight task, sends each worker a `shutdown`
+     * message, and awaits its exit. After this call returns, no further
+     * submissions are accepted.
+     *
+     * Pending tasks are rejected synchronously so callers waiting on
+     * `pool.run()` Promises do not hang. Workers handle the shutdown message
+     * by exiting cleanly; if that fails, {@link #shutdownSlot} forces
+     * termination after a 5 second timeout.
+     */
+    terminate(): Promise<void>;
+}