@cubingcenter/scrambler 0.6.3 → 0.8.0

package/dist/puzzles/cube4/state.js

@@ -36,8 +36,11 @@ export function cube4StatesEqual(a, b) {
         typedArrayEqual(a.wp, b.wp) &&
         typedArrayEqual(a.centers, b.centers));
 }
+// Read-only canonical solved state for comparisons (never mutated, so a
+// single shared instance is safe and avoids allocating 4 arrays per call).
+const SOLVED_STATE = createSolvedCube4State();
 export function isSolvedCube4State(state) {
-    return cube4StatesEqual(state, createSolvedCube4State());
+    return cube4StatesEqual(state, SOLVED_STATE);
 }
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/puzzles/cube4/worker-pool.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Worker pool for 4x4 random-state scrambles (Node.js `worker_threads`).
+ *
+ * Why: generation is CPU-bound in a single event loop — a `Promise.all`
+ * batch of N scrambles does not scale. This pool spreads one batch across
+ * N threads so `generateScrambles`-style batches grow roughly linearly
+ * with core count, while keeping the (seed, complete-options) → moves
+ * contract byte-identical to the inline path: tasks forward the FULL
+ * options object verbatim and `worker.ts` calls the very same
+ * `generateCube4Scramble`.
+ *
+ * Lifecycle:
+ *  - Lazy spawn: threads are created on demand (one per queued job, up to
+ *    `size`), never in the constructor. A cold first generation pays for
+ *    table loading (≈37 MB) per spawned thread, once; the thread then
+ *    reuses its tables for every later job (per-thread promise cache inside
+ *    `scrambler.ts`).
+ *  - Idle threads are `unref()`d, so a pool that is never terminated does
+ *    not keep the process alive; in-flight jobs `ref()` their thread so an
+ *    awaited batch always completes.
+ *  - One task in flight per thread; extra tasks queue FIFO.
+ *  - `terminate()` rejects everything queued/in-flight with
+ *    `Cube4WorkerPoolClosedError` and joins all threads — after it
+ *    resolves there are no open handles.
+ *
+ * Failure: a crashed thread only fails ITS in-flight task and is dropped
+ * from the pool; the next dispatch spawns a fresh thread (which reloads
+ * tables). Typed solver errors from inside a worker arrive as an `Error`
+ * with the original `name`, `message` and `code` preserved (see
+ * `worker-protocol.ts`).
+ *
+ * Dual-build note: this file intentionally contains no bare `import.meta`
+ * (it must also compile in the CommonJS build that `index.ts` is part of).
+ * The worker entry is located from `__filename` (CJS) or this module's top
+ * stack frame (ESM), and `dist-cjs` falls back to the sibling ESM tree,
+ * which always ships `worker.js`.
+ */
+import type { ScrambleResult } from "../../core/types.js";
+import type { Cube4ScrambleOptions } from "./scrambler.js";
+import { type Cube4WorkerGenerationOptions } from "./worker-protocol.js";
+import type { ScrambleOptions } from "../../core/types.js";
+/** Full option surface accepted by the pool and the batch helper. */
+export type Cube4PoolOptions = Cube4WorkerGenerationOptions;
+export interface Cube4WorkerPoolOptions {
+    /**
+     * Maximum number of worker threads. Defaults to
+     * `os.availableParallelism() - 1` (min 1), resolved lazily so importing
+     * this module costs nothing.
+     */
+    size?: number;
+    /**
+     * Explicit path to the worker entry (`worker.ts` / `worker.js`).
+     * Auto-resolved normally; pass this only if the automatic location
+     * fails (e.g. a bundler renamed this module).
+     */
+    workerPath?: string;
+}
+/** Typed rejection used for post-terminate operations and shutdown itself. */
+export declare class Cube4WorkerPoolClosedError extends Error {
+    readonly code: "cube4-pool-closed";
+    constructor(action?: string);
+}
+/**
+ * Batch seed derivation — byte-for-byte the semantics of
+ * `deriveBatchScrambleOptions` in `src/core/api.ts` (`generateScrambles`):
+ * with a `seed` and `count > 1`, item i uses `${seed}:${i}`; otherwise the
+ * options pass through untouched. Exported so tests can assert the pool
+ * batch equals the sequential/core batch for the same inputs.
+ */
+export declare function deriveBatchCube4Options(options: Cube4PoolOptions, index: number, count: number): Cube4PoolOptions;
+export declare class Cube4WorkerPool {
+    private readonly workers;
+    private readonly queue;
+    private readonly explicitSize;
+    private readonly workerPathOption;
+    private sizePromise;
+    /** Last resolved size, kept sync-readable for the pump's headroom check. */
+    private sizeSync;
+    private pumping;
+    private terminatePromise;
+    private nextId;
+    private terminated;
+    constructor(options?: Cube4WorkerPoolOptions);
+    /** Maximum thread count (resolves the default lazily on first use). */
+    get size(): Promise<number>;
+    /** Threads spawned so far (lazily grown; 0 before the first job). */
+    get workerCount(): number;
+    get queuedCount(): number;
+    get busyCount(): number;
+    get closed(): boolean;
+    /**
+     * Generates one scramble on an available thread. Rejects (typed) if the
+     * pool is closed, the worker crashes, the options cannot be
+     * structured-cloned, or generation fails inside the worker.
+     */
+    generate(options?: Cube4PoolOptions): Promise<ScrambleResult>;
+    /**
+     * Batch generation with EXACTLY the seed derivation of core
+     * `generateScrambles` (see `deriveBatchCube4Options`), so results are
+     * identical — move for move — to the sequential path for the same
+     * inputs. Order of the returned array matches request order regardless
+     * of completion order.
+     */
+    generateBatch(count: number, options?: Cube4PoolOptions): Promise<ScrambleResult[]>;
+    /**
+     * Prompt shutdown: rejects queued and in-flight tasks with
+     * `Cube4WorkerPoolClosedError`, terminates every thread and resolves
+     * when none is left. Idempotent.
+     */
+    terminate(): Promise<void>;
+    private resolveSize;
+    /**
+     * Serialised dispatcher: grows the pool (lazy spawn), hands queued jobs
+     * to idle threads, and stops when every thread is busy at capacity.
+     * Re-entry while a spawn is awaited is a no-op — the running loop's
+     * `while` re-checks the queue, and every completion event (`response`,
+     * `crash`) calls `pump()` again.
+     */
+    private pump;
+    private hasDispatchHeadroom;
+    private runPump;
+    private spawnWorker;
+    private dispatch;
+    private handleResponse;
+    private handleWorkerGone;
+    private resolveWorkerEntry;
+}
+/** Shared lazily-created pool (used by `generateCube4ScrambleBatch`). */
+export declare function getDefaultCube4WorkerPool(): Cube4WorkerPool;
+/** Terminates (and forgets) the shared pool — call on process shutdown. */
+export declare function closeDefaultCube4WorkerPool(): Promise<void>;
+/**
+ * Batch convenience mirroring core `generateScrambles` for `444`:
+ *  - `count <= 1` runs INLINE in the caller (no thread spawn, no cold
+ *    start — a single scramble must never get slower);
+ *  - `count > 1` fans out over the shared pool (same seed derivation).
+ */
+export declare function generateCube4ScrambleBatch(count: number, options?: ScrambleOptions & Cube4ScrambleOptions): Promise<ScrambleResult[]>;
+//# sourceMappingURL=worker-pool.d.ts.map

package/dist/puzzles/cube4/worker-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/worker-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAEL,KAAK,4BAA4B,EAGlC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;gBAEjC,MAAM,SAAc;CAIjC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,gBAAgB,CAKlB;AAsED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,WAAW,CAA8B;IACjD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,GAAE,sBAA2B;IAWhD,uEAAuE;IACvE,IAAI,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAE1B;IAED,qEAAqE;IACrE,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,QAAQ,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IAWjE;;;;;;OAMG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAWvF;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB1B,OAAO,CAAC,WAAW;IAmBnB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;IAiBZ,OAAO,CAAC,mBAAmB;YAKb,OAAO;YAuBP,WAAW;IA6BzB,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,kBAAkB;CAkC3B;AAMD,yEAAyE;AACzE,wBAAgB,yBAAyB,IAAI,eAAe,CAG3D;AAED,2EAA2E;AAC3E,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAIjE;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAe,GAAG,oBAAyB,GACnD,OAAO,CAAC,cAAc,EAAE,CAAC,CAQ3B"}

package/dist/puzzles/cube4/worker-pool.js

@@ -0,0 +1,405 @@
+/**
+ * Worker pool for 4x4 random-state scrambles (Node.js `worker_threads`).
+ *
+ * Why: generation is CPU-bound in a single event loop — a `Promise.all`
+ * batch of N scrambles does not scale. This pool spreads one batch across
+ * N threads so `generateScrambles`-style batches grow roughly linearly
+ * with core count, while keeping the (seed, complete-options) → moves
+ * contract byte-identical to the inline path: tasks forward the FULL
+ * options object verbatim and `worker.ts` calls the very same
+ * `generateCube4Scramble`.
+ *
+ * Lifecycle:
+ *  - Lazy spawn: threads are created on demand (one per queued job, up to
+ *    `size`), never in the constructor. A cold first generation pays for
+ *    table loading (≈37 MB) per spawned thread, once; the thread then
+ *    reuses its tables for every later job (per-thread promise cache inside
+ *    `scrambler.ts`).
+ *  - Idle threads are `unref()`d, so a pool that is never terminated does
+ *    not keep the process alive; in-flight jobs `ref()` their thread so an
+ *    awaited batch always completes.
+ *  - One task in flight per thread; extra tasks queue FIFO.
+ *  - `terminate()` rejects everything queued/in-flight with
+ *    `Cube4WorkerPoolClosedError` and joins all threads — after it
+ *    resolves there are no open handles.
+ *
+ * Failure: a crashed thread only fails ITS in-flight task and is dropped
+ * from the pool; the next dispatch spawns a fresh thread (which reloads
+ * tables). Typed solver errors from inside a worker arrive as an `Error`
+ * with the original `name`, `message` and `code` preserved (see
+ * `worker-protocol.ts`).
+ *
+ * Dual-build note: this file intentionally contains no bare `import.meta`
+ * (it must also compile in the CommonJS build that `index.ts` is part of).
+ * The worker entry is located from `__filename` (CJS) or this module's top
+ * stack frame (ESM), and `dist-cjs` falls back to the sibling ESM tree,
+ * which always ships `worker.js`.
+ */
+import { InvalidCountError } from "../../core/errors.js";
+import { generateCube4Scramble } from "./scrambler.js";
+import { deserializeCube4Error } from "./worker-protocol.js";
+/** Typed rejection used for post-terminate operations and shutdown itself. */
+export class Cube4WorkerPoolClosedError extends Error {
+    code = "cube4-pool-closed";
+    constructor(action = "operation") {
+        super(`[cube4] worker pool is closed (${action} rejected).`);
+        this.name = "Cube4WorkerPoolClosedError";
+    }
+}
+/**
+ * Batch seed derivation — byte-for-byte the semantics of
+ * `deriveBatchScrambleOptions` in `src/core/api.ts` (`generateScrambles`):
+ * with a `seed` and `count > 1`, item i uses `${seed}:${i}`; otherwise the
+ * options pass through untouched. Exported so tests can assert the pool
+ * batch equals the sequential/core batch for the same inputs.
+ */
+export function deriveBatchCube4Options(options, index, count) {
+    if (count === 1 || options.seed === undefined) {
+        return options;
+    }
+    return { ...options, seed: `${options.seed}:${index}` };
+}
+const TSX_ARGV = ["--import", "tsx"];
+/**
+ * Locates this module's own file (extension included), dual-build safe:
+ * CJS knows it as `__filename`; in ESM we take the top stack frame, which
+ * V8 reports as the module URL (`file://…`) of `worker-pool.ts|js` — the
+ * path is correct whether or not source maps are enabled (they only move
+ * line/column, never the module URL).
+ */
+function resolveCurrentModuleLocation() {
+    if (typeof __filename === "string" && __filename.length > 0) {
+        return __filename;
+    }
+    const holder = new Error();
+    Error.captureStackTrace?.(holder);
+    const raw = holder.stack;
+    const candidates = [];
+    if (typeof raw === "string") {
+        for (const line of raw.split("\n")) {
+            const match = /^\s*at (?:(?:.*?\s+\())?(.+?):\d+:\d+\)?$/.exec(line.trim());
+            if (match && match[1] !== undefined)
+                candidates.push(match[1]);
+        }
+    }
+    else if (Array.isArray(raw)) {
+        for (const frame of raw) {
+            const name = frame?.getFileName?.();
+            if (typeof name === "string")
+                candidates.push(name);
+        }
+    }
+    for (const candidate of candidates) {
+        if (candidate.includes("worker-pool.")) {
+            return candidate.startsWith("file://") ? fileUrlToPath(candidate) : candidate;
+        }
+    }
+    return undefined;
+}
+/** Minimal `file://` → path conversion (global `URL`, no node:url import). */
+function fileUrlToPath(value) {
+    try {
+        let pathname = decodeURIComponent(new URL(value).pathname);
+        // Windows file URLs keep a leading slash before the drive letter.
+        if (/^\/[A-Za-z]:/.test(pathname))
+            pathname = pathname.slice(1);
+        return pathname;
+    }
+    catch {
+        return value.replace(/^file:\/\//, "");
+    }
+}
+export class Cube4WorkerPool {
+    workers = [];
+    queue = [];
+    explicitSize;
+    workerPathOption;
+    sizePromise;
+    /** Last resolved size, kept sync-readable for the pump's headroom check. */
+    sizeSync = 0;
+    pumping;
+    terminatePromise;
+    nextId = 0;
+    terminated = false;
+    constructor(options = {}) {
+        if (options.size !== undefined) {
+            if (!Number.isInteger(options.size) || options.size < 1) {
+                throw new RangeError(`[cube4] pool size must be an integer >= 1 (got ${options.size}).`);
+            }
+            this.sizeSync = options.size;
+        }
+        this.explicitSize = options.size;
+        this.workerPathOption = options.workerPath;
+    }
+    /** Maximum thread count (resolves the default lazily on first use). */
+    get size() {
+        return this.resolveSize();
+    }
+    /** Threads spawned so far (lazily grown; 0 before the first job). */
+    get workerCount() {
+        return this.workers.length;
+    }
+    get queuedCount() {
+        return this.queue.length;
+    }
+    get busyCount() {
+        return this.workers.reduce((n, rec) => n + (rec.task !== null ? 1 : 0), 0);
+    }
+    get closed() {
+        return this.terminated;
+    }
+    /**
+     * Generates one scramble on an available thread. Rejects (typed) if the
+     * pool is closed, the worker crashes, the options cannot be
+     * structured-cloned, or generation fails inside the worker.
+     */
+    generate(options = {}) {
+        if (this.terminated) {
+            return Promise.reject(new Cube4WorkerPoolClosedError("generate"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.queue.push({ id, options, resolve, reject });
+            this.pump();
+        });
+    }
+    /**
+     * Batch generation with EXACTLY the seed derivation of core
+     * `generateScrambles` (see `deriveBatchCube4Options`), so results are
+     * identical — move for move — to the sequential path for the same
+     * inputs. Order of the returned array matches request order regardless
+     * of completion order.
+     */
+    generateBatch(count, options = {}) {
+        if (!Number.isInteger(count) || count < 1) {
+            return Promise.reject(new InvalidCountError(count));
+        }
+        return Promise.all(Array.from({ length: count }, (_, index) => this.generate(deriveBatchCube4Options(options, index, count))));
+    }
+    /**
+     * Prompt shutdown: rejects queued and in-flight tasks with
+     * `Cube4WorkerPoolClosedError`, terminates every thread and resolves
+     * when none is left. Idempotent.
+     */
+    terminate() {
+        if (this.terminatePromise !== undefined)
+            return this.terminatePromise;
+        this.terminated = true;
+        for (const task of this.queue.splice(0)) {
+            task.reject(new Cube4WorkerPoolClosedError("queued task"));
+        }
+        const records = this.workers.splice(0);
+        const joins = [];
+        for (const rec of records) {
+            if (rec.task !== null) {
+                rec.task.reject(new Cube4WorkerPoolClosedError("in-flight task"));
+                rec.task = null;
+            }
+            joins.push(rec.worker.terminate().then(() => undefined));
+        }
+        this.terminatePromise = Promise.all(joins).then(() => undefined);
+        return this.terminatePromise;
+    }
+    // ── internals ────────────────────────────────────────────────────────
+    resolveSize() {
+        if (this.explicitSize !== undefined)
+            return Promise.resolve(this.explicitSize);
+        this.sizePromise ??= (async () => {
+            try {
+                // @vite-ignore: Node-only; the browser bundle never executes this.
+                const os = await import(/* webpackIgnore: true */ /* @vite-ignore */ "node:os");
+                const parallelism = typeof os.availableParallelism === "function"
+                    ? os.availableParallelism()
+                    : os.cpus().length;
+                this.sizeSync = Math.max(1, parallelism - 1);
+            }
+            catch {
+                this.sizeSync = 4;
+            }
+            return this.sizeSync;
+        })();
+        return this.sizePromise;
+    }
+    /**
+     * Serialised dispatcher: grows the pool (lazy spawn), hands queued jobs
+     * to idle threads, and stops when every thread is busy at capacity.
+     * Re-entry while a spawn is awaited is a no-op — the running loop's
+     * `while` re-checks the queue, and every completion event (`response`,
+     * `crash`) calls `pump()` again.
+     */
+    pump() {
+        if (this.pumping !== undefined || this.terminated)
+            return;
+        this.pumping = this.runPump()
+            .catch(() => undefined) // runPump handles failures per task; belt and braces
+            .finally(() => {
+            this.pumping = undefined;
+            // A task pushed by a microtask that landed between runPump's last
+            // queue check and this finally would have been skipped (pump was
+            // still "running"). Re-pump only when dispatch can make actual
+            // progress — an idle thread or spawn headroom — so tasks parked at
+            // capacity (which a completion event will pump) cannot spin here.
+            if (this.queue.length > 0 && !this.terminated && this.hasDispatchHeadroom()) {
+                this.pump();
+            }
+        });
+    }
+    hasDispatchHeadroom() {
+        if (this.workers.some((rec) => rec.task === null))
+            return true;
+        return this.sizeSync > 0 && this.workers.length < this.sizeSync;
+    }
+    async runPump() {
+        while (!this.terminated && this.queue.length > 0) {
+            const idle = this.workers.find((rec) => rec.task === null);
+            if (idle !== undefined) {
+                this.dispatch(idle, this.queue.shift());
+                continue;
+            }
+            if (this.workers.length < (await this.resolveSize())) {
+                let rec;
+                try {
+                    rec = await this.spawnWorker();
+                }
+                catch (error) {
+                    // Spawning failed (missing entry, bad workerPath, …): fail THIS
+                    // task and keep trying for the rest of the queue.
+                    this.queue.shift()?.reject(error);
+                    continue;
+                }
+                continue; // the fresh thread is idle → dispatched on the next pass
+            }
+            break; // at capacity with every thread busy — wait for a response
+        }
+    }
+    async spawnWorker() {
+        // @vite-ignore: Node-only; never executed in a browser bundle.
+        const { Worker: WorkerCtor } = await import(
+        /* webpackIgnore: true */ /* @vite-ignore */ "node:worker_threads");
+        if (this.terminated)
+            throw new Cube4WorkerPoolClosedError("spawn");
+        const entry = this.resolveWorkerEntry();
+        const worker = new WorkerCtor(entry.path, { execArgv: [...entry.execArgv] });
+        const rec = { worker, task: null };
+        worker.on("message", (response) => {
+            this.handleResponse(rec, response);
+        });
+        worker.on("error", (error) => {
+            this.handleWorkerGone(rec, error);
+        });
+        worker.on("exit", (code) => {
+            this.handleWorkerGone(rec, new Error(`[cube4] worker exited unexpectedly (code ${code}).`));
+        });
+        this.workers.push(rec);
+        worker.unref(); // idle threads must not keep the process alive
+        return rec;
+    }
+    dispatch(rec, task) {
+        rec.task = task;
+        rec.worker.ref(); // an awaited job keeps the event loop alive
+        const message = { id: task.id, options: task.options };
+        try {
+            rec.worker.postMessage(message);
+        }
+        catch (error) {
+            // e.g. DataCloneError for non-cloneable options.metadata — the
+            // thread is fine; fail only this task.
+            rec.task = null;
+            rec.worker.unref();
+            task.reject(error);
+            this.pump();
+        }
+    }
+    handleResponse(rec, response) {
+        const task = rec.task;
+        if (task === null || task.id !== response.id)
+            return; // stale/unknown id
+        rec.task = null;
+        if (this.terminated)
+            return;
+        if (response.ok)
+            task.resolve(response.result);
+        else
+            task.reject(deserializeCube4Error(response.error));
+        const next = this.queue.shift();
+        if (next !== undefined)
+            this.dispatch(rec, next);
+        else
+            rec.worker.unref();
+        this.pump();
+    }
+    handleWorkerGone(rec, error) {
+        const index = this.workers.indexOf(rec);
+        if (index === -1)
+            return; // already removed ('error' precedes 'exit')
+        this.workers.splice(index, 1);
+        const task = rec.task;
+        rec.task = null;
+        if (task !== null && !this.terminated) {
+            // Only THIS thread's job fails; the rest of the queue keeps running
+            // (a replacement thread is spawned lazily by pump()).
+            task.reject(error);
+        }
+        if (!this.terminated)
+            this.pump();
+    }
+    resolveWorkerEntry() {
+        if (this.workerPathOption !== undefined) {
+            return {
+                path: this.workerPathOption,
+                execArgv: this.workerPathOption.endsWith(".ts") ? [...TSX_ARGV] : []
+            };
+        }
+        const hereRaw = resolveCurrentModuleLocation();
+        if (hereRaw === undefined) {
+            throw new Error("[cube4] cannot locate worker.ts/worker.js next to worker-pool.js; " +
+                "pass an explicit `workerPath` to Cube4WorkerPool.");
+        }
+        // Normalise Windows separators: forward slashes are valid in every
+        // Node path/URL consumer here (Worker entry, fs lookups by Node).
+        const here = hereRaw.replace(/\\/g, "/");
+        const separator = here.lastIndexOf("/");
+        const dir = separator === -1 ? "." : here.slice(0, separator);
+        if (here.endsWith(".ts")) {
+            // Running from source under tsx → the thread needs the tsx loader.
+            return { path: `${dir}/worker.ts`, execArgv: [...TSX_ARGV] };
+        }
+        const distCjs = dir.lastIndexOf("/dist-cjs");
+        if (distCjs !== -1) {
+            // The CJS build excludes the worker entry (it is Node-ESM-only); the
+            // ESM tree is always published alongside and always contains it.
+            const esmDir = `${dir.slice(0, distCjs)}/dist${dir.slice(distCjs + "/dist-cjs".length)}`;
+            return { path: `${esmDir}/worker.js`, execArgv: [] };
+        }
+        return { path: `${dir}/worker.js`, execArgv: [] };
+    }
+}
+// ── module-level conveniences ──────────────────────────────────────────
+let defaultPool;
+/** Shared lazily-created pool (used by `generateCube4ScrambleBatch`). */
+export function getDefaultCube4WorkerPool() {
+    defaultPool ??= new Cube4WorkerPool();
+    return defaultPool;
+}
+/** Terminates (and forgets) the shared pool — call on process shutdown. */
+export async function closeDefaultCube4WorkerPool() {
+    const pool = defaultPool;
+    defaultPool = undefined;
+    if (pool !== undefined)
+        await pool.terminate();
+}
+/**
+ * Batch convenience mirroring core `generateScrambles` for `444`:
+ *  - `count <= 1` runs INLINE in the caller (no thread spawn, no cold
+ *    start — a single scramble must never get slower);
+ *  - `count > 1` fans out over the shared pool (same seed derivation).
+ */
+export async function generateCube4ScrambleBatch(count, options = {}) {
+    if (!Number.isInteger(count) || count < 1) {
+        throw new InvalidCountError(count);
+    }
+    if (count === 1) {
+        return [await generateCube4Scramble(options)];
+    }
+    return getDefaultCube4WorkerPool().generateBatch(count, options);
+}

package/dist/puzzles/cube4/worker-protocol.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Message protocol shared by the 4x4 Node worker (`worker.ts`), its pool
+ * (`worker-pool.ts`), and the browser equivalents (`browser-worker.ts`,
+ * `browser-worker-pool.ts`).
+ *
+ * Design notes:
+ *  - Tasks carry the FULL `generateCube4Scramble` options object. The
+ *    scrambler is a pure function of (seed, complete options), so forwarding
+ *    every option verbatim is what makes the pool output bit-identical to
+ *    the inline path for the same inputs.
+ *  - Errors cross the thread boundary as data (`Cube4SerializedError`):
+ *    `name`, `message`, `code` and `stack` survive, so typed solver errors
+ *    (e.g. `Cube4TargetMismatchError` with `code: "cube4-target-mismatch"`)
+ *    remain discriminated on the consumer side by name/code — the same
+ *    classification keys `scrambler.ts` itself uses. Classes cannot be
+ *    structured-cloned, so `instanceof` does not cross the boundary
+ *    (documented contract).
+ *
+ * This module is deliberately free of runtime imports (type-only imports
+ * are erased at emit) so it can be bundled for the browser worker without
+ * dragging Node-only code into the graph.
+ */
+import type { ScrambleOptions, ScrambleResult } from "../../core/types.js";
+import type { Cube4ScrambleOptions } from "./scrambler.js";
+/** Complete options accepted by a worker task. */
+export type Cube4WorkerGenerationOptions = ScrambleOptions & Cube4ScrambleOptions;
+export interface Cube4WorkerTask {
+    id: number;
+    options: Cube4WorkerGenerationOptions;
+}
+export interface Cube4SerializedError {
+    name: string;
+    message: string;
+    /** Preserved when primitive (string | number); `undefined` otherwise. */
+    code?: string | number;
+    stack?: string;
+}
+export type Cube4WorkerResponse = {
+    id: number;
+    ok: true;
+    result: ScrambleResult;
+} | {
+    id: number;
+    ok: false;
+    error: Cube4SerializedError;
+};
+/**
+ * Flattens an unknown thrown value into the structured-clone-safe shape
+ * above. Non-Error values are stringified so nothing is lost silently.
+ */
+export declare function serializeCube4Error(error: unknown): Cube4SerializedError;
+/**
+ * Rebuilds an Error from the wire shape, restoring `name`, `code` and
+ * `stack` (stack kept only as a debugging aid — its file locations point
+ * into the worker thread).
+ */
+export declare function deserializeCube4Error(serialized: Cube4SerializedError): Error;
+//# sourceMappingURL=worker-protocol.d.ts.map

package/dist/puzzles/cube4/worker-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-protocol.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/worker-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,kDAAkD;AAClD,MAAM,MAAM,4BAA4B,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAElF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,4BAA4B,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAcxE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,oBAAoB,GAAG,KAAK,CAU7E"}