@cubingcenter/scrambler 0.1.0

package/dist-cjs/puzzles/pyraminx/solver.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPermutationIndex = getPermutationIndex;
+exports.getPermutationFromIndex = getPermutationFromIndex;
+exports.getOrientationIndex = getOrientationIndex;
+exports.getOrientationFromIndex = getOrientationFromIndex;
+exports.getCentersIndex = getCentersIndex;
+exports.getCentersFromIndex = getCentersFromIndex;
+exports.getStateIndex = getStateIndex;
+exports.solvePyraminx = solvePyraminx;
+const moves_js_1 = require("./moves.js");
+const state_js_1 = require("./state.js");
+// Fast state-to-index encoder/decoder to allow optimal BFS solving
+// Factorials for permutation encoding
+const FACT = [1, 1, 2, 6, 24, 120, 720];
+function getPermutationIndex(perm) {
+    let index = 0;
+    const n = perm.length;
+    for (let i = 0; i < n; i++) {
+        let count = 0;
+        for (let j = i + 1; j < n; j++) {
+            if (perm[j] < perm[i])
+                count++;
+        }
+        index += count * FACT[n - 1 - i];
+    }
+    return index;
+}
+function getPermutationFromIndex(index, n) {
+    const perm = Array(n).fill(0);
+    const temp = Array.from({ length: n }, (_, i) => i);
+    let val = index;
+    for (let i = 0; i < n; i++) {
+        const f = FACT[n - 1 - i];
+        const choice = Math.floor(val / f);
+        val %= f;
+        perm[i] = temp[choice];
+        temp.splice(choice, 1);
+    }
+    return perm;
+}
+function getOrientationIndex(orient) {
+    let index = 0;
+    for (let i = 0; i < 5; i++) {
+        index = (index << 1) | orient[i];
+    }
+    return index;
+}
+function getOrientationFromIndex(index) {
+    const orient = Array(6).fill(0);
+    let temp = index;
+    let sum = 0;
+    for (let i = 4; i >= 0; i--) {
+        const bit = temp & 1;
+        orient[i] = bit;
+        sum += bit;
+        temp >>= 1;
+    }
+    orient[5] = sum % 2 === 0 ? 0 : 1;
+    return orient;
+}
+function getCentersIndex(centers) {
+    return centers[0] + 3 * centers[1] + 9 * centers[2] + 27 * centers[3];
+}
+function getCentersFromIndex(index) {
+    let temp = index;
+    const centers = Array(4).fill(0);
+    for (let i = 0; i < 4; i++) {
+        centers[i] = temp % 3;
+        temp = Math.floor(temp / 3);
+    }
+    return centers;
+}
+function getStateIndex(state) {
+    const c = getCentersIndex(state.centers);
+    const p = getPermutationIndex(state.edgesPerm);
+    const o = getOrientationIndex(state.edgesOrient);
+    // c is 0..80, p is 0..719, o is 0..31
+    return c + 81 * (p + 720 * o);
+}
+// Bidirectional BFS solver
+const MOVES = ["U", "U'", "L", "L'", "R", "R'", "B", "B'"];
+function solvePyraminx(state) {
+    const startIdx = getStateIndex(state);
+    const solvedIdx = getStateIndex((0, state_js_1.createSolvedPyraminxState)());
+    if (startIdx === solvedIdx)
+        return [];
+    // Bidirectional BFS:
+    // forwardMap and backwardMap store the move that led to this index and the parent index
+    const forwardMap = new Map();
+    const backwardMap = new Map();
+    const forwardQueue = [startIdx];
+    const backwardQueue = [solvedIdx];
+    forwardMap.set(startIdx, { move: "", parent: -1 });
+    backwardMap.set(solvedIdx, { move: "", parent: -1 });
+    while (forwardQueue.length > 0 && backwardQueue.length > 0) {
+        // Expand forward
+        const fSize = forwardQueue.length;
+        for (let i = 0; i < Math.min(fSize, 1000); i++) {
+            const currIdx = forwardQueue.shift();
+            const currState = getPyraminxStateFromIndex(currIdx);
+            for (const move of MOVES) {
+                const nextState = (0, moves_js_1.applyPyraminxMove)(currState, move);
+                const nextIdx = getStateIndex(nextState);
+                if (!forwardMap.has(nextIdx)) {
+                    forwardMap.set(nextIdx, { move, parent: currIdx });
+                    if (backwardMap.has(nextIdx)) {
+                        return reconstructPath(nextIdx, forwardMap, backwardMap);
+                    }
+                    forwardQueue.push(nextIdx);
+                }
+            }
+        }
+        // Expand backward
+        const bSize = backwardQueue.length;
+        for (let i = 0; i < Math.min(bSize, 1000); i++) {
+            const currIdx = backwardQueue.shift();
+            const currState = getPyraminxStateFromIndex(currIdx);
+            for (const move of MOVES) {
+                const nextState = (0, moves_js_1.applyPyraminxMove)(currState, move);
+                const nextIdx = getStateIndex(nextState);
+                if (!backwardMap.has(nextIdx)) {
+                    // Note: we record the inverse move since we are searching from solved
+                    const invMove = move.endsWith("'") ? move.slice(0, -1) : `${move}'`;
+                    backwardMap.set(nextIdx, { move: invMove, parent: currIdx });
+                    if (forwardMap.has(nextIdx)) {
+                        return reconstructPath(nextIdx, forwardMap, backwardMap);
+                    }
+                    backwardQueue.push(nextIdx);
+                }
+            }
+        }
+    }
+    throw new Error("Pyraminx state is unsolvable");
+}
+function getPyraminxStateFromIndex(index) {
+    let val = index;
+    const centersIdx = val % 81;
+    val = Math.floor(val / 81);
+    const permIdx = val % 720;
+    const orientIdx = Math.floor(val / 720);
+    return {
+        centers: getCentersFromIndex(centersIdx),
+        edgesPerm: getPermutationFromIndex(permIdx, 6),
+        edgesOrient: getOrientationFromIndex(orientIdx),
+        tips: [0, 0, 0, 0] // tips are solved separately
+    };
+}
+function reconstructPath(meetingIdx, forwardMap, backwardMap) {
+    const path = [];
+    // Reconstruct forward path
+    let curr = meetingIdx;
+    while (curr !== -1) {
+        const edge = forwardMap.get(curr);
+        if (edge.parent !== -1) {
+            path.unshift(edge.move);
+        }
+        curr = edge.parent;
+    }
+    // Reconstruct backward path
+    curr = meetingIdx;
+    while (curr !== -1) {
+        const edge = backwardMap.get(curr);
+        if (edge.parent !== -1) {
+            path.push(edge.move);
+        }
+        curr = edge.parent;
+    }
+    return path;
+}

package/dist-cjs/puzzles/pyraminx/state.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSolvedPyraminxState = createSolvedPyraminxState;
+exports.clonePyraminxState = clonePyraminxState;
+exports.pyraminxStatesEqual = pyraminxStatesEqual;
+exports.isSolvedPyraminxState = isSolvedPyraminxState;
+function createSolvedPyraminxState() {
+    return {
+        centers: [0, 0, 0, 0],
+        edgesPerm: [0, 1, 2, 3, 4, 5],
+        edgesOrient: [0, 0, 0, 0, 0, 0],
+        tips: [0, 0, 0, 0]
+    };
+}
+function clonePyraminxState(state) {
+    return {
+        centers: [...state.centers],
+        edgesPerm: [...state.edgesPerm],
+        edgesOrient: [...state.edgesOrient],
+        tips: [...state.tips]
+    };
+}
+function pyraminxStatesEqual(left, right) {
+    return (arraysEqual(left.centers, right.centers) &&
+        arraysEqual(left.edgesPerm, right.edgesPerm) &&
+        arraysEqual(left.edgesOrient, right.edgesOrient) &&
+        arraysEqual(left.tips, right.tips));
+}
+function isSolvedPyraminxState(state) {
+    return (state.centers.every(c => c === 0) &&
+        state.edgesPerm.every((e, idx) => e === idx) &&
+        state.edgesOrient.every(o => o === 0)
+    // tips don't have to be 0 for the core to be solved in the state-matching, but for full solved they do
+    );
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

package/dist-cjs/puzzles/pyraminx/types.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PYRAMINX_TIPS = exports.PYRAMINX_CORE_MOVES = void 0;
+exports.PYRAMINX_CORE_MOVES = [
+    "U", "U'",
+    "L", "L'",
+    "R", "R'",
+    "B", "B'"
+];
+exports.PYRAMINX_TIPS = ["u", "l", "r", "b"];

package/dist-cjs/puzzles/pyraminx/validation.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePyraminxState = validatePyraminxState;
+exports.permutationParity = permutationParity;
+exports.isAllowedRandomPyraminxState = isAllowedRandomPyraminxState;
+const state_js_1 = require("./state.js");
+function validatePyraminxState(state) {
+    const errors = [];
+    // 1. Centers validation
+    if (state.centers.length !== 4) {
+        errors.push("Centers must contain 4 values.");
+    }
+    else {
+        for (const val of state.centers) {
+            if (val < 0 || val > 2 || !Number.isInteger(val)) {
+                errors.push(`Center orientation out of range: ${val}`);
+            }
+        }
+    }
+    // 2. Tips validation
+    if (state.tips.length !== 4) {
+        errors.push("Tips must contain 4 values.");
+    }
+    else {
+        for (const val of state.tips) {
+            if (val < 0 || val > 2 || !Number.isInteger(val)) {
+                errors.push(`Tip orientation out of range: ${val}`);
+            }
+        }
+    }
+    // 3. Edges Permutation validation
+    if (state.edgesPerm.length !== 6) {
+        errors.push("Edges permutation must contain 6 values.");
+    }
+    else {
+        const seen = new Set();
+        for (const val of state.edgesPerm) {
+            if (val < 0 || val > 5 || !Number.isInteger(val) || seen.has(val)) {
+                errors.push(`Invalid edge permutation value: ${val}`);
+            }
+            seen.add(val);
+        }
+    }
+    // 4. Edges Orientation validation
+    if (state.edgesOrient.length !== 6) {
+        errors.push("Edges orientation must contain 6 values.");
+    }
+    else {
+        let sumOrient = 0;
+        for (const val of state.edgesOrient) {
+            if (val < 0 || val > 1 || !Number.isInteger(val)) {
+                errors.push(`Edge orientation out of range: ${val}`);
+            }
+            sumOrient += val;
+        }
+        if (sumOrient % 2 !== 0) {
+            errors.push("Edge orientation sum must be even.");
+        }
+    }
+    // 5. Permutation parity validation
+    if (errors.length === 0) {
+        if (permutationParity(state.edgesPerm) !== 0) {
+            errors.push("Edge permutation parity must be even.");
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+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;
+            }
+        }
+    }
+    return inversions % 2;
+}
+function isAllowedRandomPyraminxState(state) {
+    return validatePyraminxState(state).valid && !(0, state_js_1.isSolvedPyraminxState)(state);
+}

package/dist-cjs/random/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRandomSource = void 0;
+var prng_js_1 = require("./prng.js");
+Object.defineProperty(exports, "createRandomSource", { enumerable: true, get: function () { return prng_js_1.createRandomSource; } });

package/dist-cjs/random/prng.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRandomSource = createRandomSource;
+const node_crypto_1 = require("node:crypto");
+function createRandomSource(seed) {
+    if (seed === undefined) {
+        return new CryptoRandomSource();
+    }
+    return new SeededRandomSource(hashSeed(seed));
+}
+class CryptoRandomSource {
+    next() {
+        const value = (0, node_crypto_1.randomBytes)(6).readUIntBE(0, 6);
+        return value / 0x1000000000000;
+    }
+    nextInt(maxExclusive) {
+        validateMax(maxExclusive);
+        return Math.floor(this.next() * maxExclusive);
+    }
+    choice(items) {
+        if (items.length === 0) {
+            throw new RangeError("Cannot choose from an empty collection.");
+        }
+        return items[this.nextInt(items.length)];
+    }
+}
+class SeededRandomSource {
+    state;
+    constructor(seed) {
+        this.state = seed >>> 0;
+    }
+    next() {
+        this.state += 0x6d2b79f5;
+        let value = this.state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 0x100000000;
+    }
+    nextInt(maxExclusive) {
+        validateMax(maxExclusive);
+        return Math.floor(this.next() * maxExclusive);
+    }
+    choice(items) {
+        if (items.length === 0) {
+            throw new RangeError("Cannot choose from an empty collection.");
+        }
+        return items[this.nextInt(items.length)];
+    }
+}
+function validateMax(maxExclusive) {
+    if (!Number.isInteger(maxExclusive) || maxExclusive < 1) {
+        throw new RangeError(`maxExclusive must be a positive integer. Received: ${maxExclusive}`);
+    }
+}
+function hashSeed(seed) {
+    const text = String(seed);
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}

package/docs/cubingcenter-integration.md

@@ -0,0 +1,69 @@
+# CubingCenter Integration
+
+Use the root API for timer-facing scramble generation.
+
+## Generate One Scramble
+
+```ts
+import { generateScramble } from "@cubingcenter/scrambler";
+
+const result = generateScramble("222", { seed: "session-42" });
+// or
+const result3x3 = generateScramble("333", { seed: "session-42" });
+
+const scrambleText = result.scramble;
+const moves = result.moves;
+const metadata = result.metadata;
+```
+
+### 2x2 (`222`) metadata
+
+- `state`: target cubie state.
+- `facelets`: six row-major faces keyed by `U R F D L B`.
+- `faceletString`: 24-character string in `U R F D L B` face order.
+- `solutionMoves`: internal solver solution from target state to solved.
+- `solutionDepth`: solver move count.
+
+### 3x3 (`333`) metadata
+
+- `state`: target cubie state.
+- `facelets`: six row-major faces keyed by `U R F D L B`.
+- `faceletString`: 54-character string in `U R F D L B` face order.
+- `solutionMoves`: internal solver solution from target state to solved.
+- `solutionDepth`, `phase1Depth`, `phase2Depth`, `visitedNodes`: diagnostics.
+
+## Timer Preview Flow
+
+The recommended timer flow is:
+
+1. Call `generateScramble("222")` or `generateScramble("333")`.
+2. Show `result.scramble` as the scramble text.
+3. Render `metadata.facelets` directly for the preview.
+4. Map letters to the user's color scheme in the UI layer.
+
+The timer should not need to recompute the cube state from the scramble unless it wants an independent verification path.
+
+## Validation Flow
+
+The generator already verifies that applying `result.moves` to solved reaches the target state. If CubingCenter wants an extra check during development:
+
+```ts
+import { cube2, generateScramble } from "@cubingcenter/scrambler";
+import type { Cube2Move, Cube2State } from "@cubingcenter/scrambler";
+
+const result = generateScramble("222", { seed: "debug" });
+const metadata = result.metadata as { state: Cube2State };
+const state = cube2.applyCube2Algorithm(
+  cube2.createSolvedCube2State(),
+  result.moves as Cube2Move[]
+);
+
+console.log(cube2.cube2StatesEqual(state, metadata.state));
+```
+
+## Error Handling
+
+Unsupported events throw a `ScramblerError` subclass. Treat those as user/configuration errors and avoid retrying the same event id.
+
+Generator failures should be treated as operational errors. For local development, log the seed and event id so the case can be reproduced.
+

package/docs/development.md

@@ -0,0 +1,44 @@
+# Development
+
+## Commands
+
+```sh
+pnpm install
+pnpm lint
+pnpm test
+pnpm build
+pnpm package:check
+pnpm verify
+```
+
+- `pnpm lint`: TypeScript type check without emitting files.
+- `pnpm test`: Node test runner with `tsx`.
+- `pnpm build`: ESM build, CJS build, CJS package marker, generated asset copy.
+- `pnpm package:check`: local package and consumption checks.
+- `pnpm verify`: full local verification for normal development.
+
+## Solver Tables
+
+3x3 solver tables are committed as generated binary assets under the cube3 solver generated directory.
+
+Regenerate them only when coordinates, moves, pruning logic, or table encoding changes:
+
+```sh
+pnpm cube3:tables
+pnpm cube3:tables:check
+```
+
+The build copies those assets into both `dist` and `dist-cjs`. Package checks fail if required generated assets are missing from the packed output.
+
+## Public API Expectations
+
+Root exports are the supported library entrypoint:
+
+```ts
+import { generateScramble, generateScrambles, cube3 } from "@cubingcenter/scrambler";
+```
+
+The `cube3` module is available for advanced tooling, tests, and integration helpers. Normal app code should call `generateScramble("333")` instead of calling the solver directly.
+
+The `cube3.solver` namespace is advanced API. It is useful for diagnostics and development, but timer code should not depend on it for normal rendering.
+

package/docs/facelets.md

@@ -0,0 +1,64 @@
+# Facelets
+
+3x3 facelets are exposed so a timer can draw the target scramble state without recomputing cubies.
+
+## Face Order
+
+The formatted facelet string uses this face order:
+
+```txt
+U R F D L B
+```
+
+Each face has nine stickers in row-major order:
+
+```txt
+0 1 2
+3 4 5
+6 7 8
+```
+
+The solved formatted string is:
+
+```txt
+UUUUUUUUURRRRRRRRRFFFFFFFFFDDDDDDDDDLLLLLLLLLBBBBBBBBB
+```
+
+## Object Shape
+
+```ts
+type Cube3Facelets = {
+  U: Cube3Sticker[];
+  R: Cube3Sticker[];
+  F: Cube3Sticker[];
+  D: Cube3Sticker[];
+  L: Cube3Sticker[];
+  B: Cube3Sticker[];
+};
+```
+
+Every face array has exactly nine entries. A legal 3x3 state has exactly nine stickers of each letter across the whole object.
+
+## Color Mapping
+
+The package returns face letters, not UI colors. CubingCenter should map letters to the selected color scheme:
+
+```ts
+const colors = {
+  U: "#ffffff",
+  R: "#d82929",
+  F: "#2f9e44",
+  D: "#ffd43b",
+  L: "#f08c00",
+  B: "#1c7ed6"
+};
+```
+
+If a user's physical cube uses a different scheme, keep the generated letters unchanged and change only the UI mapping.
+
+## Legal States And Appearance
+
+Visual appearance is not a legality rule. A face can have repeated colors, blocks, lines, or recognizable patterns and still be a legal random-state scramble target.
+
+Legality is checked through cubie permutation parity, corner orientation sum, edge orientation sum, and valid permutations.
+

package/docs/getting-started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+This guide shows how to build and consume `@cubingcenter/scrambler` as a local library.
+
+## Build The Package
+
+```sh
+pnpm install
+pnpm build
+pnpm package:check
+```
+
+`pnpm build` writes ESM output to `dist`, CommonJS output to `dist-cjs`, declaration files to `dist`, and copies the generated 3x3 solver assets into both output trees.
+
+`pnpm package:check` verifies that the built package can be consumed through ESM and CommonJS and that the package contents include the required runtime assets.
+
+## Consume From Another Local Project
+
+Use the workflow that best matches your setup:
+
+```sh
+pnpm add ../cubingcenter-scrambler
+```
+
+or, in a pnpm workspace, add the package as a workspace dependency:
+
+```json
+{
+  "dependencies": {
+    "@cubingcenter/scrambler": "workspace:*"
+  }
+}
+```
+
+For tarball-style testing:
+
+```sh
+pnpm build
+npm pack
+pnpm add ./cubingcenter-scrambler-0.1.0.tgz
+```
+
+## Basic Usage
+
+```ts
+import { generateScramble } from "@cubingcenter/scrambler";
+
+const result2 = generateScramble("222", { seed: "demo" });
+const result3 = generateScramble("333", { seed: "demo" });
+
+console.log(result2.scramble);
+console.log(result2.moves);
+console.log(result2.metadata?.faceletString);
+
+console.log(result3.scramble);
+console.log(result3.moves);
+console.log(result3.metadata?.faceletString);
+```
+
+## Batch Usage
+
+```ts
+import { generateScrambles } from "@cubingcenter/scrambler";
+
+const scrambles = generateScrambles("333", 5, { seed: "session-1" });
+
+for (const item of scrambles) {
+  console.log(item.seed, item.scramble);
+}
+```
+
+When a seed is provided for a batch, each item derives a stable seed with `seed:index`.
+

package/examples/cli-json.md

@@ -0,0 +1,30 @@
+# CLI JSON Shape
+
+```sh
+cubingcenter-scrambler 333 --seed demo --json
+```
+
+The command prints one object for a single scramble:
+
+```json
+{
+  "eventId": "333",
+  "scramble": "R U R'",
+  "moves": ["R", "U", "R'"],
+  "quality": "random-state",
+  "generator": "cube3-two-phase",
+  "seed": "demo",
+  "facelets": {
+    "U": ["U", "U", "U", "U", "U", "U", "U", "U", "U"],
+    "R": ["R", "R", "R", "R", "R", "R", "R", "R", "R"],
+    "F": ["F", "F", "F", "F", "F", "F", "F", "F", "F"],
+    "D": ["D", "D", "D", "D", "D", "D", "D", "D", "D"],
+    "L": ["L", "L", "L", "L", "L", "L", "L", "L", "L"],
+    "B": ["B", "B", "B", "B", "B", "B", "B", "B", "B"]
+  },
+  "faceletString": "UUUUUUUUURRRRRRRRRFFFFFFFFFDDDDDDDDDLLLLLLLLLBBBBBBBBB"
+}
+```
+
+The scramble and facelets above are illustrative. Real output depends on the seed.
+

package/examples/commonjs.cjs

@@ -0,0 +1,11 @@
+const { generateScramble } = require("../dist-cjs/index.js");
+
+(async () => {
+  const result2 = await generateScramble("222", { seed: "commonjs-example-2x2" });
+  console.log("2x2:", result2.scramble);
+  console.log("2x2 facelets:", result2.metadata.faceletString);
+
+  const result3 = await generateScramble("333", { seed: "commonjs-example-3x3" });
+  console.log("3x3:", result3.scramble);
+  console.log("3x3 facelets:", result3.metadata.faceletString);
+})();

package/examples/esm.mjs

@@ -0,0 +1,9 @@
+import { generateScramble } from "../dist/index.js";
+
+const result2 = await generateScramble("222", { seed: "esm-example-2x2" });
+console.log("2x2:", result2.scramble);
+console.log("2x2 facelets:", result2.metadata.faceletString);
+
+const result3 = await generateScramble("333", { seed: "esm-example-3x3" });
+console.log("3x3:", result3.scramble);
+console.log("3x3 facelets:", result3.metadata.faceletString);