@wodzik/cubecore 0.1.0

package/timeline/segments.js

@@ -0,0 +1,39 @@
+/**
+ * Segments — sections of a timeline for a progress bar: where each part
+ * starts and ends, what it's called, and optionally where "looking" turns
+ * into "turning". Plain data, independent of any method: a player shows
+ * whatever segments it's given (guide chapters, stored stage times…);
+ * `stageSegments` computes them from a recorded solve for any Method.
+ */
+import { stageTimings } from "./timings.js";
+/** The stages of `method` in a recorded solve as segments (skipped stages — no time of their own — left out). */
+export function stageSegments(method, rec) {
+    return stageTimings(method, rec)
+        .stages.filter((s) => !s.skipped && s.endMs > s.startMs)
+        .map((s) => ({
+        start: s.startMs,
+        end: s.endMs,
+        label: s.label,
+        id: s.stage,
+        ...(s.detail ? { detail: s.detail } : {}),
+        ...(s.recognitionMs > 0 ? { split: s.startMs + s.recognitionMs } : {}),
+        moves: s.moveCount,
+    }));
+}
+/** The segment `time` falls in (index), or −1. */
+export function segmentAt(segments, time) {
+    for (let i = 0; i < segments.length; i++) {
+        const s = segments[i];
+        if (time >= s.start && (time < s.end || (i === segments.length - 1 && time <= s.end)))
+            return i;
+    }
+    return -1;
+}
+/** How much of a segment has played at `time` (0..1). */
+export function segmentPlayed(s, time) {
+    if (time <= s.start)
+        return 0;
+    if (time >= s.end)
+        return 1;
+    return (time - s.start) / (s.end - s.start);
+}

package/timeline/share.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Share payloads — a whole solve as one URL-safe string, e.g. for a link
+ * fragment (`…#s=<payload>`) that a static app can open with no backend.
+ * Building and reading the URL is the app's business; this is the codec. Only what can't be recomputed is stored: the recording
+ * (scramble, every move with its time, the total) and a few facts about it.
+ * Stage splits are NOT stored — the reader derives them (MethodTracker).
+ *
+ * Payload (version 1), base64url:
+ *   byte    version
+ *   byte    flags: bit0 DNF · bit1 hide times (show move counts only) · bit2 has start state
+ *   text    method id ("cfop", "roux"… or empty) — varint length + UTF-8
+ *   [11 B]  start state (core state codec bytes) when the solve didn't start from `scramble` on a solved cube
+ *   …       the recording (see codec.ts)
+ * A typical 100-move solve is ~250 characters.
+ */
+import { type State } from "../core/index.js";
+import type { Recording } from "./recording.js";
+export declare const SHARE_VERSION = 1;
+export interface SharedSolve {
+    recording: Recording;
+    /** Method id the solve was analysed with, e.g. "cfop". */
+    method?: string;
+    dnf?: boolean;
+    /** The sharer showed move counts, not times — a viewer should do the same. */
+    hideTimes?: boolean;
+    /** State the solve started from, when it isn't `scramble` applied to a solved cube (e.g. a scrambled-by-hand cube). */
+    start?: State;
+}
+export declare function encodeShare(solve: SharedSolve): string;
+export declare function decodeShare(text: string): SharedSolve | null;

package/timeline/share.js

@@ -0,0 +1,62 @@
+/**
+ * Share payloads — a whole solve as one URL-safe string, e.g. for a link
+ * fragment (`…#s=<payload>`) that a static app can open with no backend.
+ * Building and reading the URL is the app's business; this is the codec. Only what can't be recomputed is stored: the recording
+ * (scramble, every move with its time, the total) and a few facts about it.
+ * Stage splits are NOT stored — the reader derives them (MethodTracker).
+ *
+ * Payload (version 1), base64url:
+ *   byte    version
+ *   byte    flags: bit0 DNF · bit1 hide times (show move counts only) · bit2 has start state
+ *   text    method id ("cfop", "roux"… or empty) — varint length + UTF-8
+ *   [11 B]  start state (core state codec bytes) when the solve didn't start from `scramble` on a solved cube
+ *   …       the recording (see codec.ts)
+ * A typical 100-move solve is ~250 characters.
+ */
+import { ByteReader, decodeState, encodeState, fromBase64Url, toBase64Url, writeText } from "../core/index.js";
+import { readRecording, writeRecording } from "./codec.js";
+export const SHARE_VERSION = 1;
+export function encodeShare(solve) {
+    const out = [SHARE_VERSION, (solve.dnf ? 1 : 0) | (solve.hideTimes ? 2 : 0) | (solve.start ? 4 : 0)];
+    writeText(out, solve.method ?? "");
+    if (solve.start) {
+        const code = encodeState(solve.start);
+        if (!code)
+            throw new Error("start is not a reachable cube state");
+        out.push(...fromBase64Url(code));
+    }
+    writeRecording(out, solve.recording);
+    return toBase64Url(out);
+}
+export function decodeShare(text) {
+    const bytes = fromBase64Url(text);
+    if (!bytes)
+        return null;
+    const r = new ByteReader(bytes);
+    if (r.byte() !== SHARE_VERSION)
+        return null;
+    const flags = r.byte();
+    if (flags === null || flags > 7)
+        return null;
+    const method = r.text(64);
+    if (method === null)
+        return null;
+    let start;
+    if (flags & 4) {
+        const raw = r.bytes(11);
+        const decoded = raw && decodeState(toBase64Url(raw));
+        if (!decoded)
+            return null;
+        start = decoded;
+    }
+    const recording = readRecording(r);
+    if (!recording || !r.done)
+        return null;
+    return {
+        recording,
+        ...(method ? { method } : {}),
+        ...(flags & 1 ? { dnf: true } : {}),
+        ...(flags & 2 ? { hideTimes: true } : {}),
+        ...(start ? { start } : {}),
+    };
+}

package/timeline/stats.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Solve-time statistics, WCA / csTimer style. Times in ms; a DNF is
+ * `DNF` (Infinity) — it counts as the worst time, so one DNF in an ao5 is
+ * trimmed away, two make the average a DNF.
+ *
+ *   ao(times, 5)            // average of the last 5, best and worst dropped
+ *   bestAo(times, 12)       // best rolling average of 12 in the session
+ *   sessionStats(times)     // { count, best, worst, mean, mo3, ao5, ao12, ao100, bestAo5, bestAo12 }
+ */
+export declare const DNF: number;
+/** How many times an average of `n` drops at each end: 1 for ao5 / ao12, 5 % above that (ao50: 3, ao100: 5). */
+export declare const trimCount: (n: number) => number;
+/** Average of the `n` times ending at `end` (default: the last n); null if there aren't enough, DNF if too many DNFs. */
+export declare function ao(times: readonly number[], n: number, end?: number): number | null;
+/** Mean of the last `n` (nothing dropped; any DNF makes it a DNF) — mo3. */
+export declare function mo(times: readonly number[], n: number, end?: number): number | null;
+/** Best rolling average of `n` over the whole session. */
+export declare function bestAo(times: readonly number[], n: number): number | null;
+export interface SessionStats {
+    count: number;
+    /** Solves that weren't DNFs. */
+    finished: number;
+    best: number | null;
+    worst: number | null;
+    /** Mean of the finished solves. */
+    mean: number | null;
+    mo3: number | null;
+    ao5: number | null;
+    ao12: number | null;
+    ao100: number | null;
+    bestAo5: number | null;
+    bestAo12: number | null;
+}
+export declare function sessionStats(times: readonly number[]): SessionStats;

package/timeline/stats.js

@@ -0,0 +1,56 @@
+/**
+ * Solve-time statistics, WCA / csTimer style. Times in ms; a DNF is
+ * `DNF` (Infinity) — it counts as the worst time, so one DNF in an ao5 is
+ * trimmed away, two make the average a DNF.
+ *
+ *   ao(times, 5)            // average of the last 5, best and worst dropped
+ *   bestAo(times, 12)       // best rolling average of 12 in the session
+ *   sessionStats(times)     // { count, best, worst, mean, mo3, ao5, ao12, ao100, bestAo5, bestAo12 }
+ */
+export const DNF = Number.POSITIVE_INFINITY;
+/** How many times an average of `n` drops at each end: 1 for ao5 / ao12, 5 % above that (ao50: 3, ao100: 5). */
+export const trimCount = (n) => (n <= 12 ? 1 : Math.ceil(n * 0.05));
+/** Average of the `n` times ending at `end` (default: the last n); null if there aren't enough, DNF if too many DNFs. */
+export function ao(times, n, end = times.length) {
+    if (n < 3 || end < n)
+        return null;
+    const sorted = times.slice(end - n, end).sort((a, b) => a - b);
+    const t = trimCount(n);
+    const kept = sorted.slice(t, n - t);
+    if (kept.some((x) => x === DNF))
+        return DNF;
+    return kept.reduce((s, x) => s + x, 0) / kept.length;
+}
+/** Mean of the last `n` (nothing dropped; any DNF makes it a DNF) — mo3. */
+export function mo(times, n, end = times.length) {
+    if (end < n || n < 1)
+        return null;
+    const last = times.slice(end - n, end);
+    return last.some((x) => x === DNF) ? DNF : last.reduce((s, x) => s + x, 0) / n;
+}
+/** Best rolling average of `n` over the whole session. */
+export function bestAo(times, n) {
+    let best = null;
+    for (let end = n; end <= times.length; end++) {
+        const a = ao(times, n, end);
+        if (best === null || a < best)
+            best = a;
+    }
+    return best;
+}
+export function sessionStats(times) {
+    const done = times.filter((t) => t !== DNF);
+    return {
+        count: times.length,
+        finished: done.length,
+        best: done.length ? Math.min(...done) : null,
+        worst: done.length ? Math.max(...done) : null,
+        mean: done.length ? done.reduce((s, x) => s + x, 0) / done.length : null,
+        mo3: mo(times, 3),
+        ao5: ao(times, 5),
+        ao12: ao(times, 12),
+        ao100: ao(times, 100),
+        bestAo5: bestAo(times, 5),
+        bestAo12: bestAo(times, 12),
+    };
+}

package/timeline/timings.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Per-stage timings of a recorded solve for a method, colour neutral
+ * (uses core's MethodTracker). For each stage: recognition = pause before its
+ * first move, execution = from that move to the stage's completion.
+ */
+import { type Method } from "../core/index.js";
+import type { Recording } from "./recording.js";
+export interface StageTiming {
+    stage: string;
+    label: string;
+    /** Index of the first move of this stage and number of moves in it. */
+    firstMove: number;
+    moveCount: number;
+    startMs: number;
+    endMs: number;
+    recognitionMs: number;
+    executionMs: number;
+    totalMs: number;
+    /** Completed on the same move as the previous stage (or before the solve started). */
+    skipped: boolean;
+    detail?: string;
+}
+export interface SolveTimings {
+    stages: StageTiming[];
+    /** Share of the solve spent turning rather than looking (0..1); null if the time is 0. */
+    fluency: number | null;
+    /** Face the method anchored on (e.g. the cross face), null if no stage was reached. */
+    bottomFace: string | null;
+}
+export declare function stageTimings(method: Method, rec: Recording): SolveTimings;

package/timeline/timings.js

@@ -0,0 +1,54 @@
+/**
+ * Per-stage timings of a recorded solve for a method, colour neutral
+ * (uses core's MethodTracker). For each stage: recognition = pause before its
+ * first move, execution = from that move to the stage's completion.
+ */
+import { MethodTracker, applyMoves, solvedState } from "../core/index.js";
+export function stageTimings(method, rec) {
+    const tracker = new MethodTracker(method, applyMoves(solvedState(), rec.scramble));
+    rec.moves.forEach((m) => tracker.push(m.move, m.t));
+    const labels = new Map(method.stages.map((s) => [s.id, s.label]));
+    const timeAfter = (moveIndex) => (moveIndex === 0 ? 0 : rec.moves[moveIndex - 1].t);
+    let prevIndex = 0;
+    let prevEnd = 0;
+    const stages = tracker.boundaries.map((b) => {
+        const endMs = timeAfter(b.moveIndex);
+        const moveCount = b.moveIndex - prevIndex;
+        // A move's timestamp is when it completed; its start is ~the previous move's time.
+        const firstStart = moveCount > 0 ? (prevIndex === 0 ? 0 : rec.moves[prevIndex - 1].t) : endMs;
+        const firstDone = moveCount > 0 ? rec.moves[prevIndex].t : endMs;
+        const recognitionMs = moveCount > 0 ? Math.max(0, firstDone - firstStart - estimateTurnMs(rec)) : 0;
+        const t = {
+            stage: b.stage,
+            label: labels.get(b.stage) ?? b.stage,
+            firstMove: prevIndex,
+            moveCount,
+            startMs: prevEnd,
+            endMs,
+            recognitionMs,
+            executionMs: Math.max(0, endMs - prevEnd - recognitionMs),
+            totalMs: endMs - prevEnd,
+            skipped: moveCount === 0,
+            ...(b.detail ? { detail: b.detail } : {}),
+        };
+        prevIndex = b.moveIndex;
+        prevEnd = endMs;
+        return t;
+    });
+    const recognition = stages.reduce((s, x) => s + x.recognitionMs, 0);
+    return {
+        stages,
+        fluency: rec.totalMs > 0 ? 1 - recognition / rec.totalMs : null,
+        bottomFace: tracker.bottomFace,
+    };
+}
+/**
+ * Typical time of one turn in this solve (median gap between consecutive
+ * moves, capped): the part of a pause that is really the first move itself.
+ */
+function estimateTurnMs(rec) {
+    const gaps = rec.moves.slice(1).map((m, i) => m.t - rec.moves[i].t).filter((g) => g > 0).sort((a, b) => a - b);
+    if (gaps.length === 0)
+        return 0;
+    return Math.min(gaps[Math.floor(gaps.length / 2)], 250);
+}

package/zz/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ZZ — EOLine (all edges oriented + DF/DB), two F2L blocks in either order,
+ * then the last layer. Checks, method and masks; colour neutral.
+ */
+import { type Frame, type Mask, type MaskRule, type Method, type StageDef, type State } from "../core/index.js";
+export declare const eoLine: (s: State) => boolean;
+export declare const eoCross: (s: State) => boolean;
+export declare const leftBlockSolved: (s: State) => boolean;
+export declare const rightBlockSolved: (s: State) => boolean;
+export declare const ZZ: Method;
+export type ZzMask = "eoline" | "eocross" | "f2l";
+export declare const ZZ_MASKS: Record<ZzMask, MaskRule>;
+export declare const zzMask: (name: ZzMask, frame?: Frame) => Mask;
+export declare const ZZ_TRAINERS: {
+    /**
+     * EOCross: cross on D and every edge oriented (F/B axis). Level 10 is a
+     * few in a million among random states — its cases come from a list found
+     * offline (seeds.ts).
+     */
+    readonly eocross: () => StageDef;
+    /** EOLine: every edge oriented (F/B axis) and DF + DB in place — classic ZZ's first step. */
+    readonly eoline: () => StageDef;
+    /**
+     * ZZ blocks after EOLine, built with R U L only (edges stay oriented):
+     * the left block (DL + the FL and BL pairs), then the right (DR + FR, BR);
+     * `side` = which one this stage adds (the other may already be built).
+     */
+    readonly block: (side: "left" | "right", other?: boolean) => StageDef;
+};

package/zz/index.js

@@ -0,0 +1,68 @@
+/**
+ * ZZ — EOLine (all edges oriented + DF/DB), two F2L blocks in either order,
+ * then the last layer. Checks, method and masks; colour neutral.
+ */
+import { IDENTITY_FRAME, LAST_LAYER_STAGES, PIECE, buildMask, checks as C } from "../core/index.js";
+import { EOCROSS_SEEDS } from "./seeds.js";
+const DF = C.cubieAt(0, -1, 1);
+const DB = C.cubieAt(0, -1, -1);
+const LEFT_BLOCK = C.cubiesWhere((p) => p[0] === -1 && p[1] <= 0);
+const RIGHT_BLOCK = C.cubiesWhere((p) => p[0] === 1 && p[1] <= 0);
+export const eoLine = (s) => C.edgesOrientedFB(s) && C.cubieSolved(s, DF) && C.cubieSolved(s, DB);
+export const eoCross = (s) => C.edgesOrientedFB(s) && C.crossSolved(s);
+export const leftBlockSolved = (s) => C.allSolved(s, LEFT_BLOCK);
+export const rightBlockSolved = (s) => C.allSolved(s, RIGHT_BLOCK);
+export const ZZ = {
+    id: "zz",
+    name: "ZZ",
+    stages: [
+        { id: "eoline", label: "EOLine", done: eoLine },
+        {
+            id: "block-1",
+            label: "First block",
+            done: (s) => eoLine(s) && (leftBlockSolved(s) || rightBlockSolved(s)),
+            detail: (s) => (leftBlockSolved(s) ? "left" : "right"),
+        },
+        { id: "block-2", label: "Second block", done: (s) => C.f2lSolved(s) && C.edgesOrientedFB(s) },
+        ...LAST_LAYER_STAGES,
+    ],
+};
+export const ZZ_MASKS = {
+    // Every edge shown as good/bad orientation material, the line in colour.
+    eoline: (f, c) => c.kind === "edge" ? (c.pos[1] === -1 && c.pos[0] === 0 ? "regular" : "oriented") : c.kind === "center" ? "regular" : "ignored",
+    // EOCross: the whole cross in colour, the other edges as orientation material.
+    eocross: (f, c) => (c.kind === "edge" ? (c.pos[1] === -1 ? "regular" : "oriented") : c.kind === "center" ? "regular" : "ignored"),
+    f2l: (f, c) => (c.pos[1] <= 0 || c.kind === "center" ? "regular" : "ignored"),
+};
+export const zzMask = (name, frame = IDENTITY_FRAME) => buildMask(ZZ_MASKS[name], frame);
+// ─── trainer stages (run them with @cubecore/solve) ───
+export const ZZ_TRAINERS = {
+    /**
+     * EOCross: cross on D and every edge oriented (F/B axis). Level 10 is a
+     * few in a million among random states — its cases come from a list found
+     * offline (seeds.ts).
+     */
+    eocross: () => ({
+        name: "eocross",
+        pieces: [PIECE.DR, PIECE.DF, PIECE.DL, PIECE.DB],
+        eo: true,
+        groups: [[0, 1, 2, 3]],
+        seeds: { 10: EOCROSS_SEEDS },
+    }),
+    /** EOLine: every edge oriented (F/B axis) and DF + DB in place — classic ZZ's first step. */
+    eoline: () => ({ name: "eoline", pieces: [PIECE.DF, PIECE.DB], eo: true, groups: [[0, 1]] }),
+    /**
+     * ZZ blocks after EOLine, built with R U L only (edges stay oriented):
+     * the left block (DL + the FL and BL pairs), then the right (DR + FR, BR);
+     * `side` = which one this stage adds (the other may already be built).
+     */
+    block: (side, other = false) => {
+        const left = [PIECE.DL, PIECE.FL, PIECE.DLF, PIECE.BL, PIECE.DBL];
+        const right = [PIECE.DR, PIECE.FR, PIECE.DFR, PIECE.BR, PIECE.DRB];
+        const blocks = other ? [left, right] : [side === "left" ? left : right];
+        const pieces = [PIECE.DF, PIECE.DB, ...blocks.flat()];
+        // Tables: line + block edge + one pair, per pair.
+        const groups = blocks.flatMap((_, b) => [[0, 1, 2 + 5 * b, 3 + 5 * b, 4 + 5 * b], [0, 1, 2 + 5 * b, 5 + 5 * b, 6 + 5 * b]]);
+        return { name: `zz-${other ? "blocks" : `${side}-block`}`, pieces, groups, moves: ["R", "U", "L"] };
+    },
+};

package/zz/seeds.d.ts

@@ -0,0 +1,9 @@
+/**
+ * EOCross cases at level 10 — a few in a million random states, too rare to
+ * draw at run time. Found offline by walking the level-9 states and
+ * keeping neighbours at 10, widened by the stage's symmetries (y2, L↔R and
+ * F↔B mirrors) and each checked with the solver. Placements of DR DF DL DB
+ * (position × 2 + orientation) and the flip coordinate; the rest of the
+ * cube stays random in a trainer scramble. 112 cases.
+ */
+export declare const EOCROSS_SEEDS: readonly string[];

package/zz/seeds.js

@@ -0,0 +1,29 @@
+/**
+ * EOCross cases at level 10 — a few in a million random states, too rare to
+ * draw at run time. Found offline by walking the level-9 states and
+ * keeping neighbours at 10, widened by the stage's symmetries (y2, L↔R and
+ * F↔B mirrors) and each checked with the solver. Placements of DR DF DL DB
+ * (position × 2 + orientation) and the flip coordinate; the rest of the
+ * cube stays random in a trainer scramble. 112 cases.
+ */
+export const EOCROSS_SEEDS = [
+    "13.11.9.15:1279", "13.11.9.15:895", "13.11.9.15:511", "13.11.9.15:1663", "9.15.13.11:1535", "9.15.13.11:1917",
+    "9.15.13.11:1534", "9.15.13.11:1915", "11.18.16.3:2041", "20.7.15.22:2046", "18.16.11.3:2041", "15.7.22.20:2046",
+    "5.6.1.2:1407", "18.3.13.9:2013", "9.13.22.7:2039", "9.3.16.13:2011", "20.9.13.7:2038", "7.20.9.15:2014",
+    "13.11.3.16:2035", "13.22.7.15:2015", "3.11.9.18:2037", "9.3.5.7:2007", "1.3.13.7:2007", "9.15.13.11:1019",
+    "9.15.13.11:1790", "9.15.13.11:1789", "9.15.13.11:1023", "13.11.9.15:1019", "13.11.9.15:1790", "13.11.9.15:1789",
+    "13.11.9.15:1023", "23.15.21.7:2047", "17.3.19.11:2047", "20.22.7.15:2046", "3.11.16.18:2041", "7.20.22.15:2046",
+    "18.11.3.16:2041", "5.15.1.11:2047", "5.11.1.15:2047", "19.11.17.3:2047", "21.7.23.15:2047", "9.3.13.11:2047",
+    "9.15.13.7:2047", "1.11.5.15:2047", "1.4.2.7:1159", "6.3.5.0:775", "2.0.5.7:391", "1.3.6.4:1543",
+    "9.15.13.11:895", "9.15.13.11:1279", "9.15.13.11:1663", "9.15.13.11:511", "9.15.13.3:1887", "9.7.13.11:1527",
+    "9.15.2.11:1407", "6.15.13.11:1407", "2.15.13.11:1407", "9.15.6.11:1407", "2.15.6.11:1407", "6.15.2.11:1407",
+    "1.18.3.15:2013", "7.11.5.22:2039", "3.16.5.15:2011", "1.11.7.20:2038", "9.3.13.5:2047", "9.1.13.7:2047",
+    "9.3.13.1:2047", "9.5.13.7:2047", "1.3.5.7:1967", "2.0.6.4:7", "6.4.2.0:7", "9.3.13.7:2047",
+    "1.6.5.15:1887", "1.11.5.2:1527", "23.11.21.7:2041", "17.3.19.15:2046", "22.4.3.0:760", "7.4.18.0:760",
+    "3.0.20.4:760", "16.0.7.4:760", "9.15.13.2:1503", "9.6.13.11:1911", "1.3.13.7:2047", "9.3.5.7:2047",
+    "4.3.0.15:767", "4.11.0.7:767", "9.15.13.11:127", "5.7.1.2:1503", "5.6.1.3:1911", "4.7.1.3:1687",
+    "5.7.0.3:967", "9.3.13.11:1911", "9.15.13.7:1503", "5.15.1.11:1407", "13.11.9.15:127", "13.3.21.7:1683",
+    "17.3.9.7:964", "23.3.9.7:964", "13.3.19.7:1683", "13.11.9.15:2045", "13.11.9.15:2042", "4.3.0.7:767",
+    "13.16.9.22:1363", "13.18.9.20:1364", "13.7.9.3:2007", "20.3.11.17:2038", "15.21.16.7:2011", "11.3.22.19:2039",
+    "18.23.15.7:2013", "5.7.1.3:2007", "1.3.5.6:1911", "1.2.5.7:1503",
+];