@cubingcenter/scrambler 0.5.3 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 Reusable scramble generation toolkit for CubingCenter projects.
 
-The package currently ships random-state scramblers for `222` (2x2x2), `333` (3x3x3), and a first native reduced-state `444` (4x4x4) path. It does not depend on cstimer, cubing.js, or another external scramble engine at runtime.
+The package currently ships random-state scramblers for `222` (2x2x2), `333` (3x3x3), `444` (4x4x4), `pymx` (Pyraminx) and `skwb` (Skewb). The 4x4 scrambler is a native reduction solver (centers + wing pairing + 3x3 finish), table-backed. It does not depend on cstimer, cubing.js, or another external scramble engine at runtime.
 
 ## Status
 
@@ -16,7 +16,7 @@ The package currently ships random-state scramblers for `222` (2x2x2), `333` (3x
 - 3x3 quality: random-state target + two-phase solver + verified scramble inversion
 - Pyraminx quality: random-state target + optimal policy-table solver (all 933,120 core states verified)
 - Skewb quality: random-state target + optimal policy-table solver (all 3,149,280 states; exact uniform sampling)
-- 4x4 quality: reduced 4x4 random-state target + existing 3x3 two-phase finish; full center/wing random-state reduction is isolated under `cube4.reduction`
+- 4x4 quality: random-state target (uniform sampler) + reduction solver (4 phases) + verified scramble inversion
 
 This library is intended for practice, training, and internal CubingCenter use. Do not present it as an official WCA competition scrambler; sanctioned competitions must use the official program required by the delegate/organization.
 
@@ -45,16 +45,13 @@ import {
 const events = getSupportedEvents();
 const info222 = getEventInfo("222");
 const info333 = getEventInfo("333");
-const info444 = getEventInfo("444");
 const scramble2 = generateScramble("222", { seed: "demo" });
 const scramble3 = generateScramble("333", { seed: "demo" });
-const scramble4 = await generateScramble("444");
 const batch = generateScrambles("333", 5, { seed: "session-1" });
 
 console.log(events);
 console.log(scramble2.scramble);
 console.log(scramble3.scramble);
-console.log(scramble4.scramble);
 console.log(batch.map((item) => item.scramble));
 ```
 
@@ -72,7 +69,7 @@ puzzle you need — each subpath registers its own generator, so
 
 ```ts
 import { generateScramble, initializeScrambler } from "@cubingcenter/scrambler/puzzles/pyraminx";
-// "222" | "333" | "444" | "555" | "666" | "777" | "pymx" | "skwb" | "clck" | "mgmx"
+// "222" | "333" | "555" | "666" | "777" | "pymx" | "skwb" | "clck" | "mgmx"
 await initializeScrambler("/scrambler-tables", "pymx");
 const result = await generateScramble("pymx", { seed: "demo" });
 ```
@@ -84,6 +81,25 @@ The demo repo ships precompressed `.br`/`.gz` variants of the tables (see
 `DecompressionStream` is available (Pyraminx ~470 KB → ~345 KB, cube3
 ~6.6 MB → ~2.2 MB).
 
+## 3x3 two-tier tables
+
+The 3x3 solver ships in two tiers:
+
+- **Default**: the standard tables (~7 MB) plus the phase-1 joint tables
+  (`phase1-udco.bin` / `phase1-udeo.bin`, ~1 MB), which tighten the phase-1
+  bound from `max(coeo, ud)` to `max(coeo, ud, udco, udeo)`. They are part
+  of the standard manifest and load automatically.
+- **Turbo (optional)**: additionally, the combined (cp x uep) phase-2
+  pruning table (`generated/pair/`, ~55 MB, generated by the C++ tool
+  `tools/exp3-gen` in the companion `cubingcenter-scrambler-native` repo).
+  When present, the loaders pick it up automatically and phase-2 drops from
+  ~34k to ~40 nodes per solve. It is excluded from the npm package — drop
+  the files into `puzzles/cube3/solver/generated/pair/` (or serve them from
+  your tables base URL) to enable it.
+
+Measured (i5-13420H, warm): default ~14-17 ms/scramble, turbo ~1.2 ms
+(see the companion native repo for the full experiment series).
+
 ## 2x2 Technical Module
 
 ```ts
@@ -178,9 +194,9 @@ const paired = cube4.areWingsPaired(state);
 
 Supported moves: `U D R L F B` (outer) and `Uw Dw Rw Lw Fw Bw` (wide), each with `'` and `2` suffixes.
 
-The public `generateScramble("444")` path currently returns a reduced 4x4 random-state scramble: centers are solved, wings are paired, and the projected 3x3 state is random and solved with the existing two-phase solver. The full arbitrary center/wing random-state pipeline is being developed under `cube4.reduction`.
+The public `generateScramble("444")` path is: sample a uniform random state (`generateRandomCube4State` — corners `8! × 3^7`, wings `24!`, centers as a color multiset `24!/(4!)^6`), solve it with the reduction solver (phases: axis-color face-pairs → ct/rl phase-2 goal → joint center3+pairing → 3x3 finish), and invert the solution — so the scramble always reproduces the sampled target. The pairing pruning table is generated by a C++ tool (`tools/edge3-gen/`).
 
-The `cube4.reduction` namespace is exported for advanced tooling. Normal consumers should prefer `generateScramble("444")`.
+`validateCube4State` checks the reachability constraints of a normal (non-super) 4x4: corner permutation + orientation sum divisible by 3, wing permutation (wings have no orientation), and 4-of-each-color centers. There is no visible corner/wing parity constraint on a normal 4x4 (all four parity combinations are reachable).
 
 ## CLI
 
@@ -193,7 +209,6 @@ cubingcenter-scrambler 222 --seed demo --json
 cubingcenter-scrambler 333 --count 5
 cubingcenter-scrambler 333 --seed demo
 cubingcenter-scrambler 333 --seed demo --json
-cubingcenter-scrambler 444 --count 3
 ```
 
 `list` prints registered events. `--json` prints structured output with `scramble`, `moves`, `facelets`, and `faceletString`.

package/dist/core/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/core/api.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BrG;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,iBAAmC,GAC5C,IAAI,CAEN;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,iBAAmC,GAAG,SAAS,EAAE,CAE7F;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,QAAQ,GAAE,iBAAmC,GAC5C,SAAS,CAQX;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,eAAoB,EAC7B,QAAQ,GAAE,iBAAmC,GAC5C,OAAO,CAAC,cAAc,CAAC,CAiBzB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,EAC7B,QAAQ,GAAE,iBAAmC,GAC5C,OAAO,CAAC,cAAc,EAAE,CAAC,CAU3B"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/core/api.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCrG;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,iBAAmC,GAC5C,IAAI,CAEN;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,iBAAmC,GAAG,SAAS,EAAE,CAE7F;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,QAAQ,GAAE,iBAAmC,GAC5C,SAAS,CAQX;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,eAAoB,EAC7B,QAAQ,GAAE,iBAAmC,GAC5C,OAAO,CAAC,cAAc,CAAC,CAiBzB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,EAC7B,QAAQ,GAAE,iBAAmC,GAC5C,OAAO,CAAC,cAAc,EAAE,CAAC,CAU3B"}

package/dist/core/api.js

@@ -34,12 +34,22 @@ export async function initializeScrambler(baseUrl, eventId) {
         const { loadBrowserTables } = await import("../puzzles/skewb/solver/browser-loader.js");
         await loadBrowserTables(baseUrl);
     }
+    else if (eventId === "sq1") {
+        const { loadBrowserTables } = await import("../puzzles/sq1/solver/browser-loader.js");
+        await loadBrowserTables(baseUrl);
+    }
+    else if (eventId === "444") {
+        const { loadCube4ReductionTablesBrowser } = await import("../puzzles/cube4/reduction/browser-loader.js");
+        await loadCube4ReductionTablesBrowser(baseUrl);
+    }
     else if (!eventId) {
         await Promise.all([
             import("../puzzles/cube2/solver/browser-loader.js").then((m) => m.loadBrowserTables(baseUrl)),
             import("../puzzles/cube3/solver/browser-loader.js").then((m) => m.loadBrowserTables(baseUrl)),
             import("../puzzles/pyraminx/solver/browser-loader.js").then((m) => m.loadBrowserTables(baseUrl)),
-            import("../puzzles/skewb/solver/browser-loader.js").then((m) => m.loadBrowserTables(baseUrl))
+            import("../puzzles/skewb/solver/browser-loader.js").then((m) => m.loadBrowserTables(baseUrl)),
+            import("../puzzles/sq1/solver/browser-loader.js").then((m) => m.loadBrowserTables(baseUrl)),
+            import("../puzzles/cube4/reduction/browser-loader.js").then((m) => m.loadCube4ReductionTablesBrowser(baseUrl))
         ]);
     }
 }

package/dist/core/types.d.ts

@@ -1,5 +1,5 @@
 export type EventId = string;
-export type SupportedEventId = "222" | "333" | "444" | "555" | "666" | "777" | "pymx" | "skwb" | "clck" | "mgmx";
+export type SupportedEventId = "222" | "333" | "444" | "555" | "666" | "777" | "pymx" | "skwb" | "clck" | "mgmx" | "fto" | "sq1";
 export type ScrambleQuality = "random-state" | "random-move" | "training" | "placeholder";
 export interface ScrambleOptions {
     seed?: string | number;

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAG7B,MAAM,MAAM,gBAAgB,GACxB,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,CAAC;AAEX,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,aAAa,GACb,UAAU,GACV,aAAa,CAAC;AAElB,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC7C,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACrD,IAAI,IAAI,SAAS,EAAE,CAAC;IACpB,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAG7B,MAAM,MAAM,gBAAgB,GACxB,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,KAAK,GACL,KAAK,CAAC;AAEV,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,aAAa,GACb,UAAU,GACV,aAAa,CAAC;AAElB,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC7C,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACrD,IAAI,IAAI,SAAS,EAAE,CAAC;IACpB,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAChC"}

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

@@ -1,8 +1,10 @@
 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 type { Cube4Face, Cube4FaceMove, Cube4Move, Cube4MoveSuffix, Cube4State, Cube4Sticker, Cube4Facelets, Cube4ValidationResult, 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 { applyCube4Move, applyCube4Algorithm, invertCube4Move, invertCube4Algorithm, formatCube4Algorithm, parseCube4Algorithm, parseCube4Move, parseMove, FACE_MOVE_EFFECTS } from "./moves.js";
+export { generateRandomCube4State } from "./random-state.js";
+export { validateCube4State, isOneMoveFromSolvedCube4State, isTrivialCube4State, isAllowedRandomCube4State } from "./validation.js";
 export { toCube4Facelets, formatCube4Facelets, getCube4FaceOrder } from "./facelets.js";
 export { generateScramble, generateScrambles, getEventInfo, getSupportedEvents, initializeScrambler } from "../../core/index.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/index.ts"],"names":[],"mappings":"AASA,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;AAEvB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/index.ts"],"names":[],"mappings":"AASA,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,qBAAqB,EACrB,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,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAExB,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,wBAAwB,EACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,mBAAmB,EACnB,yBAAyB,EAC1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC"}

package/dist/puzzles/cube4/index.js

@@ -6,7 +6,9 @@ import { cube4ScrambleGenerator } from "./scrambler.js";
 registerScrambleGenerator(cube4ScrambleGenerator);
 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 { applyCube4Move, applyCube4Algorithm, invertCube4Move, invertCube4Algorithm, formatCube4Algorithm, parseCube4Algorithm, parseCube4Move, parseMove, FACE_MOVE_EFFECTS } from "./moves.js";
+export { generateRandomCube4State } from "./random-state.js";
+export { validateCube4State, isOneMoveFromSolvedCube4State, isTrivialCube4State, isAllowedRandomCube4State } from "./validation.js";
 export { toCube4Facelets, formatCube4Facelets, getCube4FaceOrder } from "./facelets.js";
 export { generateScramble, generateScrambles, getEventInfo, getSupportedEvents, initializeScrambler } from "../../core/index.js";

package/dist/puzzles/cube4/random-state.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Uniform random-state generation for 4x4x4.
+ *
+ * Samples uniformly from the reachable states of the normal (non-super) 4x4:
+ *  - corner permutation 8! + orientation with sum ≡ 0 (mod 3)
+ *  - wing permutation 24! (wings have no orientation)
+ *  - centers: 24!/(4!)^6 (any arrangement with 4 centers of each color)
+ *
+ * On a normal 4x4 the corner and wing permutation parities are independent
+ * (a single face turn changes corner parity while leaving wing parity even),
+ * so no cross-parity constraint is applied here — the reduction solver must
+ * be able to reduce states with all four parity combinations.
+ */
+import type { Cube4RandomStateOptions, Cube4State } from "./types.js";
+export declare function generateRandomCube4State(options?: Cube4RandomStateOptions): Cube4State;
+//# sourceMappingURL=random-state.d.ts.map

package/dist/puzzles/cube4/random-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-state.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/random-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGtE,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAe1F"}

package/dist/puzzles/cube4/random-state.js

@@ -0,0 +1,76 @@
+/**
+ * Uniform random-state generation for 4x4x4.
+ *
+ * Samples uniformly from the reachable states of the normal (non-super) 4x4:
+ *  - corner permutation 8! + orientation with sum ≡ 0 (mod 3)
+ *  - wing permutation 24! (wings have no orientation)
+ *  - centers: 24!/(4!)^6 (any arrangement with 4 centers of each color)
+ *
+ * On a normal 4x4 the corner and wing permutation parities are independent
+ * (a single face turn changes corner parity while leaving wing parity even),
+ * so no cross-parity constraint is applied here — the reduction solver must
+ * be able to reduce states with all four parity combinations.
+ */
+import { createRandomSource } from "../../random/index.js";
+import { CENTER_COUNT, CENTERS_PER_FACE, CORNER_COUNT, FACE_COUNT, WING_COUNT } from "./types.js";
+import { isTrivialCube4State } from "./validation.js";
+export function generateRandomCube4State(options = {}) {
+    const random = createRandomSource(options.seed);
+    const rejectTrivial = options.rejectTrivial ?? true;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        // The state is legal by construction (permutations shuffled, corner
+        // orientation sum fixed, 4 centers per color), so the only meaningful
+        // rejection is the trivial set (solved + the 36 single-move states).
+        const state = createLegalRandomState(random);
+        if (!rejectTrivial || !isTrivialCube4State(state)) {
+            return state;
+        }
+    }
+    throw new Error("Unable to generate a non-trivial random 4x4 state.");
+}
+function createLegalRandomState(random) {
+    const cp = shuffledRange(CORNER_COUNT, random);
+    const wp = shuffledRange(WING_COUNT, random);
+    return {
+        cp,
+        co: randomOrientations(CORNER_COUNT, 3, random),
+        wp,
+        centers: shuffledCenters(random)
+    };
+}
+function shuffledRange(length, random) {
+    const values = Uint8Array.from({ length }, (_, index) => index);
+    for (let index = values.length - 1; index > 0; index -= 1) {
+        const swapIndex = random.nextInt(index + 1);
+        const temporary = values[index];
+        values[index] = values[swapIndex];
+        values[swapIndex] = temporary;
+    }
+    return values;
+}
+function randomOrientations(length, modulo, random) {
+    const orientations = new Uint8Array(length);
+    let total = 0;
+    for (let index = 0; index < length - 1; index += 1) {
+        const orientation = random.nextInt(modulo);
+        orientations[index] = orientation;
+        total += orientation;
+    }
+    orientations[length - 1] = (modulo - (total % modulo)) % modulo;
+    return orientations;
+}
+function shuffledCenters(random) {
+    const centers = new Uint8Array(CENTER_COUNT);
+    for (let face = 0; face < FACE_COUNT; face += 1) {
+        for (let index = 0; index < CENTERS_PER_FACE; index += 1) {
+            centers[face * CENTERS_PER_FACE + index] = face;
+        }
+    }
+    for (let index = centers.length - 1; index > 0; index -= 1) {
+        const swapIndex = random.nextInt(index + 1);
+        const temporary = centers[index];
+        centers[index] = centers[swapIndex];
+        centers[swapIndex] = temporary;
+    }
+    return centers;
+}

package/dist/puzzles/cube4/reduction/browser-loader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Browser loader for the cube4 reduction tables (the committed .bin files).
+ * The manifests are per-phase (`center1-manifest.json`, ...).
+ */
+import type { Center1Tables } from "./center1.js";
+import type { Center2Tables } from "./center2.js";
+import type { Center3Tables } from "./center3.js";
+import type { Edge3Tables } from "./edge3.js";
+export interface Cube4ReductionTables {
+    center1: Center1Tables;
+    center2: Center2Tables;
+    center3: Center3Tables;
+    edge3: Edge3Tables;
+}
+export declare function getCachedCube4Tables(): Cube4ReductionTables | undefined;
+export declare function clearCachedCube4Tables(): void;
+export declare function loadCube4ReductionTablesBrowser(baseUrl?: string): Promise<Cube4ReductionTables>;
+//# sourceMappingURL=browser-loader.d.ts.map

package/dist/puzzles/cube4/reduction/browser-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-loader.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/browser-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC;CACpB;AAOD,wBAAgB,oBAAoB,IAAI,oBAAoB,GAAG,SAAS,CAEvE;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAgBD,wBAAsB,+BAA+B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAarG"}

package/dist/puzzles/cube4/reduction/browser-loader.js

@@ -0,0 +1,95 @@
+/**
+ * Browser loader for the cube4 reduction tables (the committed .bin files).
+ * The manifests are per-phase (`center1-manifest.json`, ...).
+ */
+import { edge3DistanceLookup } from "./edge3.js";
+import { fetchTableBuffer } from "../../shared/compressed-fetch.js";
+const GENERATED_DIRECTORY = "puzzles/cube4/reduction/generated";
+const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
+let cachedTables;
+export function getCachedCube4Tables() {
+    return cachedTables;
+}
+export function clearCachedCube4Tables() {
+    cachedTables = undefined;
+}
+function resolveBaseUrl(provided) {
+    if (provided) {
+        return provided.replace(/\/$/, "");
+    }
+    if (typeof document !== "undefined") {
+        const script = document.currentScript;
+        if (script?.src) {
+            const base = new URL(".", script.src).href;
+            return base.replace(/\/$/, "");
+        }
+    }
+    return ".";
+}
+export async function loadCube4ReductionTablesBrowser(baseUrl) {
+    if (cachedTables) {
+        return cachedTables;
+    }
+    const resolved = resolveBaseUrl(baseUrl);
+    const [center1, center2, center3, edge3] = await Promise.all([
+        loadCenter1(resolved),
+        loadCenter2(resolved),
+        loadCenter3(resolved),
+        loadEdge3(resolved)
+    ]);
+    cachedTables = { center1, center2, center3, edge3 };
+    return cachedTables;
+}
+async function fetchJson(baseUrl, file) {
+    const url = `${baseUrl}/${GENERATED_DIRECTORY}/${file}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to load ${file}: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+async function loadCenter1(baseUrl) {
+    const manifest = await fetchJson(baseUrl, "center1-manifest.json");
+    const [distanceBuffer, moveMapsBuffer] = await Promise.all([
+        fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.distanceTable.file, { cacheName: CACHE_NAME, compressed: manifest.distanceTable.compressed !== false }),
+        fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.moveMaps.file, { cacheName: CACHE_NAME, compressed: manifest.moveMaps.compressed !== false })
+    ]);
+    return {
+        distance: new Uint8Array(distanceBuffer),
+        moveMaps: new Int32Array(moveMapsBuffer)
+    };
+}
+async function loadCenter2(baseUrl) {
+    const manifest = await fetchJson(baseUrl, "center2-manifest.json");
+    const [ctMoveBuffer, rlMoveBuffer, pruningBuffer] = await Promise.all([
+        fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.ctMove.file, { cacheName: CACHE_NAME, compressed: manifest.ctMove.compressed !== false }),
+        fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.rlMove.file, { cacheName: CACHE_NAME, compressed: manifest.rlMove.compressed !== false }),
+        fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.pruningTable.file, { cacheName: CACHE_NAME, compressed: manifest.pruningTable.compressed !== false })
+    ]);
+    const ctMove = new Int32Array(ctMoveBuffer);
+    const rlMove = new Int32Array(rlMoveBuffer);
+    const pruningPacked = new Uint8Array(pruningBuffer);
+    const pruning = new Uint8Array(450450);
+    for (let i = 0; i < 450450; i++) {
+        const byte = pruningPacked[i >> 1];
+        pruning[i] = (i & 1) === 0 ? byte & 0x0f : byte >> 4;
+    }
+    return { ctMove, rlMove, pruning };
+}
+async function loadCenter3(baseUrl) {
+    const manifest = await fetchJson(baseUrl, "center3-manifest.json");
+    const [moveTableBuffer, pruningBuffer] = await Promise.all([
+        fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.moveTable.file, { cacheName: CACHE_NAME, compressed: manifest.moveTable.compressed !== false }),
+        fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.pruningTable.file, { cacheName: CACHE_NAME, compressed: manifest.pruningTable.compressed !== false })
+    ]);
+    return {
+        moveTable: new Int32Array(moveTableBuffer),
+        pruning: new Uint8Array(pruningBuffer)
+    };
+}
+async function loadEdge3(baseUrl) {
+    const manifest = await fetchJson(baseUrl, "edge3-manifest.json");
+    const distancesBuffer = await fetchTableBuffer(baseUrl, GENERATED_DIRECTORY, manifest.distances.file, { cacheName: CACHE_NAME, compressed: manifest.distances.compressed !== false });
+    const distances = new Uint8Array(distancesBuffer);
+    return { distances, distanceOfEdge: edge3DistanceLookup(distances) };
+}

package/dist/puzzles/cube4/reduction/center1.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Center1 (phase 1 of the 4x4 reduction solver): reduce the two colors of a
+ * chosen axis (U/D, R/L or F/B) onto a single face-pair.
+ *
+ * Design (simpler than the reference's symmetry-reduced tables, which use a
+ * fragile 48-element non-group of "block-turn symmetries"):
+ *  - coordinate: the raw C(24,8) = 735,471 mask of the positions holding the
+ *    two axis colors — NO symmetry reduction;
+ *  - pruning: the exact BFS distance table from the three face-pair goal
+ *    masks (God's number 9; the 27-move set reaches the whole space);
+ *  - search: greedy descent — any move that decreases the exact distance by
+ *    exactly 1 is on an optimal path, so repeatedly applying the first such
+ *    move reaches the goal in exactly `distance` moves, with zero
+ *    backtracking and no iterative deepening.
+ *
+ * One table serves all three axes (the face-pairs are equivalent goals).
+ * The phase-1 move set: 9 axes [U,R,F,D,L,B,Uw,Rw,Fw] × 3 powers = 27.
+ */
+import type { Cube4Move } from "../types.js";
+export declare const CENTER1_AXES: readonly Cube4Move[];
+export declare const CENTER1_MOVES: readonly Cube4Move[];
+export declare const CENTER1_RAW_STATES = 735471;
+/** The mask of the positions holding the two axis colors (colors % 3 == urf). */
+export declare function center1Mask(centers: Uint8Array, urf: 0 | 1 | 2): number;
+/** C(24,8) combination rank of a mask. */
+export declare function rankCenter1Mask(mask: number): number;
+export declare function unrankCenter1Mask(idx: number): number;
+/** The three face-pair goal masks (bit i = center position i, face-major). */
+export declare const CENTER1_GOAL_MASKS: {
+    readonly ud: 61455;
+    readonly rl: 983280;
+    readonly fb: 15732480;
+};
+/** The 27 phase-1 moves as bit-permutations of the 24-bit mask. */
+export declare function buildCenter1MoveMaps(): Int32Array;
+export declare function applyCenter1Move(mask: number, moveMap: Int32Array, move: number): number;
+export interface Center1Tables {
+    /** Exact BFS distance per rank (nibble-packed, 4 bits per state). */
+    distance: Uint8Array;
+    /** The 27 move bit-permutations (24 entries per move). */
+    moveMaps: Int32Array;
+}
+export declare function generateCenter1Tables(): Center1Tables;
+export interface Center1Phase1Result {
+    /** Phase-1 solution moves (27-move set). */
+    moves: Cube4Move[];
+    /** Total move count. */
+    length: number;
+}
+export declare function getCenter1Distance(mask: number, tables: Center1Tables): number;
+/**
+ * Phase-1 greedy descent: bring the axis colors onto some face-pair in
+ * exactly `distance` moves (optimal). Every move that decreases the exact
+ * distance by 1 is on an optimal path, so no backtracking is needed.
+ * Returns null if the state is unreachable (should not happen).
+ */
+export declare function solveCenter1(centers: Uint8Array, urf: 0 | 1 | 2, tables: Center1Tables): Center1Phase1Result | null;
+/**
+ * Enumerate phase-1 solutions (the optimal descending paths, then longer
+ * alternatives up to `cap`). The phase-1 → phase-3 pipeline needs variety:
+ * the phase-2 gate rate depends strongly on the phase-1 output's wings.
+ */
+export declare function solveCenter1All(centers: Uint8Array, urf: 0 | 1 | 2, tables: Center1Tables, cap?: number): Center1Phase1Result[];
+export declare function verifyCenter1(tables: Center1Tables): string[];
+//# sourceMappingURL=center1.d.ts.map

package/dist/puzzles/cube4/reduction/center1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"center1.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/center1.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAO7C,eAAO,MAAM,YAAY,EAAE,SAAS,SAAS,EAE5C,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAE7C,CAAC;AAEF,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAoBzC,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAMvE;AAED,0CAA0C;AAC1C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOpD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAC;AAMX,mEAAmE;AACnE,wBAAgB,oBAAoB,IAAI,UAAU,CAejD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMxF;AAMD,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,EAAE,UAAU,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED,wBAAgB,qBAAqB,IAAI,aAAa,CAmDrD;AAMD,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GACpB,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EACd,MAAM,EAAE,aAAa,GACpB,mBAAmB,GAAG,IAAI,CAG5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EACd,MAAM,EAAE,aAAa,EACrB,GAAG,SAAK,GACP,mBAAmB,EAAE,CAyBvB;AAMD,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,EAAE,CA8B7D"}