@cubingcenter/scrambler 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# CubingCenter Scrambler
+
+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.
+
+## Status
+
+- Package: `@cubingcenter/scrambler`
+- Runtime: Node.js
+- Language: TypeScript
+- Package manager: pnpm
+- Registered events: `222`, `333`, `444`
+- Main technical modules: `cube2`, `cube3`, `cube4`
+- 2x2 quality: random-state target + optimal IDA* corner solver + verified scramble inversion
+- 3x3 quality: random-state target + two-phase solver + verified scramble inversion
+- 4x4 quality: reduced 4x4 random-state target + existing 3x3 two-phase finish; full center/wing random-state reduction is isolated under `cube4.reduction`
+
+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.
+
+## Install Locally
+
+From this repository:
+
+```sh
+pnpm install
+pnpm build
+pnpm package:check
+```
+
+From another local project, consume it through your workspace setup or a local path/tarball workflow. See [Getting Started](docs/getting-started.md) for practical options.
+
+## API Usage
+
+```ts
+import {
+  generateScramble,
+  generateScrambles,
+  getEventInfo,
+  getSupportedEvents
+} from "@cubingcenter/scrambler";
+
+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));
+```
+
+`generateScramble("222")` returns a legal random-state 2x2 scramble. Its metadata includes the target cubie state, timer-ready facelets, a 24-character facelet string, and solver diagnostics.
+
+`generateScramble("333")` returns a legal random-state 3x3 scramble. Its metadata includes the target cubie state, timer-ready facelets, a 54-character facelet string, and solver diagnostics.
+
+## 2x2 Technical Module
+
+```ts
+import { cube2 } from "@cubingcenter/scrambler";
+
+const solved = cube2.createSolvedCube2State();
+const moved = cube2.applyCube2Algorithm(solved, ["R", "U", "R'"]);
+const state = cube2.generateRandomCube2State({ seed: "demo" });
+const facelets = cube2.toCube2Facelets(state);
+const faceletString = cube2.formatCube2Facelets(facelets);
+const validation = cube2.validateCube2State(state);
+```
+
+`generateRandomCube2State` returns a legal cube state, not a scramble sequence.
+
+`toCube2Facelets` returns six faces with four stickers each in row-major order. The face order is `U R F D L B`. `formatCube2Facelets` produces a stable 24-character string for logs, tests, or timer previews.
+
+The `cube2.solver` namespace is exported for advanced tooling and validation. Normal consumers should prefer `generateScramble("222")`.
+
+## 3x3 Technical Module
+
+```ts
+import { cube3 } from "@cubingcenter/scrambler";
+
+const solved = cube3.createSolvedCube3State();
+const moved = cube3.applyCube3Algorithm(solved, ["R", "U", "R'"]);
+const state = cube3.generateRandomCube3State({ seed: "demo" });
+const facelets = cube3.toCube3Facelets(state);
+const faceletString = cube3.formatCube3Facelets(facelets);
+const validation = cube3.validateCube3State(state);
+```
+
+`generateRandomCube3State` returns a legal cube state, not a scramble sequence. It does not filter by visual appearance: blocks, repeated colors on a face, or recognizable patterns can still be valid if the cubie state is legal and non-trivial.
+
+`toCube3Facelets` returns six faces with nine stickers each in row-major order. The face order is `U R F D L B`. `formatCube3Facelets` produces a stable 54-character string for logs, tests, or timer previews.
+
+The `cube3.solver` namespace is exported for advanced tooling and validation. Normal consumers should prefer `generateScramble("333")`.
+
+## 4x4 Technical Module
+
+```ts
+import { cube4 } from "@cubingcenter/scrambler";
+
+const solved = cube4.createSolvedCube4State();
+const moved = cube4.applyCube4Algorithm(solved, ["R", "Uw", "Rw'"]);
+const state = cube4.generateRandomCube4State({ seed: 42 });
+const reduced = cube4.areCentersReduced(state);
+const paired = cube4.areWingsPaired(state);
+```
+
+`Cube4State` uses `Uint8Array` for all piece arrays: 8 corners (cp/co), 24 wings (wp), and 24 centers.
+
+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 `cube4.reduction` namespace is exported for advanced tooling. Normal consumers should prefer `generateScramble("444")`.
+
+## CLI
+
+```sh
+cubingcenter-scrambler --help
+cubingcenter-scrambler list
+cubingcenter-scrambler 222 --count 5
+cubingcenter-scrambler 222 --seed demo
+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`.
+
+When `--count` is used with `--seed`, each scramble derives a stable seed in the form `seed:index`. For example, `--seed demo --count 2` uses `demo:0` and `demo:1`.
+
+## Guides
+
+- [Getting Started](docs/getting-started.md)
+- [CubingCenter Integration](docs/cubingcenter-integration.md)
+- [Facelets](docs/facelets.md)
+- [Development](docs/development.md)
+
+## Examples
+
+- [ESM import](examples/esm.mjs)
+- [CommonJS require](examples/commonjs.cjs)
+- [Timer preview mapping](examples/timer-preview.mjs)
+- [CLI JSON shape](examples/cli-json.md)
+
+## Development
+
+```sh
+pnpm install
+pnpm lint
+pnpm test
+pnpm build
+pnpm package:check
+pnpm verify
+```
+
+Solver tables are versioned as generated binary assets. If cube coordinates, moves, or pruning logic change, regenerate and check them:
+
+```sh
+pnpm cube3:tables
+pnpm cube3:tables:check
+```

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from "./run.js";
+async function main() {
+    const result = await runCli(process.argv.slice(2), {
+        stdout: (text) => process.stdout.write(text),
+        stderr: (text) => process.stderr.write(text)
+    });
+    process.exitCode = result.exitCode;
+}
+main();

package/dist/cli/run.d.ts

@@ -0,0 +1,9 @@
+export interface CliIO {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export interface CliResult {
+    exitCode: number;
+}
+export declare function runCli(argv: string[], io: CliIO): Promise<CliResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAUD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAS1E"}

package/dist/cli/run.js

@@ -0,0 +1,139 @@
+import { generateScrambles, getSupportedEvents, ScramblerError } from "../index.js";
+export async function runCli(argv, io) {
+    try {
+        await run(parseArgs(argv), io);
+        return { exitCode: 0 };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        io.stderr(`${message}\n`);
+        return { exitCode: error instanceof ScramblerError ? 2 : 1 };
+    }
+}
+async function run(cliArgs, io) {
+    if (cliArgs.help || !cliArgs.command) {
+        printHelp(io);
+        return;
+    }
+    if (cliArgs.command === "list") {
+        printEvents(io);
+        return;
+    }
+    const scrambles = await generateScrambles(cliArgs.command, cliArgs.count, {
+        ...(cliArgs.seed === undefined ? {} : { seed: cliArgs.seed })
+    });
+    if (cliArgs.json) {
+        printJson(scrambles, io);
+        return;
+    }
+    for (const result of scrambles) {
+        io.stdout(`${result.scramble}\n`);
+    }
+}
+function printJson(scrambles, io) {
+    const serialized = scrambles.map(serializeScramble);
+    const output = serialized.length === 1 ? serialized[0] : serialized;
+    io.stdout(`${JSON.stringify(output, null, 2)}\n`);
+}
+function serializeScramble(result) {
+    const metadata = result.metadata ?? {};
+    const serialized = {
+        eventId: result.eventId,
+        scramble: result.scramble,
+        moves: result.moves,
+        quality: result.quality,
+        generator: result.generator
+    };
+    if (result.seed !== undefined) {
+        serialized.seed = result.seed;
+    }
+    if ("facelets" in metadata) {
+        serialized.facelets = metadata.facelets;
+    }
+    if ("faceletString" in metadata) {
+        serialized.faceletString = metadata.faceletString;
+    }
+    return serialized;
+}
+function printEvents(io) {
+    const events = getSupportedEvents();
+    if (events.length === 0) {
+        io.stdout("No scramble events are registered yet.\n");
+        return;
+    }
+    for (const event of events) {
+        io.stdout(`${event.eventId}\t${event.name}\t${event.quality}\n`);
+    }
+}
+function printHelp(io) {
+    io.stdout(`Usage:
+  cubingcenter-scrambler --help
+  cubingcenter-scrambler list
+  cubingcenter-scrambler <eventId> [--count N] [--seed value] [--json]
+
+Options:
+  --count, -c  Number of scrambles to generate. Defaults to 1.
+  --seed, -s   Seed value for reproducible generation when supported.
+  --json       Print structured JSON with metadata when available.
+  --help, -h   Show this help message.
+`);
+}
+function parseArgs(argv) {
+    const parsed = {
+        count: 1,
+        help: false,
+        json: false
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === undefined) {
+            continue;
+        }
+        if (value === "--help" || value === "-h") {
+            parsed.help = true;
+            continue;
+        }
+        if (value === "--json") {
+            parsed.json = true;
+            continue;
+        }
+        if (value === "--count" || value === "-c") {
+            parsed.count = parsePositiveInteger(readValue(argv, index, value));
+            index += 1;
+            continue;
+        }
+        if (value === "--seed" || value === "-s") {
+            parsed.seed = readValue(argv, index, value);
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--count=")) {
+            parsed.count = parsePositiveInteger(value.slice("--count=".length));
+            continue;
+        }
+        if (value.startsWith("--seed=")) {
+            parsed.seed = value.slice("--seed=".length);
+            continue;
+        }
+        if (!parsed.command) {
+            parsed.command = value;
+            continue;
+        }
+        throw new Error(`Unexpected argument: ${value}`);
+    }
+    return parsed;
+}
+function readValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith("-")) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return value;
+}
+function parsePositiveInteger(value) {
+    const count = Number(value);
+    if (!Number.isInteger(count) || count < 1) {
+        throw new Error(`Count must be a positive integer. Received: ${value}`);
+    }
+    return count;
+}

package/dist/core/api.d.ts

@@ -0,0 +1,19 @@
+import type { EventId, EventInfo, ScrambleGenerator, ScrambleOptions, ScrambleResult, ScramblerRegistry } from "./types.js";
+/**
+ * Pre-load solver tables in browser environments.
+ * In Node.js this is a no-op (tables are read lazily from the filesystem).
+ *
+ * @param baseUrl - Base URL where the `puzzles/cube3/solver/generated/`
+ *   assets are served. If omitted, defaults to the current document base URL
+ *   or `"."`. In a Next.js app you typically copy the `.bin` files to
+ *   `public/scrambler-tables/` and pass `"/scrambler-tables"`.
+ * @param eventId - Optional event ID to selectively load tables. If omitted,
+ *   loads all standard tables.
+ */
+export declare function initializeScrambler(baseUrl?: string, eventId?: EventId | string): Promise<void>;
+export declare function registerScrambleGenerator(generator: ScrambleGenerator, registry?: ScramblerRegistry): void;
+export declare function getSupportedEvents(registry?: ScramblerRegistry): EventInfo[];
+export declare function getEventInfo(eventId: EventId, registry?: ScramblerRegistry): EventInfo;
+export declare function generateScramble(eventId: EventId, options?: ScrambleOptions, registry?: ScramblerRegistry): Promise<ScrambleResult>;
+export declare function generateScrambles(eventId: EventId, count: number, options?: ScrambleOptions, registry?: ScramblerRegistry): Promise<ScrambleResult[]>;
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +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;AAIpB;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrG;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

@@ -0,0 +1,94 @@
+import { GeneratorFailedError, InvalidCountError, UnsupportedEventError } from "./errors.js";
+import { defaultRegistry } from "./registry.js";
+import { loadBrowserTables as loadCube2BrowserTables } from "../puzzles/cube2/solver/browser-loader.js";
+import { loadBrowserTables as loadCube3BrowserTables } from "../puzzles/cube3/solver/browser-loader.js";
+/**
+ * Pre-load solver tables in browser environments.
+ * In Node.js this is a no-op (tables are read lazily from the filesystem).
+ *
+ * @param baseUrl - Base URL where the `puzzles/cube3/solver/generated/`
+ *   assets are served. If omitted, defaults to the current document base URL
+ *   or `"."`. In a Next.js app you typically copy the `.bin` files to
+ *   `public/scrambler-tables/` and pass `"/scrambler-tables"`.
+ * @param eventId - Optional event ID to selectively load tables. If omitted,
+ *   loads all standard tables.
+ */
+export async function initializeScrambler(baseUrl, eventId) {
+    if (typeof self === "undefined") {
+        // Node.js — tables are loaded on-demand from the filesystem
+        return;
+    }
+    if (eventId === "222" || eventId === "222so") {
+        await loadCube2BrowserTables(baseUrl);
+    }
+    else if (eventId === "333") {
+        await loadCube3BrowserTables(baseUrl);
+    }
+    else if (!eventId) {
+        await Promise.all([
+            loadCube2BrowserTables(baseUrl),
+            loadCube3BrowserTables(baseUrl)
+        ]);
+    }
+}
+export function registerScrambleGenerator(generator, registry = defaultRegistry) {
+    registry.register(generator);
+}
+export function getSupportedEvents(registry = defaultRegistry) {
+    return registry.list();
+}
+export function getEventInfo(eventId, registry = defaultRegistry) {
+    const generator = registry.get(eventId);
+    if (!generator) {
+        throw new UnsupportedEventError(eventId);
+    }
+    return { ...generator.info };
+}
+export async function generateScramble(eventId, options = {}, registry = defaultRegistry) {
+    const generator = registry.get(eventId);
+    if (!generator) {
+        throw new UnsupportedEventError(eventId);
+    }
+    try {
+        const result = await generator.generate(options);
+        return normalizeResult(eventId, result, options);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name.endsWith("Error")) {
+            throw error;
+        }
+        throw new GeneratorFailedError(eventId, error);
+    }
+}
+export async function generateScrambles(eventId, count, options = {}, registry = defaultRegistry) {
+    if (!Number.isInteger(count) || count < 1) {
+        throw new InvalidCountError(count);
+    }
+    return Promise.all(Array.from({ length: count }, (_, index) => (generateScramble(eventId, deriveBatchScrambleOptions(options, index, count), registry))));
+}
+function deriveBatchScrambleOptions(options, index, count) {
+    if (count === 1 || options.seed === undefined) {
+        return options;
+    }
+    return {
+        ...options,
+        seed: `${options.seed}:${index}`
+    };
+}
+function normalizeResult(requestedEventId, result, options) {
+    const moves = result.moves.length > 0 ? result.moves : splitMoves(result.scramble);
+    const seed = result.seed ?? options.seed;
+    const normalized = {
+        ...result,
+        eventId: result.eventId || requestedEventId,
+        moves
+    };
+    if (seed !== undefined) {
+        normalized.seed = seed;
+    }
+    return normalized;
+}
+function splitMoves(scramble) {
+    const trimmed = scramble.trim();
+    return trimmed.length === 0 ? [] : trimmed.split(/\s+/);
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,21 @@
+import type { EventId } from "./types.js";
+export declare class ScramblerError extends Error {
+    constructor(message: string);
+}
+export declare class UnsupportedEventError extends ScramblerError {
+    readonly eventId: EventId;
+    constructor(eventId: EventId);
+}
+export declare class InvalidCountError extends ScramblerError {
+    readonly count: number;
+    constructor(count: number);
+}
+export declare class InvalidOptionsError extends ScramblerError {
+    constructor(message: string);
+}
+export declare class GeneratorFailedError extends ScramblerError {
+    readonly eventId: EventId;
+    readonly cause: unknown;
+    constructor(eventId: EventId, cause: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,EAAE,OAAO;CAI7B;AAED,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM;CAI1B;AAED,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO;CAK7C"}

package/dist/core/errors.js

@@ -0,0 +1,34 @@
+export class ScramblerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class UnsupportedEventError extends ScramblerError {
+    eventId;
+    constructor(eventId) {
+        super(`Unsupported scramble event: ${eventId}`);
+        this.eventId = eventId;
+    }
+}
+export class InvalidCountError extends ScramblerError {
+    count;
+    constructor(count) {
+        super(`Scramble count must be a positive integer. Received: ${count}`);
+        this.count = count;
+    }
+}
+export class InvalidOptionsError extends ScramblerError {
+    constructor(message) {
+        super(message);
+    }
+}
+export class GeneratorFailedError extends ScramblerError {
+    eventId;
+    cause;
+    constructor(eventId, cause) {
+        super(`Scramble generator failed for event: ${eventId}`);
+        this.eventId = eventId;
+        this.cause = cause;
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+export { GeneratorFailedError, InvalidCountError, InvalidOptionsError, ScramblerError, UnsupportedEventError } from "./errors.js";
+export { DefaultScramblerRegistry, defaultRegistry } from "./registry.js";
+export { generateScramble, generateScrambles, getEventInfo, getSupportedEvents, initializeScrambler, registerScrambleGenerator } from "./api.js";
+export type { EventId, EventInfo, ScrambleGenerator, ScrambleOptions, ScrambleQuality, ScrambleResult, ScramblerRegistry } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,wBAAwB,EACxB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EAC1B,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EAClB,MAAM,YAAY,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export { GeneratorFailedError, InvalidCountError, InvalidOptionsError, ScramblerError, UnsupportedEventError } from "./errors.js";
+export { DefaultScramblerRegistry, defaultRegistry } from "./registry.js";
+export { generateScramble, generateScrambles, getEventInfo, getSupportedEvents, initializeScrambler, registerScrambleGenerator } from "./api.js";

package/dist/core/registry.d.ts

@@ -0,0 +1,10 @@
+import type { EventId, EventInfo, ScrambleGenerator, ScramblerRegistry } from "./types.js";
+export declare class DefaultScramblerRegistry implements ScramblerRegistry {
+    private readonly generators;
+    register(generator: ScrambleGenerator): void;
+    get(eventId: EventId): ScrambleGenerator | undefined;
+    has(eventId: EventId): boolean;
+    list(): EventInfo[];
+}
+export declare const defaultRegistry: DefaultScramblerRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG3F,qBAAa,wBAAyB,YAAW,iBAAiB;IAChE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IAEpE,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAK5C,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS;IAIpD,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAI9B,IAAI,IAAI,SAAS,EAAE;CAKpB;AAED,eAAO,MAAM,eAAe,0BAAiC,CAAC"}

package/dist/core/registry.js

@@ -0,0 +1,35 @@
+import { InvalidOptionsError } from "./errors.js";
+export class DefaultScramblerRegistry {
+    generators = new Map();
+    register(generator) {
+        validateGenerator(generator);
+        this.generators.set(generator.info.eventId, generator);
+    }
+    get(eventId) {
+        return this.generators.get(eventId);
+    }
+    has(eventId) {
+        return this.generators.has(eventId);
+    }
+    list() {
+        return Array.from(this.generators.values())
+            .map((generator) => ({ ...generator.info }))
+            .sort((left, right) => left.eventId.localeCompare(right.eventId));
+    }
+}
+export const defaultRegistry = new DefaultScramblerRegistry();
+function validateGenerator(generator) {
+    const { info } = generator;
+    if (!info.eventId.trim()) {
+        throw new InvalidOptionsError("Scramble generator eventId cannot be empty.");
+    }
+    if (!info.name.trim()) {
+        throw new InvalidOptionsError(`Scramble generator ${info.eventId} must have a name.`);
+    }
+    if (!info.puzzle.trim()) {
+        throw new InvalidOptionsError(`Scramble generator ${info.eventId} must have a puzzle name.`);
+    }
+    if (!info.generator.trim()) {
+        throw new InvalidOptionsError(`Scramble generator ${info.eventId} must have a generator id.`);
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,34 @@
+export type EventId = string;
+export type ScrambleQuality = "random-state" | "random-move" | "training" | "placeholder";
+export interface ScrambleOptions {
+    seed?: string | number;
+    metadata?: Record<string, unknown>;
+}
+export interface ScrambleResult {
+    eventId: EventId;
+    scramble: string;
+    moves: string[];
+    quality: ScrambleQuality;
+    generator: string;
+    seed?: string | number;
+    metadata?: Record<string, unknown>;
+}
+export interface EventInfo {
+    eventId: EventId;
+    name: string;
+    puzzle: string;
+    quality: ScrambleQuality;
+    generator: string;
+    description?: string;
+}
+export interface ScrambleGenerator {
+    info: EventInfo;
+    generate(options?: ScrambleOptions): ScrambleResult | Promise<ScrambleResult>;
+}
+export interface ScramblerRegistry {
+    register(generator: ScrambleGenerator): void;
+    get(eventId: EventId): ScrambleGenerator | undefined;
+    list(): EventInfo[];
+    has(eventId: EventId): boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,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;CACpC;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/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core/index.js";
+export * from "./puzzles/index.js";
+export * from "./random/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./core/index.js";
+export * from "./puzzles/index.js";
+export * from "./random/index.js";

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

@@ -0,0 +1,2 @@
+export { clockScrambleGenerator, generateClockScramble } from "./scrambler.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/puzzles/clock/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC"}

package/dist/puzzles/clock/index.js

@@ -0,0 +1 @@
+export { clockScrambleGenerator, generateClockScramble } from "./scrambler.js";

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

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