@wodzik/cubecore 0.1.0

package/core/state.js

@@ -0,0 +1,140 @@
+/**
+ * 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 { CUBIES, CUBIE_OF_FACELET, FACELETS, FACELET_COUNT, FACES, centerOf } from "./geometry.js";
+import { movePermutation } from "./moves.js";
+import { parseAlg } from "./notation.js";
+export function solvedState() {
+    return Uint8Array.from({ length: FACELET_COUNT }, (_, i) => i);
+}
+export const colorOf = (sticker) => (sticker / 9) | 0;
+/** Colour class shown at facelet position `i`. */
+export const colorAt = (state, i) => colorOf(state[i]);
+/** Colour class of the centre currently on `face`. */
+export const centerColor = (state, face) => colorAt(state, centerOf(face));
+export function applyPermutation(state, perm) {
+    const out = new Uint8Array(FACELET_COUNT);
+    for (let i = 0; i < FACELET_COUNT; i++)
+        out[i] = state[perm[i]];
+    return out;
+}
+export function applyMove(state, move) {
+    return applyPermutation(state, movePermutation(move));
+}
+export function applyMoves(state, moves) {
+    let s = state;
+    for (const m of typeof moves === "string" ? parseAlg(moves) : moves)
+        s = applyMove(s, m);
+    return s;
+}
+export function statesEqual(a, b) {
+    for (let i = 0; i < FACELET_COUNT; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/** Every face shows one colour (any orientation, any scheme). */
+export function isSolved(state) {
+    for (let f = 0; f < 6; f++) {
+        const c = colorAt(state, f * 9 + 4);
+        for (let i = 0; i < 9; i++)
+            if (colorAt(state, f * 9 + i) !== c)
+                return false;
+    }
+    return true;
+}
+// ─── Colour strings (Kociemba-style facelet strings) ───
+/**
+ * 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 function toFaceletString(state) {
+    let s = "";
+    for (let i = 0; i < FACELET_COUNT; i++)
+        s += FACES[colorAt(state, i)];
+    return s;
+}
+/**
+ * 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 function fromFaceletString(text) {
+    if (text.length !== FACELET_COUNT)
+        throw new Error(`Expected ${FACELET_COUNT} facelets, got ${text.length}`);
+    const colors = [...text].map((c) => {
+        const i = FACES.indexOf(c);
+        if (i < 0)
+            throw new Error(`Unknown facelet "${c}"`);
+        return i;
+    });
+    const homeBySet = new Map();
+    for (const c of CUBIES)
+        homeBySet.set(c.facelets.map((f) => colorOf(f)).sort().join(","), CUBIES.indexOf(c));
+    const state = new Uint8Array(FACELET_COUNT);
+    const used = new Set();
+    for (const cubie of CUBIES) {
+        const set = cubie.facelets.map((f) => colors[f]).sort().join(",");
+        const homeIdx = homeBySet.get(set);
+        if (homeIdx === undefined)
+            throw new Error(`No piece has colours ${set}`);
+        if (used.has(homeIdx))
+            throw new Error(`Piece with colours ${set} appears twice`);
+        used.add(homeIdx);
+        const home = CUBIES[homeIdx];
+        for (const f of cubie.facelets)
+            state[f] = home.facelets.find((h) => colorOf(h) === colors[f]);
+    }
+    return state;
+}
+// ─── Mutable wrapper for hot paths ───
+export class CubeState {
+    s;
+    constructor(initial = solvedState()) {
+        this.s = new Uint8Array(initial);
+    }
+    get state() {
+        return this.s;
+    }
+    apply(moves) {
+        if (typeof moves === "string" || Array.isArray(moves))
+            this.s = applyMoves(this.s, moves);
+        else
+            this.s = applyMove(this.s, moves);
+        return this;
+    }
+    reset(state = solvedState()) {
+        this.s = new Uint8Array(state);
+        return this;
+    }
+    isSolved() {
+        return isSolved(this.s);
+    }
+    clone() {
+        return new CubeState(this.s);
+    }
+}
+// Re-exported for convenience.
+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 function relativeState(from, to) {
+    const toInverse = new Uint8Array(FACELET_COUNT);
+    for (let i = 0; i < FACELET_COUNT; i++)
+        toInverse[to[i]] = i;
+    const out = new Uint8Array(FACELET_COUNT);
+    for (let j = 0; j < FACELET_COUNT; j++)
+        out[j] = toInverse[from[j]];
+    return out;
+}

package/core/stateCodec.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A cube state in 15 URL-safe characters (11 bytes): version, then 73 bits —
+ * centre orientation (frame id, 5 bits), corner permutation (Lehmer rank, 16),
+ * corner twists (7 base-3 digits, 12), edge permutation (rank, 29 in two
+ * parts), edge flips (11). The last twist and flip follow from the others.
+ * For links, QR codes, storage keys. Decoding is strict: anything that isn't
+ * a state reachable by turning returns null.
+ */
+import type { State } from "./state.js";
+export declare const STATE_CODEC_VERSION = 1;
+export declare function encodeState(state: State): string | null;
+export declare function decodeState(text: string): State | null;

package/core/stateCodec.js

@@ -0,0 +1,51 @@
+/**
+ * A cube state in 15 URL-safe characters (11 bytes): version, then 73 bits —
+ * centre orientation (frame id, 5 bits), corner permutation (Lehmer rank, 16),
+ * corner twists (7 base-3 digits, 12), edge permutation (rank, 29 in two
+ * parts), edge flips (11). The last twist and flip follow from the others.
+ * For links, QR codes, storage keys. Decoding is strict: anything that isn't
+ * a state reachable by turning returns null.
+ */
+import { ByteReader, fromBase64Url, packFields, toBase64Url } from "./bytes.js";
+import { fromCubies, isSolvable, permRank, permUnrank, toCubies } from "./cubies.js";
+import { FRAMES } from "./frames.js";
+export const STATE_CODEC_VERSION = 1;
+const WIDTHS = [5, 16, 12, 15, 14, 11];
+const EP_LOW = 1 << 15;
+export function encodeState(state) {
+    const c = toCubies(state);
+    if (!c || !isSolvable(c))
+        return null;
+    const twist = c.co.slice(0, 7).reduce((acc, t) => acc * 3 + t, 0);
+    const flip = c.eo.slice(0, 11).reduce((acc, f) => acc * 2 + f, 0);
+    const ep = permRank(c.ep);
+    const out = [STATE_CODEC_VERSION];
+    const fields = [c.frame.id, permRank(c.cp), twist, ep % EP_LOW, Math.floor(ep / EP_LOW), flip];
+    packFields(out, fields, WIDTHS);
+    return toBase64Url(out);
+}
+export function decodeState(text) {
+    const bytes = fromBase64Url(text);
+    if (!bytes)
+        return null;
+    const r = new ByteReader(bytes);
+    if (r.byte() !== STATE_CODEC_VERSION)
+        return null;
+    const f = r.fields(WIDTHS);
+    if (!f || !r.done)
+        return null;
+    const [frameId, cpRank, twist, epLow, epHigh, flip] = f;
+    const epRank = epHigh * EP_LOW + epLow;
+    if (frameId >= 24 || cpRank >= 40320 || twist >= 2187 || epRank >= 479001600 || flip >= 2048)
+        return null;
+    const co = [];
+    for (let i = 0, t = twist; i < 7; i++, t = Math.floor(t / 3))
+        co.unshift(t % 3);
+    co.push((3 - (co.reduce((a, b) => a + b, 0) % 3)) % 3);
+    const eo = [];
+    for (let i = 0, t = flip; i < 11; i++, t = Math.floor(t / 2))
+        eo.unshift(t % 2);
+    eo.push(eo.reduce((a, b) => a + b, 0) % 2);
+    const c = { frame: FRAMES[frameId], cp: permUnrank(cpRank, 8), co, ep: permUnrank(epRank, 12), eo };
+    return isSolvable(c) ? fromCubies(c) : null;
+}

package/core/stream.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Live move log for a smart cube. Turns arrive one quarter at a time, and the
+ * log writes them the way a cuber would — counting everything that happened:
+ *
+ *   R, R        → R2         (a double flick is one move)
+ *   R, R, R     → R2 R       (never folded back into R')
+ *   R, R'       → R R'       (a slip and its fix: two moves, not zero)
+ *   R, L'       → M          (opposite faces turned together the same way: a slice;
+ *   U, D'       → E           in either order, only when they arrive together —
+ *   F', B       → S           see `sliceWindowMs`)
+ *   R, L', R, L' → M2
+ *
+ * Merges only look at the end of the log, so an entry never changes once
+ * something else follows it.
+ */
+import { type Move } from "./moves.js";
+export interface LoggedMove {
+    move: Move;
+    /** Time of the latest turn merged into it (ms, your clock). */
+    time: number;
+}
+export interface CollapserOptions {
+    /** Merge R, R into R2 only when at most this far apart. Default: always. */
+    repeatWindowMs?: number;
+    /** Merge opposite faces into a slice only when at most this far apart. Default 200 ms. */
+    sliceWindowMs?: number;
+}
+/** What a push did to the log: drop `removed` entries from its end, then append `added`. */
+export interface LogChange {
+    removed: number;
+    added: LoggedMove[];
+}
+/** The slice two face turns make together (R + L' → M), or null. */
+export declare function sliceOf(a: Move, b: Move): Move | null;
+export declare class MoveCollapser {
+    private log;
+    private readonly repeatWindow;
+    private readonly sliceWindow;
+    constructor(options?: CollapserOptions);
+    get moves(): readonly LoggedMove[];
+    push(move: Move, time: number): LogChange;
+    clear(): void;
+}
+/** The same rules on a finished list (all turns taken as simultaneous-enough for slices unless times are given). */
+export declare function collapseMoves(moves: readonly Move[], times?: readonly number[], options?: CollapserOptions): Move[];

package/core/stream.js

@@ -0,0 +1,75 @@
+/**
+ * Live move log for a smart cube. Turns arrive one quarter at a time, and the
+ * log writes them the way a cuber would — counting everything that happened:
+ *
+ *   R, R        → R2         (a double flick is one move)
+ *   R, R, R     → R2 R       (never folded back into R')
+ *   R, R'       → R R'       (a slip and its fix: two moves, not zero)
+ *   R, L'       → M          (opposite faces turned together the same way: a slice;
+ *   U, D'       → E           in either order, only when they arrive together —
+ *   F', B       → S           see `sliceWindowMs`)
+ *   R, L', R, L' → M2
+ *
+ * Merges only look at the end of the log, so an entry never changes once
+ * something else follows it.
+ */
+import { decompose } from "./physical.js";
+import { amountQuarters, toAmount } from "./moves.js";
+const SLICES = ["M", "E", "S"].flatMap((family) => [1, -1, 2].map((amount) => ({ family, amount })));
+const same = (a, b) => a.family === b.family && a.amount === b.amount;
+/** The slice two face turns make together (R + L' → M), or null. */
+export function sliceOf(a, b) {
+    for (const slice of SLICES) {
+        const [x, y] = decompose(slice).turns;
+        if ((same(a, x) && same(b, y)) || (same(a, y) && same(b, x)))
+            return slice;
+    }
+    return null;
+}
+/** Two identical quarter turns → the half turn; anything else → null. */
+function doubled(a, b) {
+    if (!same(a, b) || a.amount === 2)
+        return null;
+    return { family: a.family, amount: toAmount(amountQuarters(a.amount) * 2) };
+}
+export class MoveCollapser {
+    log = [];
+    repeatWindow;
+    sliceWindow;
+    constructor(options = {}) {
+        this.repeatWindow = options.repeatWindowMs ?? Infinity;
+        this.sliceWindow = options.sliceWindowMs ?? 200;
+    }
+    get moves() {
+        return this.log.map(({ move, time }) => ({ move, time }));
+    }
+    push(move, time) {
+        const before = this.log.length;
+        this.log.push({ move, time });
+        let touched = 1; // entries at the end that may differ from what the caller last saw
+        for (;;) {
+            const n = this.log.length;
+            if (n < 2)
+                break;
+            const a = this.log[n - 2], b = this.log[n - 1];
+            const gap = b.time - a.time;
+            const merged = (gap <= this.repeatWindow && doubled(a.move, b.move)) || (gap <= this.sliceWindow && sliceOf(a.move, b.move));
+            if (!merged)
+                break;
+            this.log.splice(n - 2, 2, { move: merged, time: b.time });
+            touched = Math.max(touched, before - (n - 2) + 1);
+        }
+        const keep = this.log.length - Math.min(touched, this.log.length);
+        const removed = before - keep;
+        return { removed, added: this.log.slice(keep).map(({ move, time }) => ({ move, time })) };
+    }
+    clear() {
+        this.log = [];
+    }
+}
+/** The same rules on a finished list (all turns taken as simultaneous-enough for slices unless times are given). */
+export function collapseMoves(moves, times, options) {
+    const c = new MoveCollapser(options);
+    moves.forEach((m, i) => c.push(m, times?.[i] ?? 0));
+    return c.moves.map((m) => m.move);
+}

package/core/tracker.d.ts

@@ -0,0 +1,62 @@
+/**
+ * MethodTracker — follows a solve move by move and reports when each stage
+ * of a method is reached, in any orientation and with any colour scheme.
+ *
+ * Colour neutrality: the method is followed independently in all 24 frames
+ * (orientations) — each frame keeps its own progress. The result is the frame
+ * that got furthest (ties: the one that got there first). So a cross or block
+ * that happens to appear somewhere else — in the scramble, or mid-solve —
+ * can't hijack the analysis: the real one overtakes it.
+ */
+import { type Frame } from "./frames.js";
+import { FACES, type Face } from "./geometry.js";
+import type { Method } from "./method.js";
+import type { Move } from "./moves.js";
+import { type State } from "./state.js";
+export interface StageBoundary {
+    stage: string;
+    /** Moves applied when the stage was reached (0 = already done before the first move). */
+    moveIndex: number;
+    /** Timestamp passed with that move (ms), if any. */
+    time?: number;
+    /** e.g. the F2L slot as physical faces ("FR", "UB"…) or "left"/"edges". */
+    detail?: string;
+    /** The case the stage started from, when the method recognises one ("OLL 27", "T", "PLL skip"…). */
+    case?: string;
+}
+export declare class MethodTracker {
+    readonly method: Method;
+    private state;
+    private moveCount;
+    private progress;
+    constructor(method: Method, start?: State | string);
+    /** Apply one or more moves (with an optional timestamp); returns stages newly reached by the leading frame. */
+    push(move: Move | string, time?: number): StageBoundary[];
+    /**
+     * The frame that got furthest. Ties — and at the end of a solve every frame
+     * has "reached" every stage, since a solved cube passes them all — go to the
+     * frame that reached its stages earliest overall (smallest sum of move
+     * indices): the real cross/block was there all along, an accidental one
+     * elsewhere only completes everything on the last moves.
+     */
+    private get best();
+    /** Stage boundaries of the leading frame. */
+    get boundaries(): readonly StageBoundary[];
+    /**
+     * The next stage, whether the method is finished, the leading frame (null
+     * before the first stage) and the case the next stage started from, if
+     * recognised (e.g. which OLL came up after F2L).
+     */
+    get current(): {
+        next: string | null;
+        done: boolean;
+        frame: Frame | null;
+        case?: string;
+    };
+    /** Physical face the method's canonical D (bottom) settled on — e.g. the cross face for CFOP. */
+    get bottomFace(): Face | null;
+    private advance;
+}
+/** Convenience: stage boundaries of a whole solve. */
+export declare function analyzeSolve(method: Method, scramble: string | readonly Move[], solution: string | readonly Move[], times?: readonly number[]): readonly StageBoundary[];
+export { FACES };

package/core/tracker.js

@@ -0,0 +1,121 @@
+/**
+ * MethodTracker — follows a solve move by move and reports when each stage
+ * of a method is reached, in any orientation and with any colour scheme.
+ *
+ * Colour neutrality: the method is followed independently in all 24 frames
+ * (orientations) — each frame keeps its own progress. The result is the frame
+ * that got furthest (ties: the one that got there first). So a cross or block
+ * that happens to appear somewhere else — in the scramble, or mid-solve —
+ * can't hijack the analysis: the real one overtakes it.
+ */
+import { FRAMES, view } from "./frames.js";
+import { FACES } from "./geometry.js";
+import { parseAlg } from "./notation.js";
+import { applyMove, applyMoves, solvedState } from "./state.js";
+const SLOT_NAME = /^[FB][RL]$/;
+const FACE_ORDER = ["U", "D", "F", "B", "L", "R"];
+/** Canonical slot name (e.g. "FR") → the physical faces it sits between in `frame`. */
+function physicalSlot(detail, frame) {
+    if (!SLOT_NAME.test(detail))
+        return detail;
+    const faces = [frame.face[detail[0]], frame.face[detail[1]]];
+    return faces.sort((a, b) => FACE_ORDER.indexOf(a) - FACE_ORDER.indexOf(b)).join("");
+}
+export class MethodTracker {
+    method;
+    state;
+    moveCount = 0;
+    progress = FRAMES.map((frame) => ({ frame, stageIndex: 0, details: [], boundaries: [], cases: [] }));
+    constructor(method, start = solvedState()) {
+        this.method = method;
+        this.state = typeof start === "string" ? applyMoves(solvedState(), start) : new Uint8Array(start);
+        const first = method.stages[0];
+        if (first?.recognize)
+            for (const p of this.progress)
+                p.cases[0] = first.recognize(view(this.state, p.frame));
+        this.advance(undefined);
+    }
+    /** Apply one or more moves (with an optional timestamp); returns stages newly reached by the leading frame. */
+    push(move, time) {
+        const moves = typeof move === "string" ? parseAlg(move) : [move];
+        const before = this.boundaries.length;
+        for (const m of moves) {
+            this.state = applyMove(this.state, m);
+            this.moveCount++;
+            this.advance(time);
+        }
+        return this.boundaries.slice(before);
+    }
+    /**
+     * The frame that got furthest. Ties — and at the end of a solve every frame
+     * has "reached" every stage, since a solved cube passes them all — go to the
+     * frame that reached its stages earliest overall (smallest sum of move
+     * indices): the real cross/block was there all along, an accidental one
+     * elsewhere only completes everything on the last moves.
+     */
+    get best() {
+        const score = (p) => p.boundaries.reduce((sum, b) => sum + b.moveIndex, 0);
+        let best = this.progress[0];
+        for (const p of this.progress) {
+            if (p.stageIndex > best.stageIndex || (p.stageIndex === best.stageIndex && score(p) < score(best)))
+                best = p;
+        }
+        return best;
+    }
+    /** Stage boundaries of the leading frame. */
+    get boundaries() {
+        return this.best.boundaries;
+    }
+    /**
+     * The next stage, whether the method is finished, the leading frame (null
+     * before the first stage) and the case the next stage started from, if
+     * recognised (e.g. which OLL came up after F2L).
+     */
+    get current() {
+        const best = this.best;
+        const next = this.method.stages[best.stageIndex];
+        const kase = best.cases[best.stageIndex];
+        return { next: next?.id ?? null, done: !next, frame: best.stageIndex > 0 ? best.frame : null, ...(kase ? { case: kase } : {}) };
+    }
+    /** Physical face the method's canonical D (bottom) settled on — e.g. the cross face for CFOP. */
+    get bottomFace() {
+        return this.current.frame?.face.D ?? null;
+    }
+    advance(time) {
+        for (const p of this.progress) {
+            let seen = null;
+            for (;;) {
+                const stage = this.method.stages[p.stageIndex];
+                if (!stage)
+                    break;
+                seen ??= view(this.state, p.frame);
+                if (!stage.done(seen))
+                    break;
+                const raw = stage.detail?.(seen, p.details);
+                if (raw)
+                    p.details.push(raw);
+                const kase = p.cases[p.stageIndex];
+                p.boundaries.push({
+                    stage: stage.id,
+                    moveIndex: this.moveCount,
+                    ...(time !== undefined ? { time } : {}),
+                    ...(raw ? { detail: physicalSlot(raw, p.frame) } : {}),
+                    ...(kase ? { case: kase } : {}),
+                });
+                p.stageIndex++;
+                // The next stage starts here: recognise its case now (e.g. the OLL that came up after F2L).
+                const following = this.method.stages[p.stageIndex];
+                if (following?.recognize)
+                    p.cases[p.stageIndex] = following.recognize(seen);
+            }
+        }
+    }
+}
+/** Convenience: stage boundaries of a whole solve. */
+export function analyzeSolve(method, scramble, solution, times) {
+    const tracker = new MethodTracker(method, applyMoves(solvedState(), scramble));
+    const moves = typeof solution === "string" ? parseAlg(solution) : solution;
+    moves.forEach((m, i) => tracker.push(m, times?.[i]));
+    return tracker.boundaries;
+}
+export { FACES };

package/element/alg.d.ts

@@ -0,0 +1,45 @@
+/**
+ * <cube-alg> — an algorithm as written, in sync with a <cube-player>: the
+ * move playing now is highlighted, played ones fade, click a move to jump to
+ * it. Comments, grouping and pauses stay as written (repeats and commutator
+ * inverses light up the move they copy).
+ *
+ *   <cube-player id="p" alg="(R U R' U')3 // sexy × 3"></cube-player>
+ *   <cube-alg for="p"></cube-alg>
+ *
+ * Text: its own `alg` attribute, else the player's `alg`, else the player's
+ * moves (a recorded solve). Styling: --cc-alg-font, --cc-alg-size,
+ * --cc-alg-done, --cc-alg-current, --cc-alg-current-bg, --cc-alg-comment;
+ * parts alg, token, token-done, token-current, token-todo, comment.
+ */
+import type { CubePlayer } from "./player.js";
+import { ElementBase } from "./base.js";
+export declare class CubeAlg extends ElementBase {
+    static observedAttributes: string[];
+    private readonly root;
+    private player;
+    private doc;
+    private text;
+    /** Token index (by source start) of each move. */
+    private tokenOf;
+    private tokens;
+    private readonly onTime;
+    private readonly onLoad;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** Follow this player (instead of `for`). */
+    attach(player: CubePlayer): void;
+    private connect;
+    private disconnect;
+    private render;
+    /** Moves [0, applied) are done; move `applied` is next / playing. */
+    private highlight;
+}
+export declare function defineCubeAlg(tag?: string): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        "cube-alg": CubeAlg;
+    }
+}