@cubingcenter/scrambler 0.7.0 → 0.8.0

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"}

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

@@ -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.
+ */
+/**
+ * Flattens an unknown thrown value into the structured-clone-safe shape
+ * above. Non-Error values are stringified so nothing is lost silently.
+ */
+export function serializeCube4Error(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        const primitiveCode = typeof code === "string" || typeof code === "number" ? code : undefined;
+        const serialized = {
+            name: error.name,
+            message: error.message
+        };
+        if (primitiveCode !== undefined)
+            serialized.code = primitiveCode;
+        if (typeof error.stack === "string")
+            serialized.stack = error.stack;
+        return serialized;
+    }
+    return { name: "Error", message: String(error) };
+}
+/**
+ * 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 function deserializeCube4Error(serialized) {
+    const error = new Error(serialized.message);
+    error.name = serialized.name;
+    if (serialized.code !== undefined) {
+        error.code = serialized.code;
+    }
+    if (serialized.stack !== undefined) {
+        error.stack = serialized.stack;
+    }
+    return error;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Node.js worker_thread entry for 4x4 scramble generation.
+ *
+ * Lifecycle / lazy init: the thread boots without doing any work; the
+ * reduction + 3x3 tables (≈37 MB) are loaded on the FIRST task and then
+ * reused for every later task, because `scrambler.ts` deduplicates table
+ * loads per thread via its promise cache. Spawning is driven lazily by
+ * `worker-pool.ts` (one thread per queued job, up to the pool size), so a
+ * small batch never pays for idle threads.
+ *
+ * Protocol: see `worker-protocol.ts`. One task in flight per thread (the
+ * pool only re-dispatches after a response), but the handler is written to
+ * cope with concurrent messages just in case.
+ *
+ * Source-vs-dist loading: this file is excluded from the CommonJS build,
+ * so `import.meta` is safe here. When running from source the thread is
+ * booted with `execArgv: ["--import", "tsx"]` by the pool, but that flag
+ * alone does NOT register tsx's resolve hooks inside a worker thread
+ * (measured: `./x.js` → `./x.ts` mapping missing). Therefore, before any
+ * value import of the repo's `.js`-suffixed specifiers, we register the
+ * tsx hooks explicitly — `tsx/esm/api` resolves because source mode only
+ * happens inside a checkout with node_modules. From `dist/` no tsx is
+ * involved: the `.js` files are real.
+ */
+export {};
+//# sourceMappingURL=worker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/puzzles/cube4/worker.js

@@ -0,0 +1,49 @@
+/**
+ * Node.js worker_thread entry for 4x4 scramble generation.
+ *
+ * Lifecycle / lazy init: the thread boots without doing any work; the
+ * reduction + 3x3 tables (≈37 MB) are loaded on the FIRST task and then
+ * reused for every later task, because `scrambler.ts` deduplicates table
+ * loads per thread via its promise cache. Spawning is driven lazily by
+ * `worker-pool.ts` (one thread per queued job, up to the pool size), so a
+ * small batch never pays for idle threads.
+ *
+ * Protocol: see `worker-protocol.ts`. One task in flight per thread (the
+ * pool only re-dispatches after a response), but the handler is written to
+ * cope with concurrent messages just in case.
+ *
+ * Source-vs-dist loading: this file is excluded from the CommonJS build,
+ * so `import.meta` is safe here. When running from source the thread is
+ * booted with `execArgv: ["--import", "tsx"]` by the pool, but that flag
+ * alone does NOT register tsx's resolve hooks inside a worker thread
+ * (measured: `./x.js` → `./x.ts` mapping missing). Therefore, before any
+ * value import of the repo's `.js`-suffixed specifiers, we register the
+ * tsx hooks explicitly — `tsx/esm/api` resolves because source mode only
+ * happens inside a checkout with node_modules. From `dist/` no tsx is
+ * involved: the `.js` files are real.
+ */
+import { parentPort } from "node:worker_threads";
+if (!parentPort) {
+    throw new Error("[cube4] worker.ts must be started as a worker_thread (use Cube4WorkerPool).");
+}
+const port = parentPort;
+if (import.meta.url.endsWith(".ts")) {
+    const tsxApi = await import("tsx/esm/api");
+    tsxApi.register();
+}
+const { generateCube4Scramble } = await import("./scrambler.js");
+const { serializeCube4Error } = await import("./worker-protocol.js");
+port.on("message", (task) => {
+    void (async () => {
+        const response = await (async () => {
+            try {
+                const result = await generateCube4Scramble(task.options);
+                return { id: task.id, ok: true, result };
+            }
+            catch (error) {
+                return { id: task.id, ok: false, error: serializeCube4Error(error) };
+            }
+        })();
+        port.postMessage(response);
+    })();
+});

package/dist/puzzles/pyraminx/solver/browser-loader.d.ts

@@ -1,14 +1,10 @@
-export declare function getCachedBrowserTables(): {
+export interface PyraminxBrowserTables {
     centersTable: Uint8Array;
     permutationTable: Uint16Array;
     orientationTable: Uint8Array;
     policyTable: Uint8Array;
-} | undefined;
+}
+export declare function getCachedBrowserTables(): PyraminxBrowserTables | undefined;
 export declare function clearCachedBrowserTables(): void;
-export declare function loadBrowserTables(baseUrl?: string): Promise<{
-    centersTable: Uint8Array;
-    permutationTable: Uint16Array;
-    orientationTable: Uint8Array;
-    policyTable: Uint8Array;
-}>;
+export declare function loadBrowserTables(baseUrl?: string): Promise<PyraminxBrowserTables>;
 //# sourceMappingURL=browser-loader.d.ts.map

package/dist/puzzles/pyraminx/solver/browser-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-loader.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/pyraminx/solver/browser-loader.ts"],"names":[],"mappings":"AAUA,wBAAgB,sBAAsB;kBANtB,UAAU;sBACN,WAAW;sBACX,UAAU;iBACf,UAAU;cAKxB;AACD,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACjE,YAAY,EAAE,UAAU,CAAC;IACzB,gBAAgB,EAAE,WAAW,CAAC;IAC9B,gBAAgB,EAAE,UAAU,CAAC;IAC7B,WAAW,EAAE,UAAU,CAAC;CACzB,CAAC,CAYD"}
+{"version":3,"file":"browser-loader.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/pyraminx/solver/browser-loader.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,UAAU,CAAC;IACzB,gBAAgB,EAAE,WAAW,CAAC;IAC9B,gBAAgB,EAAE,UAAU,CAAC;IAC7B,WAAW,EAAE,UAAU,CAAC;CACzB;AAKD,wBAAgB,sBAAsB,IAAI,qBAAqB,GAAG,SAAS,CAE1E;AAED,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C;AAED,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAkBxF"}