@cubingcenter/scrambler 0.6.3 → 0.8.0

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.invertCube4Algorithm = exports.invertCube4Move = exports.applyCube4Algorithm = exports.applyCube4Move = 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,14 +30,35 @@ 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; } });
 Object.defineProperty(exports, "invertCube4Move", { enumerable: true, get: function () { return moves_js_1.invertCube4Move; } });
 Object.defineProperty(exports, "invertCube4Algorithm", { enumerable: true, get: function () { return moves_js_1.invertCube4Algorithm; } });
+Object.defineProperty(exports, "simplifyCube4Algorithm", { enumerable: true, get: function () { return moves_js_1.simplifyCube4Algorithm; } });
 Object.defineProperty(exports, "formatCube4Algorithm", { enumerable: true, get: function () { return moves_js_1.formatCube4Algorithm; } });
 Object.defineProperty(exports, "parseCube4Algorithm", { enumerable: true, get: function () { return moves_js_1.parseCube4Algorithm; } });
 Object.defineProperty(exports, "parseCube4Move", { enumerable: true, get: function () { return moves_js_1.parseCube4Move; } });

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

@@ -20,6 +20,7 @@ exports.invertCube4Algorithm = invertCube4Algorithm;
 exports.formatCube4Algorithm = formatCube4Algorithm;
 exports.parseCube4Algorithm = parseCube4Algorithm;
 exports.parseCube4Move = parseCube4Move;
+exports.simplifyCube4Algorithm = simplifyCube4Algorithm;
 const types_js_1 = require("./types.js");
 // ---------------------------------------------------------------------------
 // Identity arrays
@@ -170,6 +171,32 @@ const FACE_MOVE_EFFECTS = {
 };
 exports.FACE_MOVE_EFFECTS = FACE_MOVE_EFFECTS;
 // ---------------------------------------------------------------------------
+// Precomposed total effect per move string ("R'" = R x3, "U2" = U x2),
+// built once at module load. applyCube4Algorithm then costs one lookup +
+// one pass per move: no per-move string parsing, no repeated
+// quarter-turn passes (average ~2 passes collapse into exactly 1).
+// ---------------------------------------------------------------------------
+function composePower(face, turns) {
+    const quarter = FACE_MOVE_EFFECTS[face];
+    if (turns === 2)
+        return composeEffects(quarter, quarter);
+    if (turns === 3)
+        return composeEffects(composeEffects(quarter, quarter), quarter);
+    return quarter;
+}
+const COMPOSED_EFFECTS = Object.fromEntries(types_js_1.CUBE4_ALL_MOVES.map((move) => {
+    const { face, turns } = parseMove(move);
+    return [move, composePower(face, turns)];
+}));
+/** Total effect for one move string (precomposed fast path + parse fallback). */
+function effectForMove(move) {
+    const hit = COMPOSED_EFFECTS[move];
+    if (hit !== undefined)
+        return hit;
+    const { face, turns } = parseMove(move);
+    return composePower(face, turns);
+}
+// ---------------------------------------------------------------------------
 // Apply a single move to a state
 // ---------------------------------------------------------------------------
 function applyEffect(state, effect) {
@@ -204,20 +231,52 @@ function parseMove(move) {
     return { face: face, suffix, turns };
 }
 function applyCube4Move(state, move) {
-    const { face, turns } = parseMove(move);
-    const effect = FACE_MOVE_EFFECTS[face];
-    let current = state;
-    for (let i = 0; i < turns; i++) {
-        current = applyEffect(current, effect);
-    }
-    return current;
+    // Single-pass fast path through the precomposed total effect: one lookup
+    // + one pass, no string re-parsing, no repeated quarter-turn passes, no
+    // intermediate states.
+    return applyEffect(state, effectForMove(move));
 }
 function applyCube4Algorithm(state, moves) {
-    let current = state;
-    for (const move of moves) {
-        current = applyCube4Move(current, move);
+    if (moves.length === 0)
+        return state;
+    const bufA = {
+        cp: new Uint8Array(state.cp),
+        co: new Uint8Array(state.co),
+        wp: new Uint8Array(state.wp),
+        centers: new Uint8Array(state.centers)
+    };
+    const bufB = {
+        cp: new Uint8Array(8),
+        co: new Uint8Array(8),
+        wp: new Uint8Array(24),
+        centers: new Uint8Array(24)
+    };
+    let cur = bufA;
+    let nxt = bufB;
+    for (let mIdx = 0; mIdx < moves.length; mIdx++) {
+        const move = moves[mIdx];
+        const eff = effectForMove(move);
+        for (let i = 0; i < 8; i++) {
+            const from = eff.cperm[i];
+            nxt.cp[i] = cur.cp[from];
+            nxt.co[i] = (cur.co[from] + eff.corient[i]) % 3;
+        }
+        for (let i = 0; i < 24; i++) {
+            nxt.wp[i] = cur.wp[eff.wperm[i]];
+        }
+        for (let i = 0; i < 24; i++) {
+            nxt.centers[i] = cur.centers[eff.ctperm[i]];
+        }
+        const tmp = cur;
+        cur = nxt;
+        nxt = tmp;
     }
-    return current;
+    return {
+        cp: cur.cp,
+        co: cur.co,
+        wp: cur.wp,
+        centers: cur.centers
+    };
 }
 // ---------------------------------------------------------------------------
 // Move inversion
@@ -249,3 +308,146 @@ function parseCube4Move(value) {
     }
     throw new Error(`Invalid 4x4 move: ${value}`);
 }
+function parse4Move(m) {
+    const match = m.match(/^([UDFBLR]w?)(2|')?$/);
+    if (!match)
+        throw new Error(`Invalid move format: ${m}`);
+    const base = match[1];
+    const suffix = match[2] ?? "";
+    const amount = suffix === "2" ? 2 : suffix === "'" ? 3 : 1;
+    const axis = (base[0] === "U" || base[0] === "D") ? 0 :
+        (base[0] === "R" || base[0] === "L") ? 1 : 2;
+    return { base, axis, amount };
+}
+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 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) {
+    // 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);
+    }
+    flushRun();
+    return segments.flatMap((segment) => segment.moves);
+}