@nitpicker/core 0.4.1

package/lib/page-analysis-worker.js

@@ -0,0 +1,98 @@
+/**
+ * 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:
+ *
+ * 1. Dynamically imports the configured plugin via {@link importModules}
+ * 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.
+ * @module
+ */
+import { JSDOM } from 'jsdom';
+import { importModules } from './import-modules.js';
+/**
+ * Set of critical Node.js global properties that must never be overwritten
+ * by JSDOM window properties.
+ */
+const PROTECTED_GLOBALS = new Set([
+    'process',
+    'global',
+    'globalThis',
+    'console',
+    'Buffer',
+    'setTimeout',
+    'setInterval',
+    'clearTimeout',
+    'clearInterval',
+    'setImmediate',
+    'clearImmediate',
+    'queueMicrotask',
+]);
+/**
+ * Executes a single plugin's `eachPage` hook against a single page.
+ * @template T - Column key union from the plugin's headers.
+ * @param data - Contains the single plugin and page data (HTML + URL).
+ * @param urlEventBus - Event bus for URL discovery events (forwarded to the main thread).
+ * @param num - Zero-based index of the current page in the batch.
+ * @param total - Total number of pages being processed.
+ * @returns Report data from the plugin, or `null` if skipped.
+ * @see {@link ./worker/runner.ts!runner} for how this function is called
+ * @see {@link ./nitpicker.ts!Nitpicker.analyze} for the orchestration context
+ */
+export default async function (data, urlEventBus, num, total) {
+    const { plugin, pages: { html, url }, } = data;
+    const [analyzeMod] = await importModules([plugin]);
+    if (!analyzeMod?.eachPage) {
+        return null;
+    }
+    await urlEventBus.emit('url', url.href);
+    const dom = new JSDOM(html, {
+        url: url.href,
+        runScripts: 'outside-only',
+    });
+    // Expose JSDOM globals so that browser-oriented libraries
+    // (axe-core, @medv/finder, etc.) that inspect the global scope
+    // can find `window`, `document`, `Node`, and other DOM APIs.
+    const g = globalThis;
+    const domGlobalKeys = [];
+    for (const key of Object.getOwnPropertyNames(dom.window)) {
+        if (key in g || PROTECTED_GLOBALS.has(key)) {
+            continue;
+        }
+        try {
+            g[key] = dom.window[key];
+            domGlobalKeys.push(key);
+        }
+        catch {
+            // Some window properties throw on access — skip them
+        }
+    }
+    try {
+        const report = await analyzeMod.eachPage({
+            url,
+            html,
+            window: dom.window,
+            num,
+            total,
+        });
+        return report ?? null;
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`[${plugin.name}] ${error instanceof Error ? error.message : error}`);
+        return null;
+    }
+    finally {
+        for (const key of domGlobalKeys) {
+            delete g[key];
+        }
+        dom.window.close();
+    }
+}

package/lib/read-plugin-labels.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin } from './types.js';
+/**
+ * Reads the `label` property from each plugin by importing and
+ * initializing the plugin module.
+ *
+ * Each plugin module's default export (a `PluginFactory`) is called
+ * with the plugin's configured settings. The resulting `AnalyzePlugin`
+ * object's `label` field is collected into a Map keyed by plugin name.
+ *
+ * Plugins that fail to import or initialize, or that lack a `label`,
+ * are silently skipped.
+ * @param plugins - Array of plugin definitions from the resolved config.
+ * @returns Map from plugin name to its human-readable label.
+ */
+export declare function readPluginLabels(plugins: readonly Plugin[]): Promise<Map<string, string>>;

package/lib/read-plugin-labels.js

@@ -0,0 +1,30 @@
+/**
+ * Reads the `label` property from each plugin by importing and
+ * initializing the plugin module.
+ *
+ * Each plugin module's default export (a `PluginFactory`) is called
+ * with the plugin's configured settings. The resulting `AnalyzePlugin`
+ * object's `label` field is collected into a Map keyed by plugin name.
+ *
+ * Plugins that fail to import or initialize, or that lack a `label`,
+ * are silently skipped.
+ * @param plugins - Array of plugin definitions from the resolved config.
+ * @returns Map from plugin name to its human-readable label.
+ */
+export async function readPluginLabels(plugins) {
+    const labels = new Map();
+    await Promise.all(plugins.map(async (plugin) => {
+        try {
+            const mod = await import(plugin.module);
+            const factory = mod.default;
+            const instance = await factory(plugin.settings ?? {}, plugin.configFilePath);
+            if (instance && typeof instance.label === 'string') {
+                labels.set(plugin.name, instance.label);
+            }
+        }
+        catch {
+            // Module not importable or factory failed — skip
+        }
+    }));
+    return labels;
+}

package/lib/table.d.ts

@@ -0,0 +1,75 @@
+import type { TableData, TableHeaders, TablePages } from './types.js';
+import type { ExURL as URL } from '@d-zero/shared/parse-url';
+/**
+ * In-memory accumulator for tabular report data.
+ *
+ * Table collects column headers from plugins and per-URL row data from
+ * analysis results. It uses `Map` internally for efficient merge operations
+ * (multiple plugins contribute columns to the same URL row), then serializes
+ * to plain objects for JSON storage in the archive.
+ *
+ * ## Merge semantics
+ *
+ * When data is added for a URL that already has entries, the new columns are
+ * shallow-merged with existing ones (later values overwrite earlier ones for
+ * the same key). This allows multiple plugins to contribute different columns
+ * to the same row without conflicts, as long as they use distinct column keys.
+ * @template T - String literal union of all column keys across plugins.
+ * @example
+ * ```ts
+ * const table = new Table<'title' | 'score'>();
+ * table.addHeaders({ title: 'Page Title', score: 'Score' });
+ * table.addDataToUrl(url, {
+ *   title: { value: 'Home' },
+ *   score: { value: 95 },
+ * });
+ * const json = table.toJSON();
+ * // { headers: { title: 'Page Title', score: 'Score' }, data: { 'https://...': { ... } } }
+ * ```
+ * @see {@link ./types.ts} for the underlying type aliases
+ */
+export declare class Table<T extends string> {
+    #private;
+    /**
+     * Merges a batch of URL-keyed page data into the table.
+     * Typically called with deserialized data from a Worker thread or cache.
+     * @param data - Object where keys are URL strings and values are column data.
+     */
+    addData(data: TablePages<T>): void;
+    /**
+     * Adds or merges column data for a single URL.
+     * @param url - The page URL to associate the data with.
+     * @param data - Column values to store for this URL.
+     */
+    addDataToUrl(url: URL, data: TableData<T>): void;
+    /**
+     * Registers column headers from a plugin.
+     *
+     * Multiple plugins can call this independently; headers are merged by key.
+     * If two plugins declare the same key with different labels, the later
+     * registration wins.
+     * @param headers - Map of column keys to display labels.
+     */
+    addHeaders(headers: TableHeaders<T>): void;
+    /**
+     * Returns all row data as a plain object (serializable to JSON).
+     * @returns URL-keyed record of column data.
+     */
+    getData(): TablePages<T>;
+    /**
+     * Retrieves column data for a specific URL, or `undefined` if not present.
+     * @param url - The page URL to look up.
+     * @returns Column data for the URL, or `undefined`.
+     */
+    getDataByUrl(url: URL): TableData<T> | undefined;
+    /**
+     * Serializes the entire table (headers + data) to a JSON-compatible object.
+     *
+     * Used when storing the table in the archive via `archive.setData('analysis/table', ...)`.
+     * @returns Plain object with `headers` and `data` properties.
+     */
+    toJSON(): {
+        headers: Record<T, string>;
+        data: Record<string, TableData<T>>;
+    };
+}

package/lib/table.js

@@ -0,0 +1,132 @@
+/**
+ * In-memory accumulator for tabular report data.
+ *
+ * Table collects column headers from plugins and per-URL row data from
+ * analysis results. It uses `Map` internally for efficient merge operations
+ * (multiple plugins contribute columns to the same URL row), then serializes
+ * to plain objects for JSON storage in the archive.
+ *
+ * ## Merge semantics
+ *
+ * When data is added for a URL that already has entries, the new columns are
+ * shallow-merged with existing ones (later values overwrite earlier ones for
+ * the same key). This allows multiple plugins to contribute different columns
+ * to the same row without conflicts, as long as they use distinct column keys.
+ * @template T - String literal union of all column keys across plugins.
+ * @example
+ * ```ts
+ * const table = new Table<'title' | 'score'>();
+ * table.addHeaders({ title: 'Page Title', score: 'Score' });
+ * table.addDataToUrl(url, {
+ *   title: { value: 'Home' },
+ *   score: { value: 95 },
+ * });
+ * const json = table.toJSON();
+ * // { headers: { title: 'Page Title', score: 'Score' }, data: { 'https://...': { ... } } }
+ * ```
+ * @see {@link ./types.ts} for the underlying type aliases
+ */
+export class Table {
+    /** Per-URL row data. Key is the URL href string. */
+    #data = new Map();
+    /** Column header definitions accumulated from all plugins. */
+    #headers = new Map();
+    /**
+     * Merges a batch of URL-keyed page data into the table.
+     * Typically called with deserialized data from a Worker thread or cache.
+     * @param data - Object where keys are URL strings and values are column data.
+     */
+    addData(data) {
+        const entries = Object.entries(data);
+        for (const [k, v] of entries) {
+            this.#add(k, v);
+        }
+    }
+    /**
+     * Adds or merges column data for a single URL.
+     * @param url - The page URL to associate the data with.
+     * @param data - Column values to store for this URL.
+     */
+    addDataToUrl(url, data) {
+        this.#add(url.href, data);
+    }
+    /**
+     * Registers column headers from a plugin.
+     *
+     * Multiple plugins can call this independently; headers are merged by key.
+     * If two plugins declare the same key with different labels, the later
+     * registration wins.
+     * @param headers - Map of column keys to display labels.
+     */
+    addHeaders(headers) {
+        const entries = Object.entries(headers);
+        for (const entry of entries) {
+            const [key, name] = entry;
+            this.#headers.set(key, name);
+        }
+    }
+    /**
+     * Returns all row data as a plain object (serializable to JSON).
+     * @returns URL-keyed record of column data.
+     */
+    getData() {
+        return mapToObject(this.#data);
+    }
+    /**
+     * Retrieves column data for a specific URL, or `undefined` if not present.
+     * @param url - The page URL to look up.
+     * @returns Column data for the URL, or `undefined`.
+     */
+    getDataByUrl(url) {
+        return this.#data.get(url.href);
+    }
+    /**
+     * Serializes the entire table (headers + data) to a JSON-compatible object.
+     *
+     * Used when storing the table in the archive via `archive.setData('analysis/table', ...)`.
+     * @returns Plain object with `headers` and `data` properties.
+     */
+    toJSON() {
+        return {
+            headers: mapToObject(this.#headers),
+            data: mapToObject(this.#data),
+        };
+    }
+    /**
+     * Internal merge-or-insert for a single URL row.
+     * If the URL already has data, the new values are shallow-merged.
+     * @param k - URL href string used as the row key.
+     * @param v - Column data to add or merge.
+     */
+    #add(k, v) {
+        const data = this.#data.get(k);
+        if (data) {
+            this.#data.set(k, {
+                ...data,
+                ...v,
+            });
+        }
+        else {
+            this.#data.set(k, v);
+        }
+    }
+}
+/**
+ * Converts a `Map<K, V>` to a plain `Record<K, V>` object.
+ *
+ * Used internally to serialize Map-based storage into JSON-compatible
+ * objects for archive storage and Worker message passing.
+ * @template K - String key type.
+ * @template V - Value type.
+ * @param map - The Map to convert.
+ * @returns A plain object with the same key-value pairs.
+ */
+function mapToObject(map) {
+    const entries = map.entries();
+    const object = {};
+    for (const entry of entries) {
+        const [k, v] = entry;
+        object[k] = v;
+    }
+    return object;
+}

package/lib/types.d.ts

@@ -0,0 +1,264 @@
+import type { Lanes } from '@d-zero/dealer';
+import type { ExURL as URL } from '@d-zero/shared/parse-url';
+import type { TableValue, Violation } from '@nitpicker/types';
+import type { DOMWindow } from 'jsdom';
+/**
+ * Represents a single analyze plugin loaded from the user's configuration.
+ *
+ * Each plugin corresponds to an npm module that exports a {@link PluginFactory}
+ * factory function as its default export. The `settings` object is passed
+ * through to that factory at initialization time.
+ * @see {@link ./load-plugin-settings.ts} for how plugins are discovered from cosmiconfig
+ * @see {@link ./import-modules.ts} for how plugins are dynamically imported
+ */
+export interface Plugin {
+    /**
+     * Human-readable plugin name. Currently unused at runtime but kept
+     * for backward compatibility with older config formats.
+     * @deprecated Use `module` to identify plugins instead.
+     */
+    name: string;
+    /**
+     * The npm module specifier to `import()` (e.g. `"@nitpicker/analyze-axe"`).
+     */
+    module: string;
+    /**
+     * Absolute path to the configuration file where this plugin was declared.
+     * Passed to the plugin so it can resolve relative paths in its own config.
+     */
+    configFilePath: string;
+    /**
+     * Plugin-specific settings object parsed from the config file.
+     * The shape is determined by the plugin itself (e.g. `{ lang: "ja" }` for axe).
+     */
+    settings?: unknown;
+}
+/**
+ * Options for {@link ../nitpicker.ts!Nitpicker.analyze}.
+ *
+ * Allows callers to provide an external {@link https://www.npmjs.com/package/@d-zero/dealer | Lanes}
+ * instance for rich progress display, and a verbose flag for non-TTY environments.
+ */
+export interface AnalyzeOptions {
+    /** Lanes instance for per-plugin progress display. If omitted, no progress is shown. */
+    readonly lanes?: Lanes;
+    /** When `true`, outputs plain-text progress lines instead of animated Lanes. */
+    readonly verbose?: boolean;
+}
+/**
+ * Internal configuration model used by {@link ../nitpicker.ts!Nitpicker}.
+ *
+ * Built by {@link ./load-plugin-settings.ts!loadPluginSettings} from the
+ * user's cosmiconfig file (e.g. `.nitpickerrc.json`). The external config
+ * format (`ConfigJSON` from `@nitpicker/types`) uses a `plugins.analyze`
+ * object keyed by module name; this internal type normalizes it into an
+ * ordered array of fully-resolved {@link Plugin} entries.
+ */
+export interface Config {
+    /** Ordered list of analyze plugins to execute. */
+    analyze: Plugin[];
+}
+/**
+ * The runtime interface that every analyze plugin must satisfy after
+ * its factory function ({@link PluginFactory}) has been invoked.
+ *
+ * A plugin may implement one or both callback methods:
+ *
+ * - **`eachPage`** - Runs inside a Worker thread with full JSDOM access.
+ *   Best for DOM-dependent analysis (markup validation, text linting,
+ *   accessibility checks). Each invocation receives a parsed `DOMWindow`,
+ *   so plugins can use standard DOM APIs without additional parsing.
+ *
+ * - **`eachUrl`** - Runs in the main thread, receives only the URL and
+ *   external/internal flag. Suited for lightweight, network-based checks
+ *   (e.g. link validation, SEO URL pattern checks).
+ * @template T - String literal union of the column keys this plugin
+ *   contributes to the report table (e.g. `'title' | 'description'`).
+ * @see {@link ./page-analysis-worker.ts} for how `eachPage` is called inside the worker
+ * @see {@link ./nitpicker.ts} for how `eachUrl` is called from the main thread
+ */
+export interface AnalyzePlugin<T extends string = string> {
+    /**
+     * Human-readable display label for interactive prompts.
+     * Shown instead of the raw package name (e.g. `"axe: アクセシビリティチェック"`).
+     */
+    label?: string;
+    /**
+     * Column header definitions contributed by this plugin.
+     * Keys are column identifiers (`T`), values are human-readable labels
+     * shown in the report header row.
+     */
+    headers?: TableHeaders<T>;
+    /**
+     * Per-page analysis callback executed in a Worker thread.
+     * @param page - Context for the current page, including the raw HTML,
+     *   a live JSDOM window, the page URL, and progress counters.
+     * @param page.url - Parsed URL of the page being analyzed.
+     * @param page.html - Raw HTML string of the page.
+     * @param page.window - JSDOM window with the page's DOM tree. Closed after the callback returns.
+     * @param page.num - Zero-based index of the current page in the batch.
+     * @param page.total - Total number of pages in the batch.
+     * @returns Report data for this page, or `null` to skip.
+     */
+    eachPage?(page: {
+        /** Parsed URL of the page being analyzed. */
+        url: URL;
+        /** Raw HTML string of the page. */
+        html: string;
+        /** JSDOM window with the page's DOM tree. Closed after the callback returns. */
+        window: DOMWindow;
+        /** Zero-based index of the current page in the batch. */
+        num: number;
+        /** Total number of pages in the batch. */
+        total: number;
+    }): Promise<ReportPage<T> | null> | ReportPage<T> | null;
+    /**
+     * Per-URL analysis callback executed in the main thread.
+     *
+     * Unlike `eachPage`, this callback does **not** receive HTML or a DOM
+     * window. It is designed for checks that depend only on URL metadata
+     * (e.g. checking URL patterns, external link policies).
+     * @param page - URL context including external/internal classification.
+     * @param page.url - Parsed URL being analyzed.
+     * @param page.isExternal - Whether this URL is external to the crawled site.
+     * @returns Report data for this URL, or `null` to skip.
+     */
+    eachUrl?(page: {
+        /** Parsed URL being analyzed. */
+        url: URL;
+        /** Whether this URL is external to the crawled site. */
+        isExternal: boolean;
+    }): Promise<ReportPage<T> | null> | ReportPage<T> | null;
+}
+/**
+ * The return value of a single {@link AnalyzePlugin.eachPage} or {@link AnalyzePlugin.eachUrl}
+ * invocation for one page/URL.
+ *
+ * A plugin can contribute tabular data (displayed in spreadsheet columns)
+ * and/or violation records (displayed in a dedicated violations sheet).
+ * @template T - Column key union matching the plugin's `headers`.
+ */
+export interface ReportPage<T extends string> {
+    /** Column data for this page. Keys must be a subset of `T`. */
+    page?: TableData<T>;
+    /** Violations detected on this page (e.g. a11y issues, lint errors). */
+    violations?: Violation[];
+}
+/**
+ * Aggregated report data from a Worker thread, keyed by page URL.
+ *
+ * This is the message payload returned from the Worker to the main thread
+ * via the `'finish'` message. It aggregates results from all plugins that
+ * 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
+ */
+export interface ReportPages<T extends string> {
+    /** Per-URL table data from all plugins. */
+    pages?: TablePages<T>;
+    /** Combined violations from all plugins. */
+    violations?: Violation[];
+}
+/**
+ * Factory function signature that every analyze plugin module must
+ * export as its default export.
+ *
+ * The factory receives the user's settings object (`O`) and returns
+ * an {@link AnalyzePlugin} instance (or a Promise thereof). This two-phase
+ * pattern allows plugins to perform async initialization (e.g.
+ * loading locale files, compiling lint configs) once, then reuse
+ * the resulting plugin for every page.
+ *
+ * Use {@link ./hooks/define-plugin.ts!definePlugin} to define a
+ * plugin with full type inference.
+ * @template O - Shape of the plugin's settings from the config file.
+ * @template T - String literal union of column keys the plugin contributes.
+ * @example
+ * ```ts
+ * // In @nitpicker/analyze-search/src/index.ts
+ * import { definePlugin } from '@nitpicker/core';
+ *
+ * type Options = { keywords: string[] };
+ *
+ * export default definePlugin(async (options: Options) => {
+ *   return {
+ *     headers: { found: 'Keywords Found' },
+ *     async eachPage({ html }) {
+ *       const count = options.keywords.filter(k => html.includes(k)).length;
+ *       return { page: { found: { value: count } } };
+ *     },
+ *   };
+ * });
+ * ```
+ * @see {@link AnalyzePlugin} for the runtime interface
+ * @see {@link ./hooks/define-plugin.ts!definePlugin} for the type-safe wrapper
+ */
+export type PluginFactory<O, T extends string = string> = (options: O, configFilePath: string) => Promise<AnalyzePlugin<T>> | AnalyzePlugin<T>;
+/**
+ * Column header definitions: maps column key to display label.
+ * @example
+ * ```ts
+ * const headers: TableHeaders<'title' | 'desc'> = {
+ *   title: 'Page Title',
+ *   desc: 'Meta Description',
+ * };
+ * ```
+ */
+export type TableHeaders<K extends string> = Record<K, string>;
+/** Internal Map representation of {@link TableHeaders}, used by {@link ../table.ts!Table}. */
+export type TableHeaderMap<K extends string> = Map<K, string>;
+/** A single row of cell values keyed by column identifier. */
+export type TableData<K extends string> = Record<K, TableValue>;
+/**
+ * Multiple rows of table data keyed by page URL.
+ * This is the serialized form used in Worker message payloads and JSON output.
+ */
+export type TablePages<K extends string> = Record<string, TableData<K>>;
+/**
+ * Internal Map representation of page-keyed table data.
+ * Used by {@link ../table.ts!Table} for efficient merge operations.
+ */
+export type TableRow<K extends string> = Map<string, TableData<K>>;
+/**
+ * Payload for starting an analyze action.
+ * @internal
+ */
+export interface PluginExecutionContext {
+    /** Human-readable name of the plugin module. */
+    pluginModuleName: string;
+    /** Resolved file system path to the plugin module. */
+    pluginModulePath: string;
+    /** Plugin-specific settings to pass to the hook factory. */
+    settings: unknown;
+    /** Path to the config file where this action was declared. */
+    configFilePath: string;
+    /** Temporary directory where the archive is extracted. */
+    archiveTempDir: string;
+    /** Full resolved configuration. */
+    config: Config;
+}
+/**
+ * Event map for the {@link ../nitpicker.ts!Nitpicker} event emitter.
+ *
+ * Consumers can listen to these events via `nitpicker.on('writeFile', ...)`.
+ * @see {@link ../nitpicker.ts!Nitpicker} which extends `TypedAwaitEventEmitter<NitpickerEvent>`
+ */
+export interface NitpickerEvent {
+    /**
+     * Emitted after the archive file has been successfully written to disk.
+     */
+    writeFile: {
+        /** Absolute path to the written `.nitpicker` archive file. */
+        filePath: string;
+    };
+    /**
+     * Emitted when a non-fatal error occurs during analysis.
+     */
+    error: {
+        /** Human-readable error description. */
+        message: string;
+        /** Original Error object, or `null` if unavailable. */
+        error: Error | null;
+    };
+}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,32 @@
+import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+/**
+ * Event map for {@link UrlEventBus}.
+ *
+ * Currently supports a single event type for URL discovery notifications.
+ */
+export interface UrlEventBusEvent {
+    /**
+     * Emitted when a URL is discovered or being processed.
+     * The payload is the URL href string.
+     */
+    url: string;
+}
+/**
+ * Typed event bus for URL discovery notifications.
+ *
+ * Used as a communication channel between Worker threads and the main thread:
+ *
+ * - **Inside Workers**: The each-page worker emits `'url'` events on a local
+ *   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.
+ *
+ * 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
+ */
+export declare class UrlEventBus extends EventEmitter<UrlEventBusEvent> {
+}

package/lib/url-event-bus.js

@@ -0,0 +1,20 @@
+import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+/**
+ * Typed event bus for URL discovery notifications.
+ *
+ * Used as a communication channel between Worker threads and the main thread:
+ *
+ * - **Inside Workers**: The each-page worker emits `'url'` events on a local
+ *   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.
+ *
+ * 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
+ */
+export class UrlEventBus extends EventEmitter {
+}