@wodzik/cubecore 0.1.0

package/core/practice.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Practising an algorithm on a smart cube — SequenceTracker plus what a
+ * practice session needs: moves hidden until done (memory check), hints,
+ * mistakes, time and TPS, and noticing a different algorithm that solves
+ * the case all the same.
+ *
+ * reveal: "all"  — every move shown (learning)
+ *         "done" — dots, each move shown once it's done (default)
+ *         "none" — dots to the end (test)
+ * `hint()` shows the next move; a slip shows it too unless hintOnMistake is off.
+ */
+import type { Move } from "./moves.js";
+import { type NextTurn, type SequenceOptions, type SequenceProgress, type TokenStatus } from "./sequence.js";
+import type { State } from "./state.js";
+export type Reveal = "all" | "done" | "none";
+export interface PracticeOptions extends SequenceOptions {
+    reveal?: Reveal;
+    /** Show the next move after a slip. Default true. */
+    hintOnMistake?: boolean;
+}
+export interface PracticeToken {
+    /** The move as written. */
+    move: Move;
+    status: TokenStatus;
+    /** Show it (else a dot). */
+    visible: boolean;
+}
+export interface PracticeProgress extends SequenceProgress {
+    practice: {
+        tokens: PracticeToken[];
+        mistakes: number;
+        /** Face turns made so far. */
+        turns: number;
+        /** ms from the first turn to the last one (or to completion). */
+        elapsedMs: number;
+        /** Turns per second over the attempt. */
+        tps: number;
+        /** Solved, but not with the written algorithm (the same end state another way). */
+        differentAlg: boolean;
+    };
+}
+export declare class PracticeTracker {
+    private readonly tracker;
+    private readonly revealed;
+    private reveal;
+    private readonly hintOnMistake;
+    private mistakes;
+    private turns;
+    private firstTime;
+    private lastTime;
+    private wasOff;
+    private solvedDifferently;
+    constructor(alg: string | readonly Move[], start: State, options?: PracticeOptions);
+    get written(): readonly Move[];
+    setReveal(reveal: Reveal): PracticeProgress;
+    /** Show the next move (the current one). */
+    hint(): PracticeProgress;
+    push(move: Move, time?: number): PracticeProgress;
+    /** What to turn now (see SequenceTracker.nextTurn); null for a hidden next move — Hint or a slip shows it. */
+    get nextTurn(): NextTurn | null;
+    get progress(): PracticeProgress;
+}

package/core/practice.js

@@ -0,0 +1,87 @@
+/**
+ * Practising an algorithm on a smart cube — SequenceTracker plus what a
+ * practice session needs: moves hidden until done (memory check), hints,
+ * mistakes, time and TPS, and noticing a different algorithm that solves
+ * the case all the same.
+ *
+ * reveal: "all"  — every move shown (learning)
+ *         "done" — dots, each move shown once it's done (default)
+ *         "none" — dots to the end (test)
+ * `hint()` shows the next move; a slip shows it too unless hintOnMistake is off.
+ */
+import { SequenceTracker } from "./sequence.js";
+export class PracticeTracker {
+    tracker;
+    revealed = new Set();
+    reveal;
+    hintOnMistake;
+    mistakes = 0;
+    turns = [];
+    firstTime = null;
+    lastTime = 0;
+    wasOff = false;
+    solvedDifferently = false;
+    constructor(alg, start, options = {}) {
+        this.tracker = new SequenceTracker(alg, start, options);
+        this.reveal = options.reveal ?? "done";
+        this.hintOnMistake = options.hintOnMistake ?? true;
+    }
+    get written() {
+        return this.tracker.written;
+    }
+    setReveal(reveal) {
+        this.reveal = reveal;
+        return this.progress;
+    }
+    /** Show the next move (the current one). */
+    hint() {
+        const next = this.progress.tokens.findIndex((s) => s === "current" || s === "partial" || s === "wrong-way");
+        if (next >= 0)
+            this.revealed.add(next);
+        return this.progress;
+    }
+    push(move, time = Date.now()) {
+        this.firstTime ??= time;
+        this.lastTime = time;
+        this.turns.push(move);
+        const p = this.tracker.push(move);
+        // Reaching the end straight from off the path = the case solved another way.
+        if (p.complete && this.wasOff)
+            this.solvedDifferently = true;
+        const off = p.undo.length > 0;
+        if (off && !this.wasOff) {
+            this.mistakes++;
+            if (this.hintOnMistake)
+                this.hint();
+        }
+        this.wasOff = off;
+        return this.progress;
+    }
+    /** What to turn now (see SequenceTracker.nextTurn); null for a hidden next move — Hint or a slip shows it. */
+    get nextTurn() {
+        const t = this.tracker.nextTurn;
+        if (!t || t.token === null)
+            return t;
+        return this.progress.practice.tokens[t.token]?.visible ? t : null;
+    }
+    get progress() {
+        const p = this.tracker.progress;
+        const tokens = this.tracker.written.map((move, i) => {
+            const status = p.tokens[i];
+            const visible = this.reveal === "all" || this.revealed.has(i) || (this.reveal === "done" && (status === "done" || status === "partial"));
+            return { move, status, visible };
+        });
+        const elapsedMs = this.firstTime === null ? 0 : this.lastTime - this.firstTime;
+        return {
+            ...p,
+            practice: {
+                tokens,
+                mistakes: this.mistakes,
+                turns: this.turns.length,
+                elapsedMs,
+                tps: elapsedMs > 0 ? this.turns.length / (elapsedMs / 1000) : 0,
+                differentAlg: p.complete && this.solvedDifferently,
+            },
+        };
+    }
+}

package/core/sequence.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Following a scramble (or an algorithm) on a smart cube: which moves are
+ * done, which one is under way, and — after a slip — what to undo.
+ *
+ * It matches CUBE STATES, not move strings, so everything that reaches the
+ * same state counts:
+ *   - a half turn done as two quarter turns, either way (half done = `partial`);
+ *   - opposite faces in the other order (R L done as L R);
+ *   - an algorithm written with rotations, slices and wide moves (converted
+ *     with toFaceTurns: what the smart cube will actually report).
+ * Off the path, `undo` is the way back to the last matching point (the
+ * slip, simplified: R R' cancels) and `needsReset` says it's too long.
+ */
+import { type TurnArrow } from "./arrows.js";
+import type { Frame } from "./frames.js";
+import type { Move } from "./moves.js";
+import { type State } from "./state.js";
+export interface SequenceStep {
+    /** The face turn the cube will report. */
+    move: Move;
+    /** Index of the written move (token) it belongs to — several steps for M, none for a rotation. */
+    token: number;
+}
+/** "wrong-way": the move due, its face turned the wrong way (or too far) — turn it back / on, no real slip. */
+export type TokenStatus = "done" | "partial" | "current" | "wrong-way" | "todo";
+export interface SequenceProgress {
+    /** Face-turn steps fully done. */
+    done: number;
+    total: number;
+    /** The next step is a half turn and half of it is done. */
+    partial: boolean;
+    /** Status of each written move (for display). */
+    tokens: TokenStatus[];
+    /** Moves that bring the cube back to the last matching point (empty when on track). */
+    undo: Move[];
+    /** The slip is longer than `maxCorrection`: better to reset / solve and start over. */
+    needsReset: boolean;
+    /** The only slip is the move due turned the wrong way (or too far) — the right face, fix it with that face. */
+    wrongWay: boolean;
+    complete: boolean;
+}
+/** What to turn now — for arrows on a 3D cube (see arrows.ts). */
+export interface NextTurn {
+    /**
+     * "next": the next move of the sequence; "undo": the first move back after
+     * a slip; "wrong-way": the same, when the slip was the right face turned
+     * the wrong way (or too far) — worth a colour of its own.
+     */
+    kind: "next" | "undo" | "wrong-way";
+    /** In the cube's own coordinates. Usually one; the rest of an M done half-way can be two. */
+    arrows: TurnArrow[];
+    /** The written move it belongs to (null for undo). */
+    token: number | null;
+}
+export interface SequenceOptions {
+    /** Longest undo worth showing (act's rule: 25). */
+    maxCorrection?: number;
+    /**
+     * How the cube is held at the start (default: its own U on top, F in
+     * front) — e.g. after an algorithm with a net rotation (M, wide moves) the
+     * next one is written for the cube as now held.
+     */
+    frame?: Frame;
+}
+export declare class SequenceTracker {
+    readonly written: Move[];
+    readonly steps: SequenceStep[];
+    /** How the cube is held before each written move (rotations and slices change it). */
+    readonly frames: Frame[];
+    private readonly path;
+    private cur;
+    private anchor;
+    private anchorPartial;
+    private offPath;
+    private readonly maxCorrection;
+    constructor(target: string | readonly Move[], start: State, options?: SequenceOptions);
+    get state(): State;
+    /** A face turn reported by the cube. */
+    push(move: Move): SequenceProgress;
+    get progress(): SequenceProgress;
+    /**
+     * What to turn now, for an arrow: after a slip the first undo move; half way
+     * through a half turn the remaining quarter (the way it was started); else
+     * the next written move as written — a wide r stays two layers, an M the
+     * middle one — placed where it is on the cube as now held. Null when complete.
+     */
+    get nextTurn(): NextTurn | null;
+    /** Where the current state is on the path, if anywhere: after `done` steps (+ half of the next one). */
+    private locate;
+}

package/core/sequence.js

@@ -0,0 +1,157 @@
+/**
+ * Following a scramble (or an algorithm) on a smart cube: which moves are
+ * done, which one is under way, and — after a slip — what to undo.
+ *
+ * It matches CUBE STATES, not move strings, so everything that reaches the
+ * same state counts:
+ *   - a half turn done as two quarter turns, either way (half done = `partial`);
+ *   - opposite faces in the other order (R L done as L R);
+ *   - an algorithm written with rotations, slices and wide moves (converted
+ *     with toFaceTurns: what the smart cube will actually report).
+ * Off the path, `undo` is the way back to the last matching point (the
+ * slip, simplified: R R' cancels) and `needsReset` says it's too long.
+ */
+import { turnArrow } from "./arrows.js";
+import { invert, parseAlg, simplify } from "./notation.js";
+import { OrientationTracker } from "./physical.js";
+import { applyMove, statesEqual } from "./state.js";
+export class SequenceTracker {
+    written;
+    steps;
+    /** How the cube is held before each written move (rotations and slices change it). */
+    frames;
+    path; // state after k steps
+    cur;
+    anchor = 0; // last matching step index
+    anchorPartial = false;
+    offPath = []; // moves since the last matching point
+    maxCorrection;
+    constructor(target, start, options = {}) {
+        this.written = typeof target === "string" ? parseAlg(target) : [...target];
+        this.maxCorrection = options.maxCorrection ?? 25;
+        const grip = new OrientationTracker(options.frame);
+        this.frames = [];
+        this.steps = this.written.flatMap((m, token) => {
+            this.frames.push(grip.frame);
+            return grip.push(m).map((move) => ({ move, token }));
+        });
+        this.path = [new Uint8Array(start)];
+        for (const s of this.steps)
+            this.path.push(applyMove(this.path[this.path.length - 1], s.move));
+        this.cur = new Uint8Array(start);
+    }
+    get state() {
+        return this.cur;
+    }
+    /** A face turn reported by the cube. */
+    push(move) {
+        this.cur = applyMove(this.cur, move);
+        const on = this.locate();
+        if (on) {
+            this.anchor = on.done;
+            this.anchorPartial = on.partial;
+            this.offPath = [];
+        }
+        else {
+            this.offPath.push(move);
+        }
+        return this.progress;
+    }
+    get progress() {
+        const total = this.steps.length;
+        const undo = this.offPath.length ? invert(simplify(this.offPath)) : [];
+        const done = this.anchor;
+        const partial = this.anchorPartial && !this.offPath.length;
+        const next = done < total ? this.steps[done].token : this.written.length;
+        const expected = this.steps[done]?.move;
+        const wrongWay = undo.length === 1 && expected !== undefined && undo[0].family === expected.family;
+        const tokens = this.written.map((_, t) => {
+            const idx = this.steps.map((s, i) => (s.token === t ? i : -1)).filter((i) => i >= 0);
+            if (!idx.length)
+                return t < next ? "done" : "todo"; // a rotation: done once the cube gets past it
+            const first = idx[0], last = idx[idx.length - 1];
+            if (last < done)
+                return "done";
+            if (first < done || (first === done && partial))
+                return "partial"; // M half done, or half of an R2
+            if (first === done && wrongWay)
+                return "wrong-way";
+            return first === done ? "current" : "todo";
+        });
+        return { done, total, partial, tokens, undo, needsReset: undo.length > this.maxCorrection, wrongWay, complete: done === total && !this.offPath.length };
+    }
+    /**
+     * What to turn now, for an arrow: after a slip the first undo move; half way
+     * through a half turn the remaining quarter (the way it was started); else
+     * the next written move as written — a wide r stays two layers, an M the
+     * middle one — placed where it is on the cube as now held. Null when complete.
+     */
+    get nextTurn() {
+        const p = this.progress;
+        if (p.complete)
+            return null;
+        if (p.wrongWay) {
+            // The face due went the wrong way (or too far): the turn to where it should be —
+            // back and on in one go (U instead of U': a U2 the way U' goes).
+            const expected = this.steps[p.done].move;
+            const back = p.undo[0];
+            const signed = (m) => (m.amount === 2 ? 2 * Math.sign(m.written ?? 2) : m.amount);
+            let q = signed(back) + (expected.amount === 2 ? 2 * (Math.sign(signed(back)) || 1) : expected.amount);
+            q = ((q % 4) + 4) % 4;
+            const amount = (q === 3 ? -1 : q);
+            const fix = amount === 2 ? { family: expected.family, amount: 2, written: 2 * (Math.sign(signed(expected)) || 1) } : { family: expected.family, amount };
+            return { kind: "wrong-way", arrows: [turnArrow(fix)], token: this.steps[p.done].token };
+        }
+        if (p.undo.length) {
+            return { kind: "undo", arrows: [turnArrow(p.undo[0])], token: null };
+        }
+        const k = p.done;
+        const step = this.steps[k];
+        if (!step)
+            return null;
+        const next = (moves) => ({ kind: "next", arrows: moves.map((m) => turnArrow(m)), token: step.token });
+        if (p.partial) {
+            if (step.move.amount === 2) {
+                for (const amount of [1, -1]) {
+                    const half = { family: step.move.family, amount };
+                    if (statesEqual(applyMove(this.path[k], half), this.cur))
+                        return next([half]);
+                }
+            }
+            return next([step.move]); // the opposite face went first: this one is left
+        }
+        const first = this.steps.findIndex((s) => s.token === step.token);
+        if (first < k) {
+            // A slice / wide move partly done (its face turns arrive one by one): what's left of it.
+            return next(this.steps.slice(k).filter((s) => s.token === step.token).map((s) => s.move));
+        }
+        return { kind: "next", arrows: [turnArrow(this.written[step.token], this.frames[step.token])], token: step.token };
+    }
+    /** Where the current state is on the path, if anywhere: after `done` steps (+ half of the next one). */
+    locate() {
+        for (let k = this.path.length - 1; k >= 0; k--)
+            if (statesEqual(this.path[k], this.cur))
+                return { done: k, partial: false };
+        for (let k = 0; k < this.steps.length; k++) {
+            const s = this.steps[k].move;
+            // Half of a half turn, either way.
+            if (s.amount === 2) {
+                for (const amount of [1, -1]) {
+                    if (statesEqual(applyMove(this.path[k], { family: s.family, amount }), this.cur))
+                        return { done: k, partial: true };
+                }
+            }
+            // The next step on the opposite face done first (R L done as L R): count as progress on k.
+            const n = this.steps[k + 1];
+            if (n && opposite(s, n.move)) {
+                if (statesEqual(applyMove(this.path[k], n.move), this.cur))
+                    return { done: k, partial: true };
+            }
+        }
+        return null;
+    }
+}
+const AXIS = { U: 1, D: 1, R: 0, L: 0, F: 2, B: 2 };
+function opposite(a, b) {
+    return a.family !== b.family && AXIS[a.family] !== undefined && AXIS[a.family] === AXIS[b.family];
+}

package/core/stages.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Solving stages as plain data — which pieces a stage puts where — so
+ * method packages can describe their trainer stages (cross, XCross, Roux
+ * first square…) without depending on a solver; @cubecore/solve runs them.
+ *
+ * Canonical frame: cross / first layer on D, F2L slots FR FL BL BR, Roux
+ * first block on L-bottom. Pieces use the Kociemba ids of core cubies.ts
+ * (edges UR UF UL UB DR DF DL DB FR FL BL BR, corners URF UFL ULB UBR DFR
+ * DLF DBL DRB).
+ */
+export interface Piece {
+    kind: "edge" | "corner";
+    /** Kociemba piece id. */
+    id: number;
+}
+export interface StageDef {
+    name: string;
+    pieces: readonly Piece[];
+    /** Also orient every edge (EOCross). */
+    eo?: boolean;
+    /** Groups (indices into `pieces`) with exact distance tables; the heuristic is their max. At most 5 pieces each. */
+    groups: readonly (readonly number[])[];
+    /**
+     * The stage is done in any of these states — algorithms applied to a
+     * solved cube (canonical frame), e.g. a pair "one insert away". Default:
+     * the pieces at home.
+     */
+    goals?: readonly string[];
+    /** Indices into `pieces` kept solved in trainer cases (e.g. the first block while practising the second square). */
+    keep?: readonly number[];
+    /**
+     * The block may be built with any of the four x rotations (Roux first
+     * block / square: any bottom colour on the L side) — the distance is the
+     * best of them. Trainer cases are then drawn from whole random states.
+     */
+    neutral?: "x";
+    /**
+     * Known cases for levels too rare to draw at run time (EOCross at 10: a
+     * few in a million): depth → placements "v.v.v…:flip" (each piece's
+     * value in `pieces` order, position × orientations + orientation; flip
+     * for EO stages). Found once offline; the rest of the cube stays random.
+     */
+    seeds?: Readonly<Record<number, readonly string[]>>;
+    /**
+     * Faces the solution may turn (default all six) — e.g. ["R", "U", "L"]
+     * for ZZ's F2L, which keeps every edge oriented.
+     */
+    moves?: readonly ("U" | "R" | "F" | "D" | "L" | "B")[];
+}
+export declare const edgePiece: (id: number) => Piece;
+export declare const cornerPiece: (id: number) => Piece;
+/** Named pieces (canonical positions). */
+export declare const PIECE: {
+    readonly UR: Piece;
+    readonly UF: Piece;
+    readonly UL: Piece;
+    readonly UB: Piece;
+    readonly DR: Piece;
+    readonly DF: Piece;
+    readonly DL: Piece;
+    readonly DB: Piece;
+    readonly FR: Piece;
+    readonly FL: Piece;
+    readonly BL: Piece;
+    readonly BR: Piece;
+    readonly URF: Piece;
+    readonly UFL: Piece;
+    readonly ULB: Piece;
+    readonly UBR: Piece;
+    readonly DFR: Piece;
+    readonly DLF: Piece;
+    readonly DBL: Piece;
+    readonly DRB: Piece;
+};
+/**
+ * A last-six-edges stage (Roux): moves are M and U only, the blocks and
+ * CMLL stay solved; done in any of `goals` (algorithms from a solved cube),
+ * compared on what the stage is about:
+ * `features: "eolr"` — edge orientation of the six edges, where UL and UR
+ * are, centres and corner AUF (the other four edges' order is the next
+ * step's business); `"lse"` — everything (the whole of LSE).
+ */
+export interface LseStageDef {
+    name: string;
+    kind: "lse";
+    features: "eolr" | "lse";
+    goals: readonly string[];
+}
+export type AnyStageDef = StageDef | LseStageDef;
+export declare const isLseStage: (def: AnyStageDef) => def is LseStageDef;

package/core/stages.js

@@ -0,0 +1,21 @@
+/**
+ * Solving stages as plain data — which pieces a stage puts where — so
+ * method packages can describe their trainer stages (cross, XCross, Roux
+ * first square…) without depending on a solver; @cubecore/solve runs them.
+ *
+ * Canonical frame: cross / first layer on D, F2L slots FR FL BL BR, Roux
+ * first block on L-bottom. Pieces use the Kociemba ids of core cubies.ts
+ * (edges UR UF UL UB DR DF DL DB FR FL BL BR, corners URF UFL ULB UBR DFR
+ * DLF DBL DRB).
+ */
+export const edgePiece = (id) => ({ kind: "edge", id });
+export const cornerPiece = (id) => ({ kind: "corner", id });
+/** Named pieces (canonical positions). */
+export const PIECE = {
+    UR: edgePiece(0), UF: edgePiece(1), UL: edgePiece(2), UB: edgePiece(3),
+    DR: edgePiece(4), DF: edgePiece(5), DL: edgePiece(6), DB: edgePiece(7),
+    FR: edgePiece(8), FL: edgePiece(9), BL: edgePiece(10), BR: edgePiece(11),
+    URF: cornerPiece(0), UFL: cornerPiece(1), ULB: cornerPiece(2), UBR: cornerPiece(3),
+    DFR: cornerPiece(4), DLF: cornerPiece(5), DBL: cornerPiece(6), DRB: cornerPiece(7),
+};
+export const isLseStage = (def) => def.kind === "lse";

package/core/state.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cube state: 54 stickers, each carrying the index of its HOME facelet in the
+ * solved cube (so pieces keep their identity — masks and rendering follow
+ * them). A sticker's colour class is its home face: `colorOf(id) = id / 9`.
+ *
+ * Nothing here assumes a colour scheme or an orientation: "solved" means
+ * every face shows a single colour class, whichever it is. Real colours are
+ * the renderer's business (colour class → colour of a scheme).
+ */
+import { CUBIE_OF_FACELET, FACELETS, type Face } from "./geometry.js";
+import { type Move, type Permutation } from "./moves.js";
+export type State = Uint8Array;
+/** Colour class 0..5 = the home face (U R F D L B order) of a sticker. */
+export type ColorClass = number;
+export declare function solvedState(): State;
+export declare const colorOf: (sticker: number) => ColorClass;
+/** Colour class shown at facelet position `i`. */
+export declare const colorAt: (state: State, i: number) => ColorClass;
+/** Colour class of the centre currently on `face`. */
+export declare const centerColor: (state: State, face: Face) => ColorClass;
+export declare function applyPermutation(state: State, perm: Permutation): State;
+export declare function applyMove(state: State, move: Move): State;
+export declare function applyMoves(state: State, moves: readonly Move[] | string): State;
+export declare function statesEqual(a: State, b: State): boolean;
+/** Every face shows one colour (any orientation, any scheme). */
+export declare function isSolved(state: State): boolean;
+/**
+ * 54 letters in U R F D L B facelet order, each naming the face whose home
+ * colour the sticker has — e.g. the solved cube is "UUUUUUUUURRR…BBB".
+ * This is what smart cubes and most solvers exchange.
+ */
+export declare function toFaceletString(state: State): string;
+/**
+ * Build a state from a facelet string. Stickers get their identity by matching
+ * each piece's colour set to its home piece; throws if the colours don't form a
+ * real cube (wrong counts or a piece that doesn't exist).
+ */
+export declare function fromFaceletString(text: string): State;
+export declare class CubeState {
+    private s;
+    constructor(initial?: State);
+    get state(): State;
+    apply(moves: Move | readonly Move[] | string): this;
+    reset(state?: State): this;
+    isSolved(): boolean;
+    clone(): CubeState;
+}
+export { CUBIE_OF_FACELET, FACELETS };
+/**
+ * The state whose solution is the way from `from` to `to`: solving it gives
+ * moves M with applyMoves(from, M) = to. Lets any solver (and so any
+ * scramble generator) work from wherever the physical cube is now — a smart
+ * cube between attempts doesn't have to be solved first.
+ */
+export declare function relativeState(from: State, to: State): State;