@wodzik/cubecore 0.1.0

package/solve/lse.js

@@ -0,0 +1,151 @@
+/**
+ * Last-six-edges solver (Roux 4a–4c): M and U moves only, with the blocks
+ * and CMLL solved. Small enough for an exact table: breadth-first from the
+ * stage's goal states over what the stage is about (for EOLR: orientation
+ * of the six edges, where UL / UR are, centres, corner AUF — ~15 000
+ * combinations), keeping one state of each as a trainer case.
+ *
+ * States are read with the blocks at home: a smart cube reports an M as
+ * R L' with the centres fixed, which to the solver looks like the whole
+ * cube turned by x — so the state is first turned back by x^k until the
+ * blocks are home (the centres then show the M offset, as on the real cube).
+ */
+import { CORNER_FACELETS, EDGE_FACELETS, IDENTITY_FRAME, applyMove, applyMoves, parseAlg, reframe, solvedState, unreframe, } from "../core/index.js";
+const LSE_MOVES = parseAlg("U U2 U' M M2 M'");
+const X_TURNS = ["", "x", "x2", "x'"];
+/** Edges the M / U moves never touch (DR DL FR FL BL BR) and the D corners — the blocks. */
+const BLOCK_FACELETS = [4, 6, 8, 9, 10, 11].flatMap((e) => EDGE_FACELETS[e]).concat([4, 5, 6, 7].flatMap((c) => CORNER_FACELETS[c]));
+/** Six LSE edge positions: UF UB DF DB UL UR. */
+const LSE_SLOTS = [1, 3, 5, 7, 2, 0];
+const REFERENCE = new Set(EDGE_FACELETS.map((f) => f[0]));
+const UL = new Set(EDGE_FACELETS[2]), UR = new Set(EDGE_FACELETS[0]);
+const CENTRES = [4, 13, 22, 31, 40, 49];
+const U_CORNERS = [0, 1, 2, 3].flatMap((c) => CORNER_FACELETS[c]);
+/** The state turned by x^k so the blocks are home, or null if they aren't solved. */
+function blocksHome(state) {
+    for (const x of X_TURNS) {
+        const t = x ? applyMoves(state, x) : state;
+        if (BLOCK_FACELETS.every((f) => t[f] === f))
+            return t;
+    }
+    return null;
+}
+/** Every LSE detail of a blocks-home state: each of the six edges' place and flip, centres, corner AUF. */
+function lseKey(s) {
+    const edges = LSE_SLOTS.map((j) => `${s[EDGE_FACELETS[j][0]]}`).join(".");
+    return `${edges}|${CENTRES.map((c) => s[c]).join(".")}|${U_CORNERS.map((f) => s[f]).join(".")}`;
+}
+/** EOLR features of a blocks-home state. */
+function eolrKey(s) {
+    const eo = LSE_SLOTS.map((j) => (REFERENCE.has(s[EDGE_FACELETS[j][0]]) ? 0 : 1)).join("");
+    const at = (piece) => LSE_SLOTS.findIndex((j) => piece.has(s[EDGE_FACELETS[j][0]]));
+    return `${eo}|${at(UL)}${at(UR)}|${CENTRES.map((c) => s[c]).join(".")}|${U_CORNERS.map((f) => s[f]).join(".")}`;
+}
+export class LseSolver {
+    def;
+    key;
+    /** feature → distance and one state with those features */
+    table = new Map();
+    byDepth = [];
+    constructor(def) {
+        this.def = def;
+        this.key = def.features === "lse" ? lseKey : eolrKey;
+        const keyFn = this.key;
+        let frontier = [];
+        for (const g of def.goals) {
+            const s = applyMoves(solvedState(), g);
+            const k = keyFn(s);
+            if (!this.table.has(k)) {
+                this.table.set(k, { d: 0, state: s });
+                frontier.push(s);
+            }
+        }
+        for (let d = 0; frontier.length; d++) {
+            this.byDepth[d] = frontier;
+            const next = [];
+            for (const s of frontier) {
+                for (const m of LSE_MOVES) {
+                    const t = applyMove(s, m);
+                    const k = keyFn(t);
+                    if (!this.table.has(k)) {
+                        this.table.set(k, { d: d + 1, state: t });
+                        next.push(t);
+                    }
+                }
+            }
+            frontier = next;
+        }
+    }
+    /** Deepest level. */
+    get maxDepth() {
+        return this.byDepth.length - 1;
+    }
+    canonical(state, frame) {
+        return blocksHome(frame === IDENTITY_FRAME ? state : reframe(state, frame));
+    }
+    /** Fewest M / U moves to the stage (−1 if the blocks and CMLL aren't solved). */
+    distance(state, options = {}) {
+        const s = this.canonical(state, options.frame ?? IDENTITY_FRAME);
+        return s ? (this.table.get(this.key(s))?.d ?? -1) : -1;
+    }
+    /** Optimal solutions in M and U moves (every one with `all`). */
+    solve(state, options = {}) {
+        const start = this.canonical(state, options.frame ?? IDENTITY_FRAME);
+        if (!start)
+            return [];
+        const d0 = this.table.get(this.key(start))?.d;
+        if (d0 === undefined)
+            return [];
+        const limit = options.all ? (options.limit ?? 256) : 1;
+        const out = [];
+        const walk = (s, d, path) => {
+            if (out.length >= limit)
+                return;
+            if (d === 0)
+                return void out.push([...path]);
+            for (const m of LSE_MOVES) {
+                if (path.length && path[path.length - 1].family === m.family)
+                    continue;
+                const t = applyMove(s, m);
+                if (this.table.get(this.key(t))?.d === d - 1)
+                    walk(t, d - 1, [...path, m]);
+            }
+        };
+        walk(start, d0, []);
+        return out;
+    }
+    nextMoves(state, options = {}) {
+        const seen = new Map();
+        for (const s of this.solve(state, { ...options, all: true }))
+            if (s[0])
+                seen.set(`${s[0].family}${s[0].amount}`, s[0]);
+        return [...seen.values()];
+    }
+    /**
+     * A case exactly `depth` M / U moves from the stage, as a state a cube
+     * can show with its centres home (turned by x when the case has the M
+     * slice off) — ready for a scramble. `frame` puts it on another face.
+     */
+    sampleState(depth, random = Math.random, frame = IDENTITY_FRAME) {
+        const level = this.byDepth[depth];
+        if (!level?.length)
+            return null;
+        let s = level[Math.floor(random() * level.length)];
+        for (const x of X_TURNS) {
+            const t = x ? applyMoves(s, x) : s;
+            if (CENTRES.every((c) => t[c] === c)) {
+                s = t;
+                break;
+            }
+        }
+        return frame === IDENTITY_FRAME ? s : unreframe(s, frame);
+    }
+}
+const lseSolvers = new Map();
+export function lseSolver(def) {
+    const key = JSON.stringify(def);
+    let s = lseSolvers.get(key);
+    if (!s)
+        lseSolvers.set(key, (s = new LseSolver(def)));
+    return s;
+}

package/solve/pieces.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The cube as pieces for the solvers: Kociemba corner / edge permutation +
+ * orientation (core cubies.ts numbering), the 18 face turns as such piece
+ * permutations (derived from cubecore's move geometry), and composition.
+ */
+import { type Move } from "../core/index.js";
+export interface CC {
+    cp: number[];
+    co: number[];
+    ep: number[];
+    eo: number[];
+}
+/** The 18 face turns, index = face × 3 + (0: quarter, 1: half, 2: prime). */
+export declare const MOVES: readonly Move[];
+/** Pieces after `b` is applied to `a`. */
+export declare function mul(a: CC, b: CC): CC;
+export declare const SOLVED_CC: CC;
+export declare const MOVE_CC: CC[];

package/solve/pieces.js

@@ -0,0 +1,24 @@
+/**
+ * The cube as pieces for the solvers: Kociemba corner / edge permutation +
+ * orientation (core cubies.ts numbering), the 18 face turns as such piece
+ * permutations (derived from cubecore's move geometry), and composition.
+ */
+import { applyMove, solvedState, toCubies } from "../core/index.js";
+const FACE_ORDER = ["U", "R", "F", "D", "L", "B"];
+/** The 18 face turns, index = face × 3 + (0: quarter, 1: half, 2: prime). */
+export const MOVES = FACE_ORDER.flatMap((family) => [1, 2, -1].map((amount) => ({ family, amount })));
+/** Pieces after `b` is applied to `a`. */
+export function mul(a, b) {
+    return {
+        cp: b.cp.map((p) => a.cp[p]),
+        co: b.cp.map((p, i) => (a.co[p] + b.co[i]) % 3),
+        ep: b.ep.map((p) => a.ep[p]),
+        eo: b.ep.map((p, i) => (a.eo[p] + b.eo[i]) % 2),
+    };
+}
+export const SOLVED_CC = { cp: [0, 1, 2, 3, 4, 5, 6, 7], co: new Array(8).fill(0), ep: Array.from({ length: 12 }, (_, i) => i), eo: new Array(12).fill(0) };
+// Each move as pieces, derived from cubecore's own move geometry (no hand-typed tables).
+export const MOVE_CC = MOVES.map((m) => {
+    const c = toCubies(applyMove(solvedState(), m));
+    return { cp: c.cp, co: c.co, ep: c.ep, eo: c.eo };
+});

package/solve/protocol.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Messages between the solver worker and its client. Everything is plain
+ * data (structured-clone friendly): frames travel as their FRAMES id, a
+ * random source as a seed, stages as StageDef data.
+ */
+import type { Move, Piece, State } from "../core/index.js";
+import type { ScramblePreset } from "./scramble.js";
+import type { AnyStageDef as StageDef } from "../core/index.js";
+export interface Seeded {
+    /** Seed for reproducible results; omitted = Math.random. */
+    seed?: number;
+    /** FRAMES id (0 = canonical). */
+    frameId?: number;
+    from?: State;
+    maxLength?: number;
+    timeoutMs?: number;
+}
+export type Request = {
+    op: "warmUp";
+    stages: StageDef[];
+} | {
+    op: "solve";
+    state: State;
+    maxLength?: number;
+    timeoutMs?: number;
+} | {
+    op: "solveBetween";
+    from: State;
+    to: State;
+    maxLength?: number;
+} | ({
+    op: "randomScramble";
+    preset?: ScramblePreset;
+    keep?: Piece[];
+} & Seeded) | ({
+    op: "stageScramble";
+    stage: StageDef;
+    length: number;
+} & Seeded) | {
+    op: "stageSolve";
+    stage: StageDef;
+    state: State;
+    frameId?: number;
+    all?: boolean;
+    limit?: number;
+} | {
+    op: "stageDistance";
+    stage: StageDef;
+    state: State;
+    frameId?: number;
+};
+export type Response = {
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+export interface Envelope {
+    id: number;
+    request: Request;
+}
+export type ScrambleResult = {
+    moves: Move[];
+    state: State;
+};
+/** A small seeded generator (mulberry32). */
+export declare function seededRandom(seed: number): () => number;

package/solve/protocol.js

@@ -0,0 +1,16 @@
+/**
+ * Messages between the solver worker and its client. Everything is plain
+ * data (structured-clone friendly): frames travel as their FRAMES id, a
+ * random source as a seed, stages as StageDef data.
+ */
+/** A small seeded generator (mulberry32). */
+export function seededRandom(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/solve/scramble.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Random-state scrambles: draw a random reachable state (optionally with
+ * some pieces kept solved or oriented), solve it with the two-phase solver,
+ * and use the inverse of the solution — every state is equally likely, like
+ * WCA scrambles.
+ *
+ * Constraints are written for the canonical frame (first layer D, last layer
+ * U, Roux blocks on L/R), so presets read naturally; `frame` then puts the
+ * same case on any face — colour neutral, e.g. "LL scramble with the cross
+ * on white": `randomScramble({ preset: "ll", frame: frameFor("U") })`.
+ */
+import { type Cubie, type AnyStageDef, type Piece, type Frame, type Move, type State } from "../core/index.js";
+import { type Placement } from "./stage.js";
+import { type SolveOptions, TwoPhase } from "./twophase.js";
+export type PiecePredicate = (cubie: Cubie) => boolean;
+export interface RandomStateOptions {
+    /** Pieces kept solved (in place, oriented). */
+    solved?: PiecePredicate;
+    /** Pieces put exactly here (e.g. a cross sampled at a given distance), and optionally all edges' orientation. */
+    place?: Placement;
+    /** Pieces kept oriented, but permuted among themselves. */
+    oriented?: PiecePredicate;
+    /** Random source in [0, 1). Default Math.random. */
+    random?: () => number;
+}
+/** A predicate for `solved` / `oriented`: exactly these pieces (Kociemba ids, canonical positions). */
+export declare function piecesPredicate(pieces: readonly Piece[]): PiecePredicate;
+/** A uniformly random reachable state (centres at home) honouring the constraints. */
+export declare function randomState(options?: RandomStateOptions): State;
+export type ScramblePreset = "full" | "f2l" | "ls" | "ll" | "zbll" | "pll" | "ell" | "cmll";
+export declare const SCRAMBLE_PRESETS: Record<ScramblePreset, {
+    label: string;
+    solved?: PiecePredicate;
+    oriented?: PiecePredicate;
+}>;
+export interface ScrambleOptions extends RandomStateOptions, SolveOptions {
+    preset?: ScramblePreset;
+    /** More pieces kept solved on top of the preset's (e.g. the F2L slots not being practised). */
+    keep?: readonly Piece[];
+    /** Put the case on another face: canonical D (cross / first block bottom) goes to `frame.face.D`. */
+    frame?: Frame;
+    /** A solver to reuse (default: one shared instance, built on first use). */
+    solver?: TwoPhase;
+    /**
+     * Where the cube is now (e.g. a smart cube's state after the last attempt):
+     * the scramble then goes from here to the random target — no need to solve
+     * the cube first. Default: solved.
+     */
+    from?: State;
+}
+/** The shared solver (tables built on first call, about half a second). */
+export declare const sharedSolver: () => TwoPhase;
+/** A random-state scramble: the moves, and the state they lead to (from `from`, default solved). */
+export declare function randomScramble(options?: ScrambleOptions): {
+    moves: Move[];
+    state: State;
+};
+/** Moves from `options.from` (default solved) to `target`; null if the solver gave up or there is nothing to do. */
+export declare function scrambleTo(target: State, options?: Pick<ScrambleOptions, "from" | "solver" | "maxLength" | "timeoutMs">): {
+    moves: Move[];
+    state: State;
+} | null;
+export interface StageScrambleOptions extends Omit<ScrambleOptions, "preset" | "solved" | "oriented" | "place"> {
+    /** The stage (piece stages, or a last-six-edges stage like EOLR) and how many moves its optimal solution must take. */
+    stage: AnyStageDef;
+    length: number;
+}
+/**
+ * A trainer scramble: a random-state scramble whose `stage` (cross, xcross,
+ * EOCross…) takes exactly `length` moves at best — on any face (`frame`),
+ * from wherever the cube is (`from`). Null if no such case was found.
+ */
+export declare function stageScramble(options: StageScrambleOptions): {
+    moves: Move[];
+    state: State;
+} | null;

package/solve/scramble.js

@@ -0,0 +1,187 @@
+/**
+ * Random-state scrambles: draw a random reachable state (optionally with
+ * some pieces kept solved or oriented), solve it with the two-phase solver,
+ * and use the inverse of the solution — every state is equally likely, like
+ * WCA scrambles.
+ *
+ * Constraints are written for the canonical frame (first layer D, last layer
+ * U, Roux blocks on L/R), so presets read naturally; `frame` then puts the
+ * same case on any face — colour neutral, e.g. "LL scramble with the cross
+ * on white": `randomScramble({ preset: "ll", frame: frameFor("U") })`.
+ */
+import { CORNER_FACELETS, CUBIE_OF_FACELET, EDGE_FACELETS, IDENTITY_FRAME, applyMoves, fromCubies, isLseStage, parity, solvedState, unreframe, } from "../core/index.js";
+import { flipBits, setRandomStateHook, stageSolver } from "./stage.js";
+import { lseSolver } from "./lse.js";
+import { TwoPhase } from "./twophase.js";
+const cornerCubie = (j) => CUBIE_OF_FACELET[CORNER_FACELETS[j][0]];
+const edgeCubie = (j) => CUBIE_OF_FACELET[EDGE_FACELETS[j][0]];
+function shuffle(items, random) {
+    for (let i = items.length - 1; i > 0; i--) {
+        const j = Math.floor(random() * (i + 1));
+        [items[i], items[j]] = [items[j], items[i]];
+    }
+    return items;
+}
+/** A predicate for `solved` / `oriented`: exactly these pieces (Kociemba ids, canonical positions). */
+export function piecesPredicate(pieces) {
+    const cubies = new Set(pieces.map((p) => (p.kind === "edge" ? edgeCubie(p.id) : cornerCubie(p.id))));
+    return (c) => cubies.has(c);
+}
+/** A uniformly random reachable state (centres at home) honouring the constraints. */
+export function randomState(options = {}) {
+    const random = options.random ?? Math.random;
+    const solved = options.solved ?? (() => false);
+    const oriented = options.oriented ?? (() => false);
+    const placed = { edge: new Map(), corner: new Map() };
+    for (const [piece, value] of options.place?.pieces ?? [])
+        placed[piece.kind].set(piece.id, value);
+    const flip = options.place?.flip;
+    const place = (kind, n, cubieOf, twists) => {
+        const perm = new Array(n).fill(-1);
+        const ori = new Array(n).fill(0);
+        const taken = new Set();
+        // Placed pieces, then solved ones, at their fixed positions.
+        for (const [id, value] of placed[kind]) {
+            const pos = Math.floor(value / twists);
+            perm[pos] = id;
+            ori[pos] = value % twists;
+            taken.add(id);
+        }
+        for (let j = 0; j < n; j++) {
+            if (taken.has(j) || !solved(cubieOf(j)))
+                continue;
+            perm[j] = j;
+            taken.add(j);
+        }
+        const free = perm.map((p, pos) => (p < 0 ? pos : -1)).filter((pos) => pos >= 0);
+        const pieces = shuffle(Array.from({ length: n }, (_, j) => j).filter((j) => !taken.has(j)), random);
+        free.forEach((pos, k) => (perm[pos] = pieces[k]));
+        if (kind === "edge" && flip !== undefined) {
+            const eo = flipBits(flip);
+            free.forEach((pos) => (ori[pos] = eo[pos]));
+        }
+        else {
+            // Pieces free to twist / flip; the last of them absorbs the sum rule.
+            const turnable = free.filter((pos) => !oriented(cubieOf(perm[pos])));
+            for (const pos of turnable)
+                ori[pos] = Math.floor(random() * twists);
+            if (turnable.length) {
+                const last = turnable[turnable.length - 1];
+                const rest = ori.reduce((a, b, i) => (i === last ? a : a + b), 0);
+                ori[last] = (twists - (rest % twists)) % twists;
+            }
+        }
+        return { perm, ori, free };
+    };
+    const corners = place("corner", 8, cornerCubie, 3);
+    const edges = place("edge", 12, edgeCubie, 2);
+    // Permutation parities must match: swap two free edges (or corners) if they don't.
+    if (parity(corners.perm) !== parity(edges.perm)) {
+        const swap = (p) => {
+            const [a, b] = p.free;
+            [p.perm[a], p.perm[b]] = [p.perm[b], p.perm[a]];
+            [p.ori[a], p.ori[b]] = [p.ori[b], p.ori[a]];
+        };
+        if (edges.free.length >= 2)
+            swap(edges);
+        else if (corners.free.length >= 2)
+            swap(corners);
+    }
+    return fromCubies({ frame: IDENTITY_FRAME, cp: corners.perm, co: corners.ori, ep: edges.perm, eo: edges.ori });
+}
+// ─── presets (canonical: first layer D, last layer U; Roux blocks on L/R) ───
+const y = (c) => c.pos[1];
+const isCrossEdge = (c) => c.kind === "edge" && y(c) === -1;
+const inF2L = (c) => y(c) <= 0;
+const inFR = (c) => c.pos[0] === 1 && c.pos[2] === 1 && y(c) <= 0;
+export const SCRAMBLE_PRESETS = {
+    full: { label: "Random state" },
+    f2l: { label: "F2L (cross solved)", solved: isCrossEdge },
+    ls: { label: "Last slot (FR) + last layer", solved: (c) => inF2L(c) && !inFR(c) },
+    ll: { label: "Last layer (OLL + PLL)", solved: inF2L },
+    zbll: { label: "ZBLL (last-layer edges oriented)", solved: inF2L, oriented: (c) => c.kind === "edge" },
+    pll: { label: "PLL (last layer oriented)", solved: inF2L, oriented: () => true },
+    ell: { label: "ELL (corners solved)", solved: (c) => inF2L(c) || c.kind === "corner" },
+    cmll: { label: "CMLL (Roux blocks solved)", solved: (c) => c.pos[0] !== 0 && y(c) <= 0 },
+};
+let shared = null;
+/** The shared solver (tables built on first call, about half a second). */
+export const sharedSolver = () => (shared ??= TwoPhase.create());
+/** A random-state scramble: the moves, and the state they lead to (from `from`, default solved). */
+export function randomScramble(options = {}) {
+    const preset = SCRAMBLE_PRESETS[options.preset ?? "full"];
+    for (;;) {
+        const base = options.solved ?? preset.solved;
+        const extra = options.keep?.length ? piecesPredicate(options.keep) : null;
+        const solved = extra ? (c) => extra(c) || (base?.(c) ?? false) : base;
+        let target = randomState({ solved, oriented: options.oriented ?? preset.oriented, random: options.random });
+        if (options.frame && options.frame !== IDENTITY_FRAME)
+            target = unreframe(target, options.frame);
+        const result = scrambleTo(target, options);
+        if (result)
+            return result;
+    }
+}
+/** Moves from `options.from` (default solved) to `target`; null if the solver gave up or there is nothing to do. */
+export function scrambleTo(target, options = {}) {
+    const solver = options.solver ?? sharedSolver();
+    const from = options.from ?? solvedState();
+    const moves = solver.solveBetween(from, target, options);
+    if (!moves || !moves.length)
+        return null;
+    return { moves, state: applyMoves(from, moves) };
+}
+/**
+ * A trainer scramble: a random-state scramble whose `stage` (cross, xcross,
+ * EOCross…) takes exactly `length` moves at best — on any face (`frame`),
+ * from wherever the cube is (`from`). Null if no such case was found.
+ */
+export function stageScramble(options) {
+    const def = options.stage;
+    if (isLseStage(def)) {
+        // Last six edges: a case from the exact table (blocks and CMLL solved), put on the requested face.
+        const lse = lseSolver(def);
+        for (let attempt = 0; attempt < 20; attempt++) {
+            const target = lse.sampleState(options.length, options.random, options.frame);
+            if (!target)
+                return null;
+            const result = scrambleTo(target, options);
+            if (result && lse.distance(result.state, { frame: options.frame }) === options.length)
+                return result;
+        }
+        return null;
+    }
+    const solver = stageSolver(def);
+    // A rare level can miss once; a level that doesn't exist misses every time — give up after three.
+    let misses = 0;
+    for (let attempt = 0; attempt < 20; attempt++) {
+        let target;
+        if (def.neutral) {
+            // The best block depends on pieces outside the tracked set: draw whole states.
+            const s = solver.sampleState(options.length, options.random);
+            if (!s) {
+                if (++misses >= 3)
+                    return null;
+                continue;
+            }
+            target = s;
+        }
+        else {
+            const place = solver.sample(options.length, options.random);
+            if (!place) {
+                if (++misses >= 3)
+                    return null;
+                continue;
+            }
+            target = randomState({ place, random: options.random });
+        }
+        if (options.frame && options.frame !== IDENTITY_FRAME)
+            target = unreframe(target, options.frame);
+        const result = scrambleTo(target, options);
+        // Defence in depth: the scrambled cube must really be `length` away.
+        if (result && solver.distance(result.state, { frame: options.frame }) === options.length)
+            return result;
+    }
+    return null;
+}
+setRandomStateHook((random) => randomState({ random }));

package/solve/stage.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Optimal solvers for solving stages: cross, xcross, xxcross, EOCross, an F2L
+ * slot, the Roux first block — any set of pieces (plus, optionally, the
+ * orientation of every edge). Answers: how many moves (`distance`), every
+ * optimal solution (`solve`), the optimal next moves from here (`nextMoves`),
+ * and random placements at an exact distance (`sample`, for trainer
+ * scrambles: "a cross that takes exactly 6").
+ *
+ * Canonical frame: cross on D, slots FR / FL / BL / BR, Roux first block on
+ * L-bottom. Pass `frame` to work on another face (`frameFor("U")` = cross
+ * on U) — colour neutral like the rest of cubecore.
+ *
+ * How: IDA* over the tracked pieces. Each piece is one number (position ×
+ * orientations + orientation, 0..23); the heuristic is the max of exact
+ * distance tables for groups of up to five pieces (built by breadth-first
+ * search on first use, shared between stages — the cross + one slot piece
+ * tables are ~8 MB each and take a few hundred ms).
+ */
+import { type Frame, type Move, type Piece, type StageDef, type State } from "../core/index.js";
+export declare const setRandomStateHook: (f: (random: () => number) => State) => undefined;
+export type { Piece, StageDef } from "../core/index.js";
+export type Slot = "FR" | "FL" | "BL" | "BR";
+export declare const STAGES: {
+    readonly cross: () => StageDef;
+    readonly eocross: () => StageDef;
+    readonly xcross: (slot?: Slot) => StageDef;
+    readonly xxcross: (a?: Slot, b?: Slot) => StageDef;
+    /** One F2L slot on its own (edge + corner in place). */
+    readonly slot: (slot?: Slot) => StageDef;
+    /** Roux first block: DL, FL, BL edges and the DLF, DBL corners. */
+    readonly "roux-fb": () => StageDef;
+    /**
+     * Both Roux blocks (first + second: DR, FR, BR edges, DFR, DRB corners) —
+     * for second-block practice from a solved first block. From a full
+     * scramble the optimum is long (~15+) and the search slow.
+     */
+    readonly "roux-blocks": () => StageDef;
+};
+export interface StageSolveOptions {
+    /** Hold the cube this way (canonical D → frame.face.D). Default: identity. */
+    frame?: Frame;
+    /** Longest solution looked for. Default 20. */
+    maxDepth?: number;
+    /** All optimal solutions (up to `limit`) instead of the first. */
+    all?: boolean;
+    limit?: number;
+}
+export declare class StageSolver {
+    readonly def: StageDef;
+    private readonly tables;
+    private readonly goal;
+    /** Goal placements (values of all pieces), when the stage has several (`def.goals`). */
+    private readonly goalSet;
+    /** Move indices the search may use (`def.moves`; the tables stay the all-moves ones — still a valid lower bound). */
+    private readonly allowed;
+    constructor(def: StageDef);
+    private isGoal;
+    /** Values of the tracked pieces (and flip) in `state`, seen through `frame`. */
+    private read;
+    private h;
+    /** Solutions of length exactly `depth` from values (all, or stop at the first). */
+    private search;
+    private optimal;
+    /**
+     * The frames to try: `frame`, or for an x-neutral stage every frame with
+     * the same L and R (the block on the L colour with any bottom colour).
+     */
+    private frames;
+    private distanceIn;
+    /** Fewest moves to finish the stage (−1 if not found within maxDepth). An x-neutral stage takes the best block. */
+    distance(state: State, options?: StageSolveOptions): number;
+    /** Optimal solutions (face turns, in the cube's own frame); for an x-neutral stage, those of the best blocks. */
+    solve(state: State, options?: StageSolveOptions): Move[][];
+    /**
+     * A whole random state whose stage takes exactly `depth` moves — for
+     * x-neutral stages, where the best block depends on pieces outside the
+     * tracked set. Uniform where levels are common; short levels come from
+     * random walks, the rarest deep ones one move beyond a shallower case.
+     */
+    sampleState(depth: number, random?: () => number, draw?: (random: () => number) => State, attempts?: number): State | null;
+    /** The first moves of every optimal solution — "what's a best next move from here?" */
+    nextMoves(state: State, options?: StageSolveOptions): Move[];
+    /**
+     * A random placement of the tracked pieces that takes exactly `depth` moves
+     * (canonical frame): piece → value (pos × orientations + ori), plus the
+     * flip coordinate of all edges for EO stages. Uniform rejection sampling;
+     * very short depths fall back to random walks.
+     */
+    sample(depth: number, random?: () => number, attempts?: number): Placement | null;
+}
+/** Orientation of the edge at each position (0..11) for a flip coordinate. */
+export declare function flipBits(flip: number): number[];
+/** Where some pieces are: piece → value (pos × 2 + ori for edges, pos × 3 + ori for corners); `flip` = orientation of all edges. */
+export interface Placement {
+    pieces: Map<Piece, number>;
+    flip?: number;
+}
+/** Somewhere to keep distance tables between sessions (IndexedDB in browsers — see indexedDbTableStore). */
+export interface TableStore {
+    get(key: string): Promise<Int8Array | null>;
+    set(key: string, table: Int8Array): Promise<void>;
+}
+/** Load the tables these stages need from `store`, or build and save them. Afterwards the solvers start instantly. */
+export declare function preloadStageTables(stages: readonly StageDef[], store: TableStore): Promise<void>;
+/** A TableStore in IndexedDB (works in pages and workers). */
+export declare function indexedDbTableStore(dbName?: string): TableStore;
+/** A shared solver for a stage definition (tables are shared anyway). */
+export declare function stageSolver(def: StageDef): StageSolver;