@cubingcenter/scrambler 0.1.0

package/dist/puzzles/cube3/types.js

@@ -0,0 +1,22 @@
+export const CORNER_COUNT = 8;
+export const EDGE_COUNT = 12;
+export const CUBE3_MOVES = [
+    "U",
+    "U2",
+    "U'",
+    "D",
+    "D2",
+    "D'",
+    "R",
+    "R2",
+    "R'",
+    "L",
+    "L2",
+    "L'",
+    "F",
+    "F2",
+    "F'",
+    "B",
+    "B2",
+    "B'"
+];

package/dist/puzzles/cube3/validation.d.ts

@@ -0,0 +1,6 @@
+import type { Cube3State, Cube3ValidationResult } from "./types.js";
+export declare function validateCube3State(state: Cube3State): Cube3ValidationResult;
+export declare function isOneMoveFromSolvedCube3State(state: Cube3State): boolean;
+export declare function isAllowedRandomCube3State(state: Cube3State): boolean;
+export declare function permutationParity(permutation: readonly number[]): 0 | 1;
+//# sourceMappingURL=validation.d.ts.map

package/dist/puzzles/cube3/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube3/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAIpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,qBAAqB,CA+B3E;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAGxE;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAIpE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAYvE"}

package/dist/puzzles/cube3/validation.js

@@ -0,0 +1,83 @@
+import { CUBE3_MOVES, CORNER_COUNT, EDGE_COUNT } from "./types.js";
+import { applyCube3Move } from "./moves.js";
+import { createSolvedCube3State, cube3StatesEqual, isSolvedCube3State } from "./state.js";
+export function validateCube3State(state) {
+    const errors = [
+        ...validatePermutation("corner", state.corners.permutation, CORNER_COUNT),
+        ...validatePermutation("edge", state.edges.permutation, EDGE_COUNT),
+        ...validateOrientations("corner", state.corners.orientation, CORNER_COUNT, 3),
+        ...validateOrientations("edge", state.edges.orientation, EDGE_COUNT, 2)
+    ];
+    if (errors.length === 0) {
+        const cornerOrientation = sum(state.corners.orientation) % 3;
+        const edgeOrientation = sum(state.edges.orientation) % 2;
+        const cornerParity = permutationParity(state.corners.permutation);
+        const edgeParity = permutationParity(state.edges.permutation);
+        if (cornerOrientation !== 0) {
+            errors.push("Corner orientation sum must be divisible by 3.");
+        }
+        if (edgeOrientation !== 0) {
+            errors.push("Edge orientation sum must be divisible by 2.");
+        }
+        if (cornerParity !== edgeParity) {
+            errors.push("Corner and edge permutation parity must match.");
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+export function isOneMoveFromSolvedCube3State(state) {
+    const solved = createSolvedCube3State();
+    return CUBE3_MOVES.some((move) => cube3StatesEqual(applyCube3Move(solved, move), state));
+}
+export function isAllowedRandomCube3State(state) {
+    return validateCube3State(state).valid &&
+        !isSolvedCube3State(state) &&
+        !isOneMoveFromSolvedCube3State(state);
+}
+export 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 validatePermutation(label, permutation, length) {
+    const errors = [];
+    const seen = new Set();
+    if (permutation.length !== length) {
+        errors.push(`${label} permutation must contain ${length} values.`);
+    }
+    for (const value of permutation) {
+        if (!Number.isInteger(value) || value < 0 || value >= length) {
+            errors.push(`${label} permutation contains out-of-range value: ${value}.`);
+            continue;
+        }
+        if (seen.has(value)) {
+            errors.push(`${label} permutation contains duplicate value: ${value}.`);
+        }
+        seen.add(value);
+    }
+    return errors;
+}
+function validateOrientations(label, orientations, length, modulo) {
+    const errors = [];
+    if (orientations.length !== length) {
+        errors.push(`${label} orientation must contain ${length} values.`);
+    }
+    for (const value of orientations) {
+        if (!Number.isInteger(value) || value < 0 || value >= modulo) {
+            errors.push(`${label} orientation contains out-of-range value: ${value}.`);
+        }
+    }
+    return errors;
+}
+function sum(values) {
+    return values.reduce((total, value) => total + value, 0);
+}

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

@@ -0,0 +1,5 @@
+import type { Cube4Face, Cube4Facelets, Cube4State } from "./types.js";
+export declare function toCube4Facelets(state: Cube4State): Cube4Facelets;
+export declare function formatCube4Facelets(facelets: Cube4Facelets): string;
+export declare function getCube4FaceOrder(): readonly Cube4Face[];
+//# sourceMappingURL=facelets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"facelets.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/facelets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AAmGrF,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAuDhE;AAMD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAEnE;AAMD,wBAAgB,iBAAiB,IAAI,SAAS,SAAS,EAAE,CAExD"}

package/dist/puzzles/cube4/facelets.js

@@ -0,0 +1,135 @@
+import { CORNER_COUNT, WING_COUNT, CENTER_COUNT } from "./types.js";
+const FACE_ORDER = ["U", "R", "F", "D", "L", "B"];
+const FACE_LETTERS = FACE_ORDER;
+const CENTER_SLOTS = [5, 6, 9, 10];
+// ---------------------------------------------------------------------------
+// Corner piece sticker colors (by piece identity 0-7, same as 3x3)
+// ---------------------------------------------------------------------------
+const CORNER_PIECE_STICKERS = [
+    ["U", "R", "F"], // 0 = URF
+    ["U", "F", "L"], // 1 = UFL
+    ["U", "L", "B"], // 2 = ULB
+    ["U", "B", "R"], // 3 = UBR
+    ["D", "F", "R"], // 4 = DFR
+    ["D", "L", "F"], // 5 = DLF
+    ["D", "B", "L"], // 6 = DBL
+    ["D", "R", "B"], // 7 = DRB
+];
+const CORNER_POSITION_SLOTS = [
+    [["U", 15], ["R", 0], ["F", 3]], // 0 = URF
+    [["U", 12], ["F", 0], ["L", 3]], // 1 = UFL
+    [["U", 0], ["L", 0], ["B", 3]], // 2 = ULB
+    [["U", 3], ["B", 0], ["R", 3]], // 3 = UBR
+    [["D", 3], ["F", 15], ["R", 12]], // 4 = DFR
+    [["D", 0], ["L", 15], ["F", 12]], // 5 = DLF
+    [["D", 12], ["B", 15], ["L", 12]], // 6 = DBL
+    [["D", 15], ["R", 15], ["B", 12]], // 7 = DRB
+];
+// ---------------------------------------------------------------------------
+// Wing piece color pairs (by wing identity 0-23)
+// Wings 2k and 2k+1 share the same colors (they form a 3x3-edge pair).
+// ---------------------------------------------------------------------------
+const WING_PIECE_COLORS = [
+    ["U", "R"], ["U", "R"], //  0, 1  UR pair
+    ["U", "F"], ["U", "F"], //  2, 3  UF pair
+    ["U", "L"], ["U", "L"], //  4, 5  UL pair
+    ["U", "B"], ["U", "B"], //  6, 7  UB pair
+    ["D", "R"], ["D", "R"], //  8, 9  DR pair
+    ["D", "F"], ["D", "F"], // 10, 11 DF pair
+    ["D", "L"], ["D", "L"], // 12, 13 DL pair
+    ["D", "B"], ["D", "B"], // 14, 15 DB pair
+    ["F", "R"], ["F", "R"], // 16, 17 FR pair
+    ["F", "L"], ["F", "L"], // 18, 19 FL pair
+    ["B", "L"], ["B", "L"], // 20, 21 BL pair
+    ["B", "R"], ["B", "R"], // 22, 23 BR pair
+];
+const WING_POSITION_SLOTS = [
+    [["U", 11], ["R", 1]], //  0  URf
+    [["U", 7], ["R", 2]], //  1  URb
+    [["U", 14], ["F", 2]], //  2  UFr
+    [["U", 13], ["F", 1]], //  3  UFl
+    [["U", 8], ["L", 2]], //  4  ULf
+    [["U", 4], ["L", 1]], //  5  ULb
+    [["U", 1], ["B", 2]], //  6  UBl
+    [["U", 2], ["B", 1]], //  7  UBr
+    [["D", 7], ["R", 13]], //  8  DRf
+    [["D", 11], ["R", 14]], //  9  DRb
+    [["D", 2], ["F", 14]], // 10  DFr
+    [["D", 1], ["F", 13]], // 11  DFl
+    [["D", 4], ["L", 14]], // 12  DLf
+    [["D", 8], ["L", 13]], // 13  DLb
+    [["D", 13], ["B", 14]], // 14  DBl
+    [["D", 14], ["B", 13]], // 15  DBr
+    [["F", 7], ["R", 4]], // 16  FRu
+    [["F", 11], ["R", 8]], // 17  FRd
+    [["F", 4], ["L", 7]], // 18  FLu
+    [["F", 8], ["L", 11]], // 19  FLd
+    [["B", 7], ["L", 4]], // 20  BLu
+    [["B", 11], ["L", 8]], // 21  BLd
+    [["B", 4], ["R", 7]], // 22  BRu
+    [["B", 8], ["R", 11]], // 23  BRd
+];
+// ---------------------------------------------------------------------------
+// toCube4Facelets
+// ---------------------------------------------------------------------------
+export function toCube4Facelets(state) {
+    const f = {
+        U: Array(16).fill("U"),
+        R: Array(16).fill("R"),
+        F: Array(16).fill("F"),
+        D: Array(16).fill("D"),
+        L: Array(16).fill("L"),
+        B: Array(16).fill("B"),
+    };
+    // Centers
+    for (let i = 0; i < CENTER_COUNT; i++) {
+        const face = FACE_LETTERS[Math.floor(i / 4)];
+        const slot = CENTER_SLOTS[i % 4];
+        f[face][slot] = FACE_LETTERS[state.centers[i]];
+    }
+    // Corners
+    for (let pos = 0; pos < CORNER_COUNT; pos++) {
+        const piece = state.cp[pos];
+        const ori = state.co[pos];
+        const slots = CORNER_POSITION_SLOTS[pos];
+        const stickers = CORNER_PIECE_STICKERS[piece];
+        for (let i = 0; i < slots.length; i++) {
+            const [face, idx] = slots[i];
+            f[face][idx] = stickers[(i - ori + stickers.length) % stickers.length];
+        }
+    }
+    // Wings: Recover orientation mathematically using XOR orbit parity!
+    // A wing is physically flipped if its chiral group (Left/Right) differs from the slot's chiral group.
+    const RIGHT_GROUP = new Set([1, 2, 4, 6, 8, 11, 13, 15, 16, 19, 20, 23]);
+    for (let pos = 0; pos < WING_COUNT; pos++) {
+        const piece = state.wp[pos];
+        const slots = WING_POSITION_SLOTS[pos];
+        const colors = WING_PIECE_COLORS[piece];
+        const [f0, i0] = slots[0];
+        const [f1, i1] = slots[1];
+        const wingIsRight = RIGHT_GROUP.has(piece);
+        const slotIsRight = RIGHT_GROUP.has(pos);
+        const isFlipped = wingIsRight !== slotIsRight;
+        if (isFlipped) {
+            f[f0][i0] = colors[1]; // Secondary color to primary slot sticker
+            f[f1][i1] = colors[0]; // Primary color to secondary slot sticker
+        }
+        else {
+            f[f0][i0] = colors[0]; // Primary color to primary slot sticker
+            f[f1][i1] = colors[1]; // Secondary color to secondary slot sticker
+        }
+    }
+    return f;
+}
+// ---------------------------------------------------------------------------
+// formatCube4Facelets
+// ---------------------------------------------------------------------------
+export function formatCube4Facelets(facelets) {
+    return FACE_ORDER.map((face) => facelets[face].join("")).join("");
+}
+// ---------------------------------------------------------------------------
+// getCube4FaceOrder
+// ---------------------------------------------------------------------------
+export function getCube4FaceOrder() {
+    return FACE_ORDER;
+}

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

@@ -0,0 +1,7 @@
+export { CORNER_COUNT, WING_COUNT, CENTER_COUNT, FACE_COUNT, CENTERS_PER_FACE, U, R, F, D, L, B, CUBE4_FACE_MOVES, CUBE4_ALL_MOVES, CUBE4_OUTER_MOVES } from "./types.js";
+export type { Cube4Face, Cube4FaceMove, Cube4Move, Cube4MoveSuffix, Cube4State, Cube4Sticker, Cube4Facelets, Cube4RandomStateOptions } from "./types.js";
+export { createSolvedCube4State, cloneCube4State, cube4StatesEqual, isSolvedCube4State, areCentersReduced, areWingsPaired } from "./state.js";
+export { applyCube4Move, applyCube4Algorithm, invertCube4Move, invertCube4Algorithm, formatCube4Algorithm, parseCube4Algorithm, parseCube4Move, parseMove, FACE_MOVE_EFFECTS } from "./moves.js";
+export { cube4ScrambleGenerator, generateCube4Scramble } from "./scrambler.js";
+export { toCube4Facelets, formatCube4Facelets, getCube4FaceOrder } from "./facelets.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAChB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,SAAS,EACT,aAAa,EACb,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,EACZ,aAAa,EACb,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,SAAS,EACT,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,eAAe,CAAC"}

package/dist/puzzles/cube4/index.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// cube4 barrel exports
+// ---------------------------------------------------------------------------
+export { CORNER_COUNT, WING_COUNT, CENTER_COUNT, FACE_COUNT, CENTERS_PER_FACE, U, R, F, D, L, B, CUBE4_FACE_MOVES, CUBE4_ALL_MOVES, CUBE4_OUTER_MOVES } from "./types.js";
+export { createSolvedCube4State, cloneCube4State, cube4StatesEqual, isSolvedCube4State, areCentersReduced, areWingsPaired } from "./state.js";
+export { applyCube4Move, applyCube4Algorithm, invertCube4Move, invertCube4Algorithm, formatCube4Algorithm, parseCube4Algorithm, parseCube4Move, parseMove, FACE_MOVE_EFFECTS } from "./moves.js";
+export { cube4ScrambleGenerator, generateCube4Scramble } from "./scrambler.js";
+export { toCube4Facelets, formatCube4Facelets, getCube4FaceOrder } from "./facelets.js";

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

@@ -0,0 +1,37 @@
+/**
+ * 4x4 Move Definitions
+ *
+ * Each base move (CW quarter-turn) is defined by its effect on:
+ *  - Corner permutation & orientation (same as 3x3 for outer moves; identity for wide-only slice)
+ *  - Wing permutation (24 wings)
+ *  - Center permutation (24 centers)
+ *
+ * Wide moves (Uw, Rw, etc.) = outer move + inner slice.
+ * We define outer moves and inner slices separately, then compose.
+ */
+import type { Cube4FaceMove, Cube4Move, Cube4MoveSuffix, Cube4State } from "./types.js";
+interface MoveEffect {
+    /** Corner permutation cycle(s). Identity positions omitted. */
+    cperm: readonly number[];
+    /** Corner orientation deltas (length = CORNER_COUNT). */
+    corient: readonly number[];
+    /** Wing permutation – full 24-element mapping (destination[i] = source index). */
+    wperm: readonly number[];
+    /** Center permutation – full 24-element mapping. */
+    ctperm: readonly number[];
+}
+declare const FACE_MOVE_EFFECTS: Record<Cube4FaceMove, MoveEffect>;
+export declare function parseMove(move: Cube4Move): {
+    face: Cube4FaceMove;
+    suffix: Cube4MoveSuffix;
+    turns: number;
+};
+export declare function applyCube4Move(state: Cube4State, move: Cube4Move): Cube4State;
+export declare function applyCube4Algorithm(state: Cube4State, moves: readonly Cube4Move[]): Cube4State;
+export declare function invertCube4Move(move: Cube4Move): Cube4Move;
+export declare function invertCube4Algorithm(moves: readonly Cube4Move[]): Cube4Move[];
+export declare function formatCube4Algorithm(moves: readonly Cube4Move[]): string;
+export declare function parseCube4Algorithm(algorithm: string): Cube4Move[];
+export declare function parseCube4Move(value: string): Cube4Move;
+export { FACE_MOVE_EFFECTS };
+//# sourceMappingURL=moves.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"moves.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/moves.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQxF,UAAU,UAAU;IAClB,+DAA+D;IAC/D,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,yDAAyD;IACzD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,kFAAkF;IAClF,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,oDAAoD;IACpD,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AA0KD,QAAA,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,UAAU,CAGxD,CAAC;AA0BF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAc1G;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,CAS7E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,UAAU,CAM9F;AAMD,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAI1D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,EAAE,CAE7E;AAMD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAExE;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,CAIlE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAMvD;AAMD,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/puzzles/cube4/moves.js

@@ -0,0 +1,243 @@
+/**
+ * 4x4 Move Definitions
+ *
+ * Each base move (CW quarter-turn) is defined by its effect on:
+ *  - Corner permutation & orientation (same as 3x3 for outer moves; identity for wide-only slice)
+ *  - Wing permutation (24 wings)
+ *  - Center permutation (24 centers)
+ *
+ * Wide moves (Uw, Rw, etc.) = outer move + inner slice.
+ * We define outer moves and inner slices separately, then compose.
+ */
+import { CORNER_COUNT, WING_COUNT, CENTER_COUNT, CUBE4_ALL_MOVES } from "./types.js";
+// ---------------------------------------------------------------------------
+// Identity arrays
+// ---------------------------------------------------------------------------
+const ID_CP = [0, 1, 2, 3, 4, 5, 6, 7];
+const ID_CO = [0, 0, 0, 0, 0, 0, 0, 0];
+const ID_WP = Array.from({ length: 24 }, (_, i) => i);
+const ID_CT = Array.from({ length: 24 }, (_, i) => i);
+// ---------------------------------------------------------------------------
+// Helper: apply cycles to an identity-initialized permutation array
+// ---------------------------------------------------------------------------
+function withCycles(base, ...cycles) {
+    const result = [...base];
+    for (const cycle of cycles) {
+        const last = result[cycle[cycle.length - 1]];
+        for (let i = cycle.length - 1; i > 0; i--) {
+            result[cycle[i]] = result[cycle[i - 1]];
+        }
+        result[cycle[0]] = last;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Outer face moves (single outer layer)
+// ---------------------------------------------------------------------------
+/*
+ * Corner numbering: 0=URF 1=UFL 2=ULB 3=UBR 4=DFR 5=DLF 6=DBL 7=DRB
+ *
+ * Wing numbering (24 wings):
+ *   Pair  0 (UR): 0=URf, 1=URb     Pair  6 (DL): 12=DLf, 13=DLb
+ *   Pair  1 (UF): 2=UFr, 3=UFl     Pair  7 (DB): 14=DBl, 15=DBr
+ *   Pair  2 (UL): 4=ULf, 5=ULb     Pair  8 (FR): 16=FRu, 17=FRd
+ *   Pair  3 (UB): 6=UBl, 7=UBr     Pair  9 (FL): 18=FLu, 19=FLd
+ *   Pair  4 (DR): 8=DRf, 9=DRb     Pair 10 (BL): 20=BLu, 21=BLd
+ *   Pair  5 (DF): 10=DFr, 11=DFl    Pair 11 (BR): 22=BRu, 23=BRd
+ *
+ * Center numbering (inner 2×2 per face, reading order):
+ *   U: 0,1,2,3   R: 4,5,6,7   F: 8,9,10,11
+ *   D: 12,13,14,15   L: 16,17,18,19   B: 20,21,22,23
+ *
+ *   Within a face, positions are:
+ *     0=top-left  1=top-right
+ *     2=bot-left  3=bot-right
+ *   (as seen looking at the face from the outside)
+ */
+const OUTER_U = {
+    cperm: [3, 0, 1, 2, 4, 5, 6, 7],
+    corient: [0, 0, 0, 0, 0, 0, 0, 0],
+    wperm: [7, 6, 1, 0, 2, 3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+    ctperm: [2, 0, 3, 1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+};
+const OUTER_D = {
+    cperm: [0, 1, 2, 3, 5, 6, 7, 4],
+    corient: [0, 0, 0, 0, 0, 0, 0, 0],
+    wperm: [0, 1, 2, 3, 4, 5, 6, 7, 11, 10, 12, 13, 14, 15, 9, 8, 16, 17, 18, 19, 20, 21, 22, 23],
+    ctperm: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 14, 12, 15, 13, 16, 17, 18, 19, 20, 21, 22, 23],
+};
+const OUTER_R = {
+    cperm: [4, 1, 2, 0, 7, 5, 6, 3],
+    corient: [2, 0, 0, 1, 1, 0, 0, 2],
+    wperm: [17, 16, 2, 3, 4, 5, 6, 7, 23, 22, 10, 11, 12, 13, 14, 15, 8, 9, 18, 19, 20, 21, 0, 1],
+    ctperm: [0, 1, 2, 3, 6, 4, 7, 5, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+};
+const OUTER_L = {
+    cperm: [0, 2, 6, 3, 4, 1, 5, 7],
+    corient: [0, 1, 2, 0, 0, 2, 1, 0],
+    wperm: [0, 1, 2, 3, 20, 21, 6, 7, 8, 9, 10, 11, 18, 19, 14, 15, 16, 17, 5, 4, 13, 12, 22, 23],
+    ctperm: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 16, 19, 17, 20, 21, 22, 23],
+};
+const OUTER_F = {
+    cperm: [1, 5, 2, 3, 0, 4, 6, 7],
+    corient: [1, 2, 0, 0, 2, 1, 0, 0],
+    wperm: [0, 1, 18, 19, 4, 5, 6, 7, 8, 9, 16, 17, 12, 13, 14, 15, 3, 2, 11, 10, 20, 21, 22, 23],
+    ctperm: [0, 1, 2, 3, 4, 5, 6, 7, 10, 8, 11, 9, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+};
+const OUTER_B = {
+    cperm: [0, 1, 3, 7, 4, 5, 2, 6],
+    corient: [0, 0, 1, 2, 0, 0, 2, 1],
+    wperm: [0, 1, 2, 3, 4, 5, 22, 23, 8, 9, 10, 11, 12, 13, 20, 21, 16, 17, 18, 19, 7, 6, 15, 14],
+    ctperm: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 22, 20, 23, 21],
+};
+// ---------------------------------------------------------------------------
+// Inner slices — derived from facelet simulation, verified x4=identity
+// ---------------------------------------------------------------------------
+const INNER_u = {
+    cperm: ID_CP, corient: ID_CO,
+    wperm: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 22, 17, 16, 19, 18, 21, 20, 23],
+    ctperm: [0, 1, 2, 3, 20, 21, 6, 7, 4, 5, 10, 11, 12, 13, 14, 15, 8, 9, 18, 19, 16, 17, 22, 23],
+};
+const INNER_d = {
+    cperm: ID_CP, corient: ID_CO,
+    wperm: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 18, 21, 20, 23, 22, 17],
+    ctperm: [0, 1, 2, 3, 4, 5, 10, 11, 8, 9, 18, 19, 12, 13, 14, 15, 16, 17, 22, 23, 20, 21, 6, 7],
+};
+const INNER_r = {
+    cperm: ID_CP, corient: ID_CO,
+    wperm: [0, 1, 10, 3, 4, 5, 6, 2, 8, 9, 15, 11, 12, 13, 14, 7, 16, 17, 18, 19, 20, 21, 22, 23],
+    ctperm: [0, 9, 2, 11, 4, 5, 6, 7, 8, 13, 10, 15, 12, 22, 14, 20, 16, 17, 18, 19, 3, 21, 1, 23],
+};
+const INNER_l = {
+    cperm: ID_CP, corient: ID_CO,
+    wperm: [0, 1, 2, 6, 4, 5, 14, 7, 8, 9, 10, 3, 12, 13, 11, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+    ctperm: [23, 1, 21, 3, 4, 5, 6, 7, 0, 9, 2, 11, 8, 13, 10, 15, 16, 17, 18, 19, 20, 14, 22, 12],
+};
+const INNER_f = {
+    cperm: ID_CP, corient: ID_CO,
+    wperm: [4, 1, 2, 3, 12, 5, 6, 7, 0, 9, 10, 11, 8, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+    ctperm: [0, 1, 19, 17, 2, 5, 3, 7, 8, 9, 10, 11, 6, 4, 14, 15, 16, 12, 18, 13, 20, 21, 22, 23],
+};
+const INNER_b = {
+    cperm: ID_CP, corient: ID_CO,
+    wperm: [0, 9, 2, 3, 4, 1, 6, 7, 8, 13, 10, 11, 12, 5, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+    ctperm: [5, 7, 2, 3, 4, 15, 6, 14, 8, 9, 10, 11, 12, 13, 16, 18, 1, 17, 0, 19, 20, 21, 22, 23],
+};
+// ---------------------------------------------------------------------------
+// Compose two effects to create wide moves: Xw = outer_X then inner_x
+// ---------------------------------------------------------------------------
+function composeEffects(a, b) {
+    const cp = new Array(CORNER_COUNT);
+    const co = new Array(CORNER_COUNT);
+    const wp = new Array(WING_COUNT);
+    const ct = new Array(CENTER_COUNT);
+    for (let i = 0; i < CORNER_COUNT; i++) {
+        cp[i] = a.cperm[b.cperm[i]];
+        co[i] = (a.corient[b.cperm[i]] + b.corient[i]) % 3;
+    }
+    for (let i = 0; i < WING_COUNT; i++) {
+        wp[i] = a.wperm[b.wperm[i]];
+    }
+    for (let i = 0; i < CENTER_COUNT; i++) {
+        ct[i] = a.ctperm[b.ctperm[i]];
+    }
+    return { cperm: cp, corient: co, wperm: wp, ctperm: ct };
+}
+// Wide moves = outer + inner
+const WIDE_Uw = composeEffects(OUTER_U, INNER_u);
+const WIDE_Dw = composeEffects(OUTER_D, INNER_d);
+const WIDE_Rw = composeEffects(OUTER_R, INNER_r);
+const WIDE_Lw = composeEffects(OUTER_L, INNER_l);
+const WIDE_Fw = composeEffects(OUTER_F, INNER_f);
+const WIDE_Bw = composeEffects(OUTER_B, INNER_b);
+// ---------------------------------------------------------------------------
+// Lookup table: face-move name → MoveEffect (CW quarter turn)
+// ---------------------------------------------------------------------------
+const FACE_MOVE_EFFECTS = {
+    U: OUTER_U, D: OUTER_D, R: OUTER_R, L: OUTER_L, F: OUTER_F, B: OUTER_B,
+    Uw: WIDE_Uw, Dw: WIDE_Dw, Rw: WIDE_Rw, Lw: WIDE_Lw, Fw: WIDE_Fw, Bw: WIDE_Bw
+};
+// ---------------------------------------------------------------------------
+// Apply a single move to a state
+// ---------------------------------------------------------------------------
+function applyEffect(state, effect) {
+    const cp = new Uint8Array(CORNER_COUNT);
+    const co = new Uint8Array(CORNER_COUNT);
+    const wp = new Uint8Array(WING_COUNT);
+    const centers = new Uint8Array(CENTER_COUNT);
+    for (let i = 0; i < CORNER_COUNT; i++) {
+        cp[i] = state.cp[effect.cperm[i]];
+        co[i] = (state.co[effect.cperm[i]] + effect.corient[i]) % 3;
+    }
+    for (let i = 0; i < WING_COUNT; i++) {
+        wp[i] = state.wp[effect.wperm[i]];
+    }
+    for (let i = 0; i < CENTER_COUNT; i++) {
+        centers[i] = state.centers[effect.ctperm[i]];
+    }
+    return { cp, co, wp, centers };
+}
+export function parseMove(move) {
+    let face;
+    let suffix;
+    if (move.length >= 2 && move[1] === "w") {
+        face = move.slice(0, 2);
+        suffix = move.slice(2);
+    }
+    else {
+        face = move[0];
+        suffix = move.slice(1);
+    }
+    const turns = suffix === "2" ? 2 : suffix === "'" ? 3 : 1;
+    return { face: face, suffix, turns };
+}
+export 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;
+}
+export function applyCube4Algorithm(state, moves) {
+    let current = state;
+    for (const move of moves) {
+        current = applyCube4Move(current, move);
+    }
+    return current;
+}
+// ---------------------------------------------------------------------------
+// Move inversion
+// ---------------------------------------------------------------------------
+export function invertCube4Move(move) {
+    const { face, suffix } = parseMove(move);
+    if (suffix === "2")
+        return move;
+    return `${face}${suffix === "'" ? "" : "'"}`;
+}
+export function invertCube4Algorithm(moves) {
+    return [...moves].reverse().map(invertCube4Move);
+}
+// ---------------------------------------------------------------------------
+// Format / parse
+// ---------------------------------------------------------------------------
+export function formatCube4Algorithm(moves) {
+    return moves.join(" ");
+}
+export function parseCube4Algorithm(algorithm) {
+    const trimmed = algorithm.trim();
+    if (trimmed.length === 0)
+        return [];
+    return trimmed.split(/\s+/).map(parseCube4Move);
+}
+export function parseCube4Move(value) {
+    if (CUBE4_ALL_MOVES.includes(value)) {
+        return value;
+    }
+    throw new Error(`Invalid 4x4 move: ${value}`);
+}
+// ---------------------------------------------------------------------------
+// Export the raw effects for use by the reduction solver
+// ---------------------------------------------------------------------------
+export { FACE_MOVE_EFFECTS };

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

@@ -0,0 +1,4 @@
+import type { ScrambleGenerator, ScrambleOptions, ScrambleResult } from "../../core/index.js";
+export declare const cube4ScrambleGenerator: ScrambleGenerator;
+export declare function generateCube4Scramble(options?: ScrambleOptions): Promise<ScrambleResult>;
+//# sourceMappingURL=scrambler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrambler.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/scrambler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAU9F,eAAO,MAAM,sBAAsB,EAAE,iBAYpC,CAAC;AAEF,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+BlG"}