@cubingcenter/scrambler 0.6.3 → 0.8.0

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

@@ -13,6 +13,7 @@ const phase1_js_1 = require("./phase1.js");
 const tables_js_1 = require("./tables.js");
 const search_utils_js_1 = require("./search-utils.js");
 const pair_tables_js_1 = require("./pair-tables.js");
+const symmetry_js_1 = require("./symmetry.js");
 class Cube3Phase2SearchError extends Error {
     visitedNodes;
     constructor(message, visitedNodes) {
@@ -50,17 +51,11 @@ async function solveCube3Phase2(state, options = {}) {
         throw new Cube3Phase2SearchError("3x3 Phase 2 requires a state already in G1.", 0);
     }
     const tables = options.tables ?? await (0, tables_js_1.loadCube3Phase2Tables)();
-    const pairTables = options.pairTables ?? await (0, pair_tables_js_1.loadCube3PairTables)();
+    const pairTables = options.pairTables ?? (options.skipPairTables ? undefined : await (0, pair_tables_js_1.loadCube3PairTables)());
     const maxDepth = options.maxDepth ?? 18;
     const start = encodeCube3Phase2Coordinates(state);
     const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
-    const context = {
-        tables,
-        pairTables,
-        deadline,
-        visitedNodes: 0,
-        timedOut: false
-    };
+    const context = createPhase2SearchContext(tables, pairTables, maxDepth, deadline, options.maxNodes);
     const spRange = tables.moveTables.slicePermutation.range;
     const cpspTable = tables.pruningTables.cornerPermutationSlicePermutation.values;
     const epspTable = tables.pruningTables.udEdgePermutationSlicePermutation.values;
@@ -91,6 +86,9 @@ async function solveCube3Phase2(state, options = {}) {
                 visitedNodes: context.visitedNodes
             };
         }
+        if (context.nodesExceeded) {
+            throw new Cube3Phase2SearchError(`3x3 Phase 2 node budget exceeded (${options.maxNodes} nodes).`, context.visitedNodes);
+        }
         if (context.timedOut) {
             throw new Cube3Phase2SearchError(`3x3 Phase 2 search timed out after ${options.timeoutMs}ms.`, context.visitedNodes);
         }
@@ -98,6 +96,11 @@ async function solveCube3Phase2(state, options = {}) {
     throw new Cube3Phase2SearchError(`3x3 Phase 2 solution not found within depth ${maxDepth}.`, context.visitedNodes);
 }
 async function solveCube3State(state, options = {}) {
+    const quality = options.quality ?? "short";
+    const orientations = options.orientations ?? (quality === "best" ? 3 : 1);
+    if (orientations >= 3) {
+        return solveCube3TripleOrientation(state, { ...options, orientations });
+    }
     const phase1 = await (0, phase1_js_1.solveCube3Phase1)(state, options.phase1);
     let previousFace = -1;
     let previousPreviousFace = -1;
@@ -116,6 +119,154 @@ async function solveCube3State(state, options = {}) {
     };
     const phase2 = await solveCube3Phase2(phase1.state, phase2Options);
     const moves = [...phase1.moves, ...phase2.moves];
+    const targetLength = options.targetLength;
+    const extraDepth = options.phase1ExtraDepth ?? (quality === "fast" ? 0 : 1);
+    const solutionLimit = options.phase1SolutionLimit ?? (targetLength !== undefined ? 32 : 8);
+    const improveDepths = targetLength !== undefined ? Math.max(4, extraDepth) : extraDepth;
+    const needsTarget = targetLength !== undefined && moves.length > targetLength;
+    if (needsTarget || (targetLength === undefined && extraDepth > 0)) {
+        const p1Tables = options.phase1?.tables ?? await (0, tables_js_1.loadCube3Phase1Tables)();
+        const p2Tables = options.phase2?.tables ?? await (0, tables_js_1.loadCube3Phase2Tables)();
+        const scoredPairTables = options.phase2?.pairTables ??
+            (options.phase2?.skipPairTables ? undefined : await (0, pair_tables_js_1.loadCube3PairTables)());
+        // Work budget for the improvement loop. Preferred: `improveMaxNodes`
+        // (deterministic node counter — the wall deadline stays unarmed so the
+        // outcome cannot depend on CPU load/clock). Legacy: `timeoutMs ?? 800`
+        // wall deadline, kept for existing callers.
+        const nodeMode = options.improveMaxNodes !== undefined;
+        let remainingNodes = options.improveMaxNodes ?? 0;
+        const deadline = nodeMode ? undefined : performance.now() + (options.timeoutMs ?? 800);
+        const budgetExhausted = () => nodeMode ? remainingNodes <= 0 : performance.now() > deadline;
+        const spendNodes = (used) => {
+            if (nodeMode) {
+                remainingNodes = Math.max(0, remainingNodes - used);
+            }
+        };
+        const p2SpRange = p2Tables.moveTables.slicePermutation.range;
+        const p2cpsp = p2Tables.pruningTables.cornerPermutationSlicePermutation.values;
+        const p2uepsp = p2Tables.pruningTables.udEdgePermutationSlicePermutation.values;
+        const seenG1 = new Set();
+        let bestP1 = phase1;
+        let bestP2 = phase2;
+        let bestMoves = moves;
+        let improvementNodes = 0;
+        const minDepth = phase1.depth;
+        const scored = [];
+        for (let d = minDepth; d <= minDepth + improveDepths && d < bestMoves.length; d++) {
+            if (budgetExhausted())
+                break;
+            const { solutions: p1Solutions, visitedNodes } = await (0, phase1_js_1.collectCube3Phase1Solutions)(state, d, {
+                tables: p1Tables,
+                limit: solutionLimit,
+                ...(nodeMode
+                    ? { maxNodes: Math.max(1, remainingNodes) }
+                    : { timeoutMs: Math.max(1, deadline - performance.now()) })
+            });
+            improvementNodes += visitedNodes;
+            spendNodes(visitedNodes);
+            if (budgetExhausted())
+                break;
+            for (const p1Moves of p1Solutions) {
+                if (budgetExhausted())
+                    break;
+                if (p1Moves.length >= bestMoves.length)
+                    continue;
+                // Skip the phase-1 solution the initial search already completed.
+                if (p1Moves.length === phase1.moves.length &&
+                    p1Moves.every((move, index) => move === phase1.moves[index])) {
+                    continue;
+                }
+                const s1 = (0, moves_js_1.applyCube3Algorithm)(state, p1Moves);
+                const coords = encodeCube3Phase2Coordinates(s1);
+                const estKey = `${coords.cornerPermutation},${coords.udEdgePermutation},${coords.slicePermutation}`;
+                if (seenG1.has(estKey))
+                    continue;
+                seenG1.add(estKey);
+                const cpIndex = coords.cornerPermutation * p2SpRange + coords.slicePermutation;
+                const epIndex = coords.udEdgePermutation * p2SpRange + coords.slicePermutation;
+                const cpDist = (p2cpsp[cpIndex >> 1] >> ((cpIndex & 1) << 2)) & 0x0f;
+                const epDist = (p2uepsp[epIndex >> 1] >> ((epIndex & 1) << 2)) & 0x0f;
+                let est = p1Moves.length + (cpDist > epDist ? cpDist : epDist);
+                if (scoredPairTables !== undefined) {
+                    const pair = (0, pair_tables_js_1.pairBound)(scoredPairTables, coords.cornerPermutation, coords.udEdgePermutation);
+                    const pairEst = p1Moves.length + pair;
+                    if (pairEst > est)
+                        est = pairEst;
+                }
+                // A lower bound at or above the best total can never strictly improve it.
+                if (est >= bestMoves.length)
+                    continue;
+                const pFace = p1Moves.length > 0 ? (0, search_utils_js_1.getMoveFace)(p1Moves[p1Moves.length - 1]) : -1;
+                const ppFace = p1Moves.length > 1 ? (0, search_utils_js_1.getMoveFace)(p1Moves[p1Moves.length - 2]) : -1;
+                scored.push({ moves: p1Moves, state: s1, est, pFace, ppFace });
+            }
+        }
+        // Sort ALL candidates globally across depths by admissible total lower bound
+        scored.sort((left, right) => left.est - right.est);
+        for (const cand of scored) {
+            if (budgetExhausted())
+                break;
+            // Prune: since candidates are sorted by est, no subsequent candidate can beat bestMoves.length
+            if (cand.est >= bestMoves.length)
+                break;
+            const maxP2 = Math.min(bestMoves.length - cand.moves.length - 1, 15);
+            if (maxP2 <= 0)
+                continue;
+            try {
+                // Strip any legacy wall `timeoutMs` from the spread: in node mode
+                // the wall deadline must not be armed at all (pure function of
+                // budgets); in wall mode the per-candidate cap below re-adds it.
+                const phase2Source = options.phase2 ?? {};
+                const { timeoutMs: legacyPhase2Wall, ...phase2CandidateBase } = phase2Source;
+                // Per-candidate budget: node cap (deterministic) when the loop runs
+                // on `improveMaxNodes`, else the legacy wall cap.
+                const candidateCap = nodeMode
+                    ? {
+                        maxNodes: Math.max(1, Math.min(options.improvePhase2MaxNodes ?? phase2CandidateBase.maxNodes ?? remainingNodes, remainingNodes))
+                    }
+                    : {
+                        timeoutMs: Math.min(options.improvePhase2TimeoutMs ?? legacyPhase2Wall ?? 25, Math.max(1, deadline - performance.now()))
+                    };
+                const candP2 = await solveCube3Phase2(cand.state, {
+                    ...phase2CandidateBase,
+                    pairTables: scoredPairTables,
+                    tables: p2Tables,
+                    maxDepth: maxP2,
+                    previousFace: cand.pFace,
+                    previousPreviousFace: cand.ppFace,
+                    ...candidateCap
+                });
+                improvementNodes += candP2.visitedNodes;
+                spendNodes(candP2.visitedNodes);
+                const candTotal = cand.moves.length + candP2.moves.length;
+                if (candTotal < bestMoves.length) {
+                    bestMoves = [...cand.moves, ...candP2.moves];
+                    bestP1 = {
+                        moves: cand.moves,
+                        depth: cand.moves.length,
+                        state: cand.state,
+                        coordinates: (0, phase1_js_1.encodeCube3Phase1Coordinates)(cand.state),
+                        visitedNodes: 0
+                    };
+                    bestP2 = candP2;
+                    if (targetLength !== undefined && bestMoves.length <= targetLength) {
+                        break;
+                    }
+                }
+            }
+            catch {
+                // continue
+            }
+        }
+        return {
+            phase1: bestP1,
+            phase2: bestP2,
+            moves: bestMoves,
+            depth: bestMoves.length,
+            state: bestP2.state,
+            visitedNodes: phase1.visitedNodes + phase2.visitedNodes + improvementNodes
+        };
+    }
     return {
         phase1,
         phase2,
@@ -125,6 +276,39 @@ async function solveCube3State(state, options = {}) {
         visitedNodes: phase1.visitedNodes + phase2.visitedNodes
     };
 }
+/**
+ * Best-of-N-orientations solve: UD plus rotated copies, mapped back with
+ * the inverse rotation. Rotating a solution conjugates the whole picture,
+ * so the mapped-back moves solve the original state with their length
+ * preserved. Deterministic: ties keep the earliest orientation (UD first).
+ */
+async function solveCube3TripleOrientation(state, options) {
+    const count = Math.min(Math.max(options.orientations ?? 1, 1), symmetry_js_1.CUBE3_ORIENTATIONS_24.length);
+    const singleOptions = { ...options, orientations: 1 };
+    let best = await solveCube3State(state, singleOptions);
+    let visitedNodes = best.visitedNodes;
+    const scramble = (0, moves_js_1.invertCube3Algorithm)(best.moves);
+    const sequences = symmetry_js_1.CUBE3_ORIENTATIONS_24.slice(1, count);
+    for (const sequence of sequences) {
+        try {
+            const rotatedState = (0, moves_js_1.applyCube3Algorithm)((0, state_js_1.createSolvedCube3State)(), (0, symmetry_js_1.rotateCube3AlgorithmBySequence)(scramble, sequence));
+            const candidate = await solveCube3State(rotatedState, singleOptions);
+            visitedNodes += candidate.visitedNodes;
+            if (candidate.moves.length < best.moves.length) {
+                best = {
+                    ...candidate,
+                    moves: (0, symmetry_js_1.rotateCube3AlgorithmBySequence)(candidate.moves, (0, symmetry_js_1.invertCube3RotationSequence)(sequence)),
+                    depth: candidate.moves.length,
+                    visitedNodes
+                };
+            }
+        }
+        catch {
+            // A flaky orientation must never fail the whole solve.
+        }
+    }
+    return { ...best, visitedNodes };
+}
 function encodeCube3Phase2Coordinates(state) {
     return {
         cornerPermutation: encodeCornerPermutationForPhase2(state),
@@ -147,10 +331,38 @@ const PHASE2_MOVE_FACES = tables_js_1.CUBE3_PHASE2_MOVES.map((move) => {
     const char = move[0];
     return char === "U" ? 0 : char === "D" ? 1 : char === "R" ? 2 : char === "L" ? 3 : char === "F" ? 4 : 5;
 });
+function createPhase2SearchContext(tables, pairTables, maxDepth, deadline, nodeCap = undefined) {
+    const scratchLevels = maxDepth + 1;
+    const scratchSize = scratchLevels * tables_js_1.CUBE3_PHASE2_MOVES.length;
+    return {
+        tables,
+        pairTables,
+        maxDepth,
+        deadline,
+        nodeCap,
+        visitedNodes: 0,
+        timedOut: false,
+        nodesExceeded: false,
+        scratchMove: new Int32Array(scratchSize),
+        scratchBound: new Int32Array(scratchSize),
+        scratchCp: new Int32Array(scratchSize),
+        scratchUep: new Int32Array(scratchSize),
+        scratchSp: new Int32Array(scratchSize)
+    };
+}
 function searchPhase2(cornerPermutation, udEdgePermutation, slicePermutation, previousFace, previousPreviousFace, remainingDepth, path, context) {
     context.visitedNodes += 1;
-    if (context.deadline !== undefined && (context.visitedNodes & 1023) === 0 && performance.now() > context.deadline) {
+    if (context.nodeCap !== undefined &&
+        context.visitedNodes > context.nodeCap) {
+        context.nodesExceeded = true;
+    }
+    if (!context.nodesExceeded &&
+        context.deadline !== undefined &&
+        (context.visitedNodes & 1023) === 0 &&
+        performance.now() > context.deadline) {
         context.timedOut = true;
+    }
+    if (context.timedOut || context.nodesExceeded) {
         return false;
     }
     if (remainingDepth === 0) {
@@ -166,41 +378,23 @@ function searchPhase2(cornerPermutation, udEdgePermutation, slicePermutation, pr
     const spRange = context.tables.moveTables.slicePermutation.range;
     const cpspTable = context.tables.pruningTables.cornerPermutationSlicePermutation.values;
     const epspTable = context.tables.pruningTables.udEdgePermutationSlicePermutation.values;
+    const pairTables = context.pairTables;
     const cpOffset = cornerPermutation * moveCount;
     const epOffset = udEdgePermutation * moveCount;
     const spOffset = slicePermutation * moveCount;
-    // Without the pair tables (the default npm package), keep the exact
-    // reference traversal — zero overhead. With them (turbo tier), collect the
-    // children with the pair-distance bound and explore in ascending bound
-    // order (stable: ties keep the reference move order): same depth-minimal
-    // solutions, far fewer nodes.
-    if (context.pairTables === undefined) {
-        for (let i = 0; i < validMoves.length; i += 1) {
-            const moveIndex = validMoves[i];
-            const nextCornerPermutation = cpTable[cpOffset + moveIndex];
-            const nextUdEdgePermutation = epTable[epOffset + moveIndex];
-            const nextSlicePermutation = spTable[spOffset + moveIndex];
-            const combinedCPIndex = nextCornerPermutation * spRange + nextSlicePermutation;
-            const combinedEPIndex = nextUdEdgePermutation * spRange + nextSlicePermutation;
-            const cpDist = (cpspTable[combinedCPIndex >> 1] >> ((combinedCPIndex & 1) << 2)) & 0x0f;
-            const epDist = (epspTable[combinedEPIndex >> 1] >> ((combinedEPIndex & 1) << 2)) & 0x0f;
-            const nextLowerBound = cpDist > epDist ? cpDist : epDist;
-            if (nextLowerBound > remainingDepth - 1) {
-                continue;
-            }
-            path.push(context.tables.phase2Moves[moveIndex]);
-            if (searchPhase2(nextCornerPermutation, nextUdEdgePermutation, nextSlicePermutation, PHASE2_MOVE_FACES[moveIndex], previousFace, remainingDepth - 1, path, context)) {
-                return true;
-            }
-            path.pop();
-            if (context.timedOut) {
-                return false;
-            }
-        }
-        return false;
-    }
-    const pairTables = context.pairTables;
-    const children = [];
+    // Collect the surviving children with the pair-tightened lower bound and
+    // explore them in ascending bound order (stable: ties keep the reference
+    // move order). Without the pair tables this reduces to ordering by
+    // max(cpsp, uepsp) — same depth-minimal solutions, far fewer nodes than
+    // the reference traversal. With them, same set and order as before but
+    // without per-node allocation.
+    const slot = remainingDepth * moveCount;
+    const scratchMove = context.scratchMove;
+    const scratchBound = context.scratchBound;
+    const scratchCp = context.scratchCp;
+    const scratchUep = context.scratchUep;
+    const scratchSp = context.scratchSp;
+    let childCount = 0;
     for (let i = 0; i < validMoves.length; i += 1) {
         const moveIndex = validMoves[i];
         const nextCornerPermutation = cpTable[cpOffset + moveIndex];
@@ -214,29 +408,52 @@ function searchPhase2(cornerPermutation, udEdgePermutation, slicePermutation, pr
         if (nextLowerBound > remainingDepth - 1) {
             continue;
         }
-        const pair = (0, pair_tables_js_1.pairBound)(pairTables, nextCornerPermutation, nextUdEdgePermutation);
-        if (pair > nextLowerBound) {
-            nextLowerBound = pair;
+        if (pairTables !== undefined) {
+            const pair = (0, pair_tables_js_1.pairBound)(pairTables, nextCornerPermutation, nextUdEdgePermutation);
+            if (pair > nextLowerBound) {
+                nextLowerBound = pair;
+            }
+            if (nextLowerBound > remainingDepth - 1) {
+                continue;
+            }
         }
-        if (nextLowerBound > remainingDepth - 1) {
-            continue;
+        scratchMove[slot + childCount] = moveIndex;
+        scratchBound[slot + childCount] = nextLowerBound;
+        scratchCp[slot + childCount] = nextCornerPermutation;
+        scratchUep[slot + childCount] = nextUdEdgePermutation;
+        scratchSp[slot + childCount] = nextSlicePermutation;
+        childCount += 1;
+    }
+    // Stable insertion sort by bound (n <= 10; ties keep reference order).
+    for (let i = 1; i < childCount; i += 1) {
+        const move = scratchMove[slot + i];
+        const bound = scratchBound[slot + i];
+        const cp = scratchCp[slot + i];
+        const uep = scratchUep[slot + i];
+        const sp = scratchSp[slot + i];
+        let j = i - 1;
+        while (j >= 0 && scratchBound[slot + j] > bound) {
+            scratchMove[slot + j + 1] = scratchMove[slot + j];
+            scratchBound[slot + j + 1] = scratchBound[slot + j];
+            scratchCp[slot + j + 1] = scratchCp[slot + j];
+            scratchUep[slot + j + 1] = scratchUep[slot + j];
+            scratchSp[slot + j + 1] = scratchSp[slot + j];
+            j -= 1;
         }
-        children.push({
-            moveIndex,
-            lowerBound: nextLowerBound,
-            cornerPermutation: nextCornerPermutation,
-            udEdgePermutation: nextUdEdgePermutation,
-            slicePermutation: nextSlicePermutation
-        });
+        scratchMove[slot + j + 1] = move;
+        scratchBound[slot + j + 1] = bound;
+        scratchCp[slot + j + 1] = cp;
+        scratchUep[slot + j + 1] = uep;
+        scratchSp[slot + j + 1] = sp;
     }
-    children.sort((left, right) => left.lowerBound - right.lowerBound);
-    for (const child of children) {
-        path.push(context.tables.phase2Moves[child.moveIndex]);
-        if (searchPhase2(child.cornerPermutation, child.udEdgePermutation, child.slicePermutation, PHASE2_MOVE_FACES[child.moveIndex], previousFace, remainingDepth - 1, path, context)) {
+    for (let i = 0; i < childCount; i += 1) {
+        const moveIndex = scratchMove[slot + i];
+        path.push(context.tables.phase2Moves[moveIndex]);
+        if (searchPhase2(scratchCp[slot + i], scratchUep[slot + i], scratchSp[slot + i], PHASE2_MOVE_FACES[moveIndex], previousFace, remainingDepth - 1, path, context)) {
             return true;
         }
         path.pop();
-        if (context.timedOut) {
+        if (context.timedOut || context.nodesExceeded) {
             return false;
         }
     }
@@ -281,13 +498,7 @@ function searchPhase1Interleaved(cornerOrientation, edgeOrientation, udSlice, pr
         const g1State = applyCube3Phase2Moves(context.originalState, path);
         const start2 = encodeCube3Phase2Coordinates(g1State);
         const maxPhase2Depth = 6;
-        const phase2Context = {
-            tables: context.phase2Tables,
-            pairTables: undefined,
-            deadline: context.deadline,
-            visitedNodes: 0,
-            timedOut: false
-        };
+        const phase2Context = createPhase2SearchContext(context.phase2Tables, undefined, maxPhase2Depth, context.deadline);
         for (let d2 = 0; d2 <= maxPhase2Depth; d2 += 1) {
             const path2 = [];
             const solved2 = searchPhase2(start2.cornerPermutation, start2.udEdgePermutation, start2.slicePermutation, -1, -1, d2, path2, phase2Context);

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

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CUBE3_ORIENTATIONS_24 = exports.CUBE3_ROTATION_INVERSE = void 0;
+exports.invertCube3RotationSequence = invertCube3RotationSequence;
+exports.rotateCube3AlgorithmBySequence = rotateCube3AlgorithmBySequence;
+exports.rotateCube3Algorithm = rotateCube3Algorithm;
+const ROT_FACE = {
+    "x": { "U": "B", "R": "R", "F": "U", "D": "F", "L": "L", "B": "D" },
+    "x'": { "U": "F", "R": "R", "F": "D", "D": "B", "L": "L", "B": "U" },
+    "y": { "U": "U", "R": "F", "F": "L", "D": "D", "L": "B", "B": "R" },
+    "y'": { "U": "U", "R": "B", "F": "R", "D": "D", "L": "F", "B": "L" },
+    "z": { "U": "R", "R": "D", "F": "F", "D": "L", "L": "U", "B": "B" },
+    "z'": { "U": "L", "R": "U", "F": "F", "D": "R", "L": "D", "B": "B" },
+    "x2": { "U": "D", "R": "R", "F": "B", "D": "U", "L": "L", "B": "F" },
+    "y2": { "U": "U", "R": "L", "F": "B", "D": "D", "L": "R", "B": "F" },
+    "z2": { "U": "D", "R": "L", "F": "F", "D": "U", "L": "R", "B": "B" }
+};
+const INVERT_ROTATION = {
+    "x": "x'", "x'": "x",
+    "y": "y'", "y'": "y",
+    "z": "z'", "z'": "z",
+    "x2": "x2", "y2": "y2", "z2": "z2"
+};
+exports.CUBE3_ROTATION_INVERSE = {
+    "x": "x'",
+    "x'": "x",
+    "z": "z'",
+    "z'": "z"
+};
+/**
+ * 24 whole-cube orientations as rotation sequences, discovered by BFS over
+ * the group generated by x/y/z (canonicalized by face map, so all 24 are
+ * geometrically distinct by construction).
+ * The first three are identity, x, z — so `orientations: 3` keeps the
+ * legacy UD/x/z triple exactly.
+ */
+exports.CUBE3_ORIENTATIONS_24 = (() => {
+    const faces = ["U", "R", "F", "D", "L", "B"];
+    const identity = "URFDLB";
+    const composeKey = (key, gen) => {
+        const map = ROT_FACE[gen];
+        return faces.map((face, index) => map[key[index]]).join("");
+    };
+    const seen = new Map([[identity, []]]);
+    const queue = [identity];
+    while (queue.length > 0) {
+        const key = queue.shift();
+        const sequence = seen.get(key);
+        for (const gen of ["x", "y", "z"]) {
+            const next = composeKey(key, gen);
+            if (!seen.has(next)) {
+                seen.set(next, [...sequence, gen]);
+                queue.push(next);
+            }
+        }
+    }
+    const isLegacyTriple = (sequence) => sequence.length === 0 ||
+        (sequence.length === 1 && (sequence[0] === "x" || sequence[0] === "z"));
+    const rest = [];
+    for (const sequence of seen.values()) {
+        if (!isLegacyTriple(sequence))
+            rest.push(sequence);
+    }
+    return [[], ["x"], ["z"], ...rest];
+})();
+function invertCube3RotationSequence(sequence) {
+    return [...sequence].reverse().map((rotation) => INVERT_ROTATION[rotation]);
+}
+function rotateCube3AlgorithmBySequence(moves, sequence) {
+    let result = [...moves];
+    for (const rotation of sequence) {
+        const map = ROT_FACE[rotation];
+        result = result.map((move) => `${map[move[0]]}${move.slice(1)}`);
+    }
+    return result;
+}
+function rotateCube3Algorithm(moves, rotation) {
+    const map = ROT_FACE[rotation];
+    return moves.map((move) => `${map[move[0]]}${move.slice(1)}`);
+}

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/cube3/validation.js

@@ -47,15 +47,23 @@ function isAllowedRandomCube3State(state) {
         !isOneMoveFromSolvedCube3State(state);
 }
 function permutationParity(permutation) {
-    let inversions = 0;
-    for (let left = 0; left < permutation.length; left += 1) {
-        for (let right = left + 1; right < permutation.length; right += 1) {
-            if (permutation[left] > permutation[right]) {
-                inversions += 1;
-            }
+    // Cycle-decomposition parity in O(n) instead of O(n²) inversion counting
+    // (identical result: parity = (n − cycles) mod 2).
+    const visited = new Array(permutation.length).fill(false);
+    let parity = 0;
+    for (let start = 0; start < permutation.length; start += 1) {
+        if (visited[start] || permutation[start] === start)
+            continue;
+        let length = 0;
+        let current = start;
+        while (!visited[current]) {
+            visited[current] = true;
+            current = permutation[current];
+            length += 1;
         }
+        parity ^= (length - 1) & 1;
     }
-    return (inversions % 2);
+    return parity;
 }
 function validatePermutation(label, permutation, length) {
     const errors = [];