@cubingcenter/scrambler 0.7.0 → 0.8.0

package/dist-cjs/puzzles/cube3/solver/tables.js

@@ -16,6 +16,7 @@ const types_js_1 = require("../types.js");
 const coordinates_js_1 = require("./coordinates.js");
 const state_js_1 = require("../state.js");
 const generated_assets_js_1 = require("./generated-assets.js");
+const load_once_js_1 = require("../../shared/load-once.js");
 exports.CUBE3_PHASE1_MOVES = types_js_1.CUBE3_MOVES;
 exports.CUBE3_PHASE2_MOVES = [
     "U",
@@ -29,20 +30,21 @@ exports.CUBE3_PHASE2_MOVES = [
     "F2",
     "B2"
 ];
-let cachedTables;
-let cachedPhase1Tables;
-let cachedPhase2Tables;
-async function loadCube3SolverTables() {
-    cachedTables ??= await (0, generated_assets_js_1.loadGeneratedCube3SolverTables)();
-    return cachedTables;
+// Promise slots (shared helper, see shared/load-once.ts): concurrent cold
+// calls share ONE in-flight load instead of racing several loads and
+// clobbering each other's results; a rejection purges the slot so the next
+// call can retry.
+const solverTablesSlot = { promise: undefined };
+const phase1TablesSlot = { promise: undefined };
+const phase2TablesSlot = { promise: undefined };
+function loadCube3SolverTables() {
+    return (0, load_once_js_1.loadOnce)(solverTablesSlot, generated_assets_js_1.loadGeneratedCube3SolverTables);
 }
-async function loadCube3Phase1Tables() {
-    cachedPhase1Tables ??= await (0, generated_assets_js_1.loadGeneratedCube3Phase1Tables)();
-    return cachedPhase1Tables;
+function loadCube3Phase1Tables() {
+    return (0, load_once_js_1.loadOnce)(phase1TablesSlot, generated_assets_js_1.loadGeneratedCube3Phase1Tables);
 }
-async function loadCube3Phase2Tables() {
-    cachedPhase2Tables ??= await (0, generated_assets_js_1.loadGeneratedCube3Phase2Tables)();
-    return cachedPhase2Tables;
+function loadCube3Phase2Tables() {
+    return (0, load_once_js_1.loadOnce)(phase2TablesSlot, generated_assets_js_1.loadGeneratedCube3Phase2Tables);
 }
 function generateCube3Phase1Tables() {
     const cornerOrientation = generateCube3MoveTable("cornerOrientation", coordinates_js_1.CUBE3_COORDINATE_RANGES.cornerOrientation, exports.CUBE3_PHASE1_MOVES);

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

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Web Worker pool for 4x4 random-state scrambles — the browser counterpart
+ * of `worker-pool.ts` with the same protocol, lazy-spawn lifecycle, FIFO
+ * queue, typed error propagation and per-thread table reuse.
+ *
+ * Unlike the Node pool (which locates its own worker file), the browser
+ * pool REQUIRES the caller to pass `workerUrl`, because only the caller's
+ * file can host the static `new URL("./browser-worker.js", import.meta.url)`
+ * expression that bundlers (Vite, Webpack 5, Parcel) statically analyse to
+ * emit a separate worker chunk:
+ *
+ * ```ts
+ * const pool = new Cube4BrowserWorkerPool({
+ *   workerUrl: new URL("./browser-worker.js", import.meta.url)
+ * });
+ * const batch = await pool.generateBatch(8, { seed: "demo" });
+ * await pool.terminate();
+ * ```
+ *
+ * This file contains no `import.meta` and no static Node imports, so it
+ * also compiles in the CommonJS build (unlike a hard-coded
+ * `new URL(..., import.meta.url)` default).
+ *
+ * Errors crossing the worker boundary arrive as `Error` instances with the
+ * original `name`, `message` and `code` preserved (`worker-protocol.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cube4BrowserWorkerPool = exports.Cube4BrowserWorkerPoolClosedError = void 0;
+exports.deriveBrowserBatchCube4Options = deriveBrowserBatchCube4Options;
+const worker_protocol_js_1 = require("./worker-protocol.js");
+/** Typed rejection used for post-terminate operations and shutdown itself. */
+class Cube4BrowserWorkerPoolClosedError extends Error {
+    code = "cube4-browser-pool-closed";
+    constructor(action = "operation") {
+        super(`[cube4] browser worker pool is closed (${action} rejected).`);
+        this.name = "Cube4BrowserWorkerPoolClosedError";
+    }
+}
+exports.Cube4BrowserWorkerPoolClosedError = Cube4BrowserWorkerPoolClosedError;
+/**
+ * Batch seed derivation — identical to core `generateScrambles` and to
+ * `deriveBatchCube4Options` in the Node pool.
+ */
+function deriveBrowserBatchCube4Options(options, index, count) {
+    if (count === 1 || options.seed === undefined) {
+        return options;
+    }
+    return { ...options, seed: `${options.seed}:${index}` };
+}
+function defaultBrowserSize() {
+    if (typeof navigator !== "undefined" && navigator.hardwareConcurrency) {
+        return Math.max(1, navigator.hardwareConcurrency - 1);
+    }
+    return 4;
+}
+class Cube4BrowserWorkerPool {
+    workers = [];
+    queue = [];
+    workerUrl;
+    maxSize;
+    pumping = false;
+    terminatePromise;
+    nextId = 0;
+    terminated = false;
+    constructor(options) {
+        if (typeof Worker === "undefined") {
+            throw new Error("[cube4] Web Workers are not available in this environment; " +
+                "use generateCube4Scramble() directly for single-threaded generation.");
+        }
+        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.workerUrl =
+            typeof options.workerUrl === "string" ? options.workerUrl : options.workerUrl.href;
+        this.maxSize = options.size ?? defaultBrowserSize();
+    }
+    /** 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;
+    }
+    generate(options = {}) {
+        if (this.terminated) {
+            return Promise.reject(new Cube4BrowserWorkerPoolClosedError("generate"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.queue.push({ id, options, resolve, reject });
+            this.pump();
+        });
+    }
+    generateBatch(count, options = {}) {
+        if (!Number.isInteger(count) || count < 1) {
+            return Promise.reject(new RangeError(`count must be a positive integer (got ${count}).`));
+        }
+        return Promise.all(Array.from({ length: count }, (_, index) => this.generate(deriveBrowserBatchCube4Options(options, index, count))));
+    }
+    /**
+     * Prompt shutdown: rejects queued/in-flight tasks and terminates every
+     * Web Worker synchronously (no threads to join in the browser).
+     * Idempotent.
+     */
+    terminate() {
+        if (this.terminatePromise !== undefined)
+            return;
+        this.terminated = true;
+        const closed = () => new Cube4BrowserWorkerPoolClosedError();
+        for (const task of this.queue.splice(0))
+            task.reject(closed());
+        const records = this.workers.splice(0);
+        for (const rec of records) {
+            if (rec.task !== null) {
+                rec.task.reject(closed());
+                rec.task = null;
+            }
+            rec.worker.terminate();
+        }
+        this.terminatePromise = Promise.resolve();
+    }
+    // ── internals (same shape as the Node pool) ──────────────────────────
+    pump() {
+        if (this.pumping || this.terminated)
+            return;
+        this.pumping = true;
+        void this.runPump()
+            .catch(() => undefined)
+            .finally(() => {
+            this.pumping = false;
+        });
+    }
+    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 < this.maxSize) {
+                this.spawnWorker();
+                continue;
+            }
+            break;
+        }
+    }
+    spawnWorker() {
+        const worker = new Worker(this.workerUrl, { type: "module", name: "cubingcenter-444" });
+        const rec = { worker, task: null };
+        worker.onmessage = (event) => {
+            this.handleResponse(rec, event.data);
+        };
+        worker.onerror = (event) => {
+            this.handleWorkerGone(rec, event.error instanceof Error
+                ? event.error
+                : new Error(event.message || "[cube4] browser worker failed."));
+        };
+        this.workers.push(rec);
+        return rec;
+    }
+    dispatch(rec, task) {
+        rec.task = task;
+        const message = { id: task.id, options: task.options };
+        try {
+            rec.worker.postMessage(message);
+        }
+        catch (error) {
+            rec.task = null;
+            task.reject(error);
+            this.pump();
+        }
+    }
+    handleResponse(rec, response) {
+        const task = rec.task;
+        if (task === null || task.id !== response.id)
+            return;
+        rec.task = null;
+        if (this.terminated)
+            return;
+        if (response.ok)
+            task.resolve(response.result);
+        else
+            task.reject((0, worker_protocol_js_1.deserializeCube4Error)(response.error));
+        const next = this.queue.shift();
+        if (next !== undefined)
+            this.dispatch(rec, next);
+        this.pump();
+    }
+    handleWorkerGone(rec, error) {
+        const index = this.workers.indexOf(rec);
+        if (index === -1)
+            return;
+        this.workers.splice(index, 1);
+        const task = rec.task;
+        rec.task = null;
+        if (task !== null && !this.terminated)
+            task.reject(error);
+        if (!this.terminated)
+            this.pump();
+    }
+}
+exports.Cube4BrowserWorkerPool = Cube4BrowserWorkerPool;

package/dist-cjs/puzzles/cube4/index.js

@@ -3,7 +3,8 @@
 // cube4 barrel exports
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initializeScrambler = exports.getSupportedEvents = exports.getEventInfo = exports.generateScrambles = exports.generateScramble = exports.getCube4FaceOrder = exports.formatCube4Facelets = exports.toCube4Facelets = exports.isAllowedRandomCube4State = exports.isTrivialCube4State = exports.isOneMoveFromSolvedCube4State = exports.validateCube4State = exports.generateRandomCube4State = exports.FACE_MOVE_EFFECTS = exports.parseMove = exports.parseCube4Move = exports.parseCube4Algorithm = exports.formatCube4Algorithm = exports.simplifyCube4Algorithm = exports.invertCube4Algorithm = exports.invertCube4Move = exports.applyCube4Algorithm = exports.applyCube4Move = exports.generateCube4Attempt = exports.generateCube4Scramble = exports.cube4ScrambleGenerator = exports.areWingsPaired = exports.areCentersReduced = exports.isSolvedCube4State = exports.cube4StatesEqual = exports.cloneCube4State = exports.createSolvedCube4State = exports.CUBE4_OUTER_MOVES = exports.CUBE4_ALL_MOVES = exports.CUBE4_FACE_MOVES = exports.B = exports.L = exports.D = exports.F = exports.R = exports.U = exports.CENTERS_PER_FACE = exports.FACE_COUNT = exports.CENTER_COUNT = exports.WING_COUNT = exports.CORNER_COUNT = void 0;
+exports.validateCube4State = exports.generateRandomCube4State = exports.FACE_MOVE_EFFECTS = exports.parseMove = exports.parseCube4Move = exports.parseCube4Algorithm = exports.formatCube4Algorithm = exports.simplifyCube4Algorithm = exports.invertCube4Algorithm = exports.invertCube4Move = exports.applyCube4Algorithm = exports.applyCube4Move = exports.deriveCube4StreamOptions = exports.createCube4ScrambleCache = exports.Cube4ScrambleCache = exports.deriveBrowserBatchCube4Options = exports.Cube4BrowserWorkerPoolClosedError = exports.Cube4BrowserWorkerPool = exports.closeDefaultCube4WorkerPool = exports.getDefaultCube4WorkerPool = exports.generateCube4ScrambleBatch = exports.deriveBatchCube4Options = exports.Cube4WorkerPoolClosedError = exports.Cube4WorkerPool = exports.generateCube4Attempt = exports.generateCube4Scramble = exports.cube4ScrambleGenerator = exports.Cube4Phase3CapError = exports.Cube4Phase2CapError = exports.Cube4FinishCapError = exports.areWingsPaired = exports.areCentersReduced = exports.isSolvedCube4State = exports.cube4StatesEqual = exports.cloneCube4State = exports.createSolvedCube4State = exports.CUBE4_OUTER_MOVES = exports.CUBE4_ALL_MOVES = exports.CUBE4_FACE_MOVES = exports.B = exports.L = exports.D = exports.F = exports.R = exports.U = exports.CENTERS_PER_FACE = exports.FACE_COUNT = exports.CENTER_COUNT = exports.WING_COUNT = exports.CORNER_COUNT = void 0;
+exports.initializeScrambler = exports.getSupportedEvents = exports.getEventInfo = exports.generateScrambles = exports.generateScramble = exports.getCube4FaceOrder = exports.formatCube4Facelets = exports.toCube4Facelets = exports.isAllowedRandomCube4State = exports.isTrivialCube4State = exports.isOneMoveFromSolvedCube4State = void 0;
 const index_js_1 = require("../../core/index.js");
 const scrambler_js_1 = require("./scrambler.js");
 (0, index_js_1.registerScrambleGenerator)(scrambler_js_1.cube4ScrambleGenerator);
@@ -29,10 +30,29 @@ Object.defineProperty(exports, "cube4StatesEqual", { enumerable: true, get: func
 Object.defineProperty(exports, "isSolvedCube4State", { enumerable: true, get: function () { return state_js_1.isSolvedCube4State; } });
 Object.defineProperty(exports, "areCentersReduced", { enumerable: true, get: function () { return state_js_1.areCentersReduced; } });
 Object.defineProperty(exports, "areWingsPaired", { enumerable: true, get: function () { return state_js_1.areWingsPaired; } });
+var solve_js_1 = require("./reduction/solve.js");
+Object.defineProperty(exports, "Cube4FinishCapError", { enumerable: true, get: function () { return solve_js_1.Cube4FinishCapError; } });
+Object.defineProperty(exports, "Cube4Phase2CapError", { enumerable: true, get: function () { return solve_js_1.Cube4Phase2CapError; } });
+Object.defineProperty(exports, "Cube4Phase3CapError", { enumerable: true, get: function () { return solve_js_1.Cube4Phase3CapError; } });
 var scrambler_js_2 = require("./scrambler.js");
 Object.defineProperty(exports, "cube4ScrambleGenerator", { enumerable: true, get: function () { return scrambler_js_2.cube4ScrambleGenerator; } });
 Object.defineProperty(exports, "generateCube4Scramble", { enumerable: true, get: function () { return scrambler_js_2.generateCube4Scramble; } });
 Object.defineProperty(exports, "generateCube4Attempt", { enumerable: true, get: function () { return scrambler_js_2.generateCube4Attempt; } });
+var worker_pool_js_1 = require("./worker-pool.js");
+Object.defineProperty(exports, "Cube4WorkerPool", { enumerable: true, get: function () { return worker_pool_js_1.Cube4WorkerPool; } });
+Object.defineProperty(exports, "Cube4WorkerPoolClosedError", { enumerable: true, get: function () { return worker_pool_js_1.Cube4WorkerPoolClosedError; } });
+Object.defineProperty(exports, "deriveBatchCube4Options", { enumerable: true, get: function () { return worker_pool_js_1.deriveBatchCube4Options; } });
+Object.defineProperty(exports, "generateCube4ScrambleBatch", { enumerable: true, get: function () { return worker_pool_js_1.generateCube4ScrambleBatch; } });
+Object.defineProperty(exports, "getDefaultCube4WorkerPool", { enumerable: true, get: function () { return worker_pool_js_1.getDefaultCube4WorkerPool; } });
+Object.defineProperty(exports, "closeDefaultCube4WorkerPool", { enumerable: true, get: function () { return worker_pool_js_1.closeDefaultCube4WorkerPool; } });
+var browser_worker_pool_js_1 = require("./browser-worker-pool.js");
+Object.defineProperty(exports, "Cube4BrowserWorkerPool", { enumerable: true, get: function () { return browser_worker_pool_js_1.Cube4BrowserWorkerPool; } });
+Object.defineProperty(exports, "Cube4BrowserWorkerPoolClosedError", { enumerable: true, get: function () { return browser_worker_pool_js_1.Cube4BrowserWorkerPoolClosedError; } });
+Object.defineProperty(exports, "deriveBrowserBatchCube4Options", { enumerable: true, get: function () { return browser_worker_pool_js_1.deriveBrowserBatchCube4Options; } });
+var scramble_cache_js_1 = require("./scramble-cache.js");
+Object.defineProperty(exports, "Cube4ScrambleCache", { enumerable: true, get: function () { return scramble_cache_js_1.Cube4ScrambleCache; } });
+Object.defineProperty(exports, "createCube4ScrambleCache", { enumerable: true, get: function () { return scramble_cache_js_1.createCube4ScrambleCache; } });
+Object.defineProperty(exports, "deriveCube4StreamOptions", { enumerable: true, get: function () { return scramble_cache_js_1.deriveCube4StreamOptions; } });
 var moves_js_1 = require("./moves.js");
 Object.defineProperty(exports, "applyCube4Move", { enumerable: true, get: function () { return moves_js_1.applyCube4Move; } });
 Object.defineProperty(exports, "applyCube4Algorithm", { enumerable: true, get: function () { return moves_js_1.applyCube4Algorithm; } });

package/dist-cjs/puzzles/cube4/moves.js

@@ -319,43 +319,135 @@ function parse4Move(m) {
         (base[0] === "R" || base[0] === "L") ? 1 : 2;
     return { base, axis, amount };
 }
-function format4Move(base, amount) {
-    const amt = ((amount % 4) + 4) % 4;
-    if (amt === 0)
-        return null;
-    const suffix = amt === 1 ? "" : amt === 2 ? "2" : "'";
-    return (base + suffix);
+const AXIS_FACES = [
+    ["U", "D"],
+    ["R", "L"],
+    ["F", "B"]
+];
+const AXIS_TURN_OPTIONS = [
+    ["2", 2],
+    ["", 1],
+    ["'", 3]
+];
+function axisVectorKey(vector) {
+    return vector[0] | (vector[1] << 2) | (vector[2] << 4) | (vector[3] << 6);
 }
-function movesCommute4(a, b) {
-    return a.axis === b.axis && a.base !== b.base;
+function applyMoveToAxisVector(vector, base, turns, out) {
+    out[0] = vector[0];
+    out[1] = vector[1];
+    out[2] = vector[2];
+    out[3] = vector[3];
+    const axis = base[0];
+    const [positive, negative] = AXIS_FACES.find(([p, n]) => p === axis || n === axis);
+    const isPositive = axis === positive;
+    const signedTurns = isPositive ? turns : 4 - turns;
+    const wide = base.endsWith("w");
+    if (wide) {
+        const firstLayer = isPositive ? 0 : 2;
+        out[firstLayer] = (out[firstLayer] + signedTurns) & 3;
+        out[firstLayer + 1] = (out[firstLayer + 1] + signedTurns) & 3;
+    }
+    else {
+        const layer = isPositive ? 0 : 3;
+        out[layer] = (out[layer] + signedTurns) & 3;
+    }
+}
+function buildAxisReductionTable(positiveFace, negativeFace) {
+    const bases = [positiveFace, negativeFace, `${positiveFace}w`, `${negativeFace}w`];
+    const paths = new Array(256);
+    const queue = new Uint8Array(256);
+    let head = 0;
+    let tail = 0;
+    paths[0] = [];
+    queue[tail++] = 0;
+    while (head < tail) {
+        const key = queue[head++];
+        const vector = [key & 3, (key >> 2) & 3, (key >> 4) & 3, (key >> 6) & 3];
+        const prefix = paths[key];
+        for (const base of bases) {
+            for (const [suffix, turns] of AXIS_TURN_OPTIONS) {
+                const nextVector = [0, 0, 0, 0];
+                applyMoveToAxisVector(vector, base, turns, nextVector);
+                const nextKey = axisVectorKey(nextVector);
+                if (paths[nextKey] !== undefined)
+                    continue;
+                paths[nextKey] = [...prefix, `${base}${suffix}`];
+                queue[tail++] = nextKey;
+            }
+        }
+    }
+    if (tail !== 256 || paths.some((path) => path === undefined)) {
+        throw new Error(`4x4 move simplifier: incomplete axis table for ${positiveFace}/${negativeFace}.`);
+    }
+    return paths;
+}
+const AXIS_REDUCTIONS = AXIS_FACES.map(([positive, negative]) => buildAxisReductionTable(positive, negative));
+function encodeAxisRun(moves, axis) {
+    const vector = [0, 0, 0, 0];
+    const next = [0, 0, 0, 0];
+    for (const move of moves) {
+        if (move.axis === axis) {
+            applyMoveToAxisVector(vector, move.base, move.amount, next);
+            vector[0] = next[0];
+            vector[1] = next[1];
+            vector[2] = next[2];
+            vector[3] = next[3];
+        }
+    }
+    return axisVectorKey(vector);
+}
+function addAxisKeys(a, b) {
+    let result = 0;
+    for (let layer = 0; layer < 4; layer++) {
+        const shift = layer * 2;
+        const amount = (((a >> shift) & 3) + ((b >> shift) & 3)) & 3;
+        result |= amount << shift;
+    }
+    return result;
 }
 /**
  * Simplifies a 4x4 algorithm by canceling inverse moves and merging redundant
  * turns on the same face or across commuting parallel faces.
  */
 function simplifyCube4Algorithm(moves) {
-    // Single left-to-right pass with an output stack: each move merges with
-    // the nearest same-base entry across trailing commuting parallel-face
-    // moves (verified equivalent to the old restart-from-zero loop on 20000
-    // random algorithms). O(n·window) instead of O(n²) restarts with splices.
-    const out = [];
-    for (const move of moves) {
-        const current = parse4Move(move);
-        let index = out.length - 1;
-        while (index >= 0 && movesCommute4(out[index], current))
-            index--;
-        if (index >= 0 && out[index].base === current.base) {
-            const merged = (out[index].amount + current.amount) % 4;
-            if (merged === 0)
-                out.splice(index, 1);
-            else
-                out[index].amount = merged;
-        }
-        else {
-            out.push(current);
+    // Moves on parallel layers commute, and each maximal same-axis run is a
+    // four-coordinate vector of quarter turns (one coordinate per layer).
+    // A small exact shortest-path table maps that vector back to the fewest
+    // legal face/wide moves, including mixed identities such as Rw R' = the
+    // corresponding inner-slice turn. Different axes are never reordered.
+    const segments = [];
+    let run = [];
+    let runAxis = -1;
+    const flushRun = () => {
+        if (run.length === 0)
+            return;
+        const key = encodeAxisRun(run, runAxis);
+        if (key !== 0) {
+            const previous = segments[segments.length - 1];
+            if (previous?.axis === runAxis) {
+                const mergedKey = addAxisKeys(previous.key, key);
+                if (mergedKey === 0)
+                    segments.pop();
+                else {
+                    previous.key = mergedKey;
+                    previous.moves = AXIS_REDUCTIONS[runAxis][mergedKey];
+                }
+            }
+            else {
+                segments.push({ axis: runAxis, key, moves: AXIS_REDUCTIONS[runAxis][key] });
+            }
         }
+        run = [];
+        runAxis = -1;
+    };
+    for (const move of moves) {
+        const parsed = parse4Move(move);
+        if (runAxis !== -1 && parsed.axis !== runAxis)
+            flushRun();
+        if (runAxis === -1)
+            runAxis = parsed.axis;
+        run.push(parsed);
     }
-    return out
-        .map((p) => format4Move(p.base, p.amount))
-        .filter((m) => m !== null);
+    flushRun();
+    return segments.flatMap((segment) => segment.moves);
 }