@wodzik/cubecore 0.1.9 → 0.1.11

package/README.md

@@ -13,8 +13,8 @@ headless packages also run in Node / Bun / workers.
 
 | package | what |
 |---|---|
-| `@wodzik/cubecore/core` | state (sticker permutation + centre spins), notation (parse / format / invert / simplify / mirror, `(…)3`, `[A, B]`, `.` pauses, comments, source ranges), metrics, 24 frames and colour neutrality, check primitives, method engine (`Method`, `MethodTracker`), masks, pieces view (Kociemba), 15-char state codec, facelet strings, face turns as a smart cube reports them (`toFaceTurns`, `OrientationTracker`), live move log (`MoveCollapser`: R R → R2, R L' → M), following a scramble / algorithm (`SequenceTracker`) |
-| `@wodzik/cubecore/cfop`, `roux`, `zz`, `petrus`, `lbl` | methods: stages, their checks, masks, trainer stages; CFOP: OLL / PLL recognition (colour neutral, speedcubedb numbering and names; which case came up after F2L / OLL in a solve) |
+| `@wodzik/cubecore/core` | state (sticker permutation + centre spins), notation (parse / format / invert / simplify / mirror, `(…)3`, `[A, B]`, `.` pauses, comments, source ranges), metrics, 24 frames and colour neutrality, check primitives, method engine (`Method`, `MethodTracker`), masks, pieces view (Kociemba), 15-char state codec, facelet strings, face turns as a smart cube reports them (`toFaceTurns`, `OrientationTracker`), live move log (`MoveCollapser`: R R → R2, R L' → M), following a scramble / algorithm (`SequenceTracker`), which algorithm moves did — by effect, any notation (`AlgMatcher`) |
+| `@wodzik/cubecore/cfop`, `roux`, `zz`, `petrus`, `lbl` | methods: stages, their checks, masks, trainer stages; CFOP: F2L / OLL / PLL recognition (colour neutral, speedcubedb numbering and names; which case came up after F2L / OLL in a solve), F2L tables from any set (`F2LCaseTable` — e.g. advanced F2L, a piece stuck in another slot) |
 | `@wodzik/cubecore/methods` | all methods together, masks by name |
 | `@wodzik/cubecore/solve` | two-phase solver (≤ 21 moves, ms), optimal stage solvers (cross, EOCross, xcross, xxcross, slot, Roux blocks), random-state scrambles with presets, trainer scrambles (a stage in exactly N moves), from the cube's current state, any face; Web Worker with a Promise API; tables kept in IndexedDB |
 | `@wodzik/cubecore/timeline` | recordings, replay clock (moves end at their recorded time), stage timings, sections for progress bars, pause compression, recording and share codecs |

package/bluetooth/index.d.ts

@@ -5,3 +5,6 @@ export * from "./simulated.js";
 export * from "./cubeSkins.js";
 export * from "./grips.js";
 export * from "./rotations.js";
+export * from "./timer.js";
+/** The MAC a cube's connection found (kept per device — QiYi's handshake needs it; offer it back when asking the user for one). */
+export { getCachedMacForDevice, removeCachedMacForDevice } from "./vendor/smartcube-web-bluetooth/smartcube/attachment/address-hints.js";

package/bluetooth/index.js

@@ -5,3 +5,6 @@ export * from "./simulated.js";
 export * from "./cubeSkins.js";
 export * from "./grips.js";
 export * from "./rotations.js";
+export * from "./timer.js";
+/** The MAC a cube's connection found (kept per device — QiYi's handshake needs it; offer it back when asking the user for one). */
+export { getCachedMacForDevice, removeCachedMacForDevice } from "./vendor/smartcube-web-bluetooth/smartcube/attachment/address-hints.js";

package/bluetooth/timer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The GAN smart timer (Halo / Smart Timer) over Bluetooth — hands on / get
+ * set / running / stopped, and the recorded times — from the vendored
+ * smartcube-web-bluetooth.
+ *
+ *   const timer = await connectGanTimer();          // needs a user gesture
+ *   timer.events$.subscribe((e) => { if (e.state === GanTimerState.STOPPED) … });
+ */
+export { connectGanTimer, GanTimerState, makeTime, makeTimeFromTimestamp } from "./vendor/smartcube-web-bluetooth/gan-smart-timer.js";
+export type { GanTimerConnection, GanTimerEvent, GanTimerTime, GanTimerRecordedTimes } from "./vendor/smartcube-web-bluetooth/gan-smart-timer.js";

package/bluetooth/timer.js

@@ -0,0 +1,9 @@
+/**
+ * The GAN smart timer (Halo / Smart Timer) over Bluetooth — hands on / get
+ * set / running / stopped, and the recorded times — from the vendored
+ * smartcube-web-bluetooth.
+ *
+ *   const timer = await connectGanTimer();          // needs a user gesture
+ *   timer.events$.subscribe((e) => { if (e.state === GanTimerState.STOPPED) … });
+ */
+export { connectGanTimer, GanTimerState, makeTime, makeTimeFromTimestamp } from "./vendor/smartcube-web-bluetooth/gan-smart-timer.js";

package/cfop/f2l.d.ts

@@ -26,3 +26,33 @@ export declare function isStandardF2L(s: State, slot: F2LSlot): boolean;
  * (not one of the 41).
  */
 export declare function recognizeF2L(s: State, slot: F2LSlot): F2LMatch | "solved" | null;
+/** A case of an F2L set, for one slot: its algorithm as held (cross on D, inserting into that slot). */
+export interface F2LCaseSource {
+    id: string;
+    alg: string;
+}
+export interface F2LSetMatch {
+    id: string;
+    slot: F2LSlot;
+    /** The U turn before the algorithm (moves only pieces in the top layer). */
+    preAuf: string;
+    alg: string;
+}
+/**
+ * Recognition for any set of F2L cases — e.g. "advanced F2L", where a piece
+ * of the pair is stuck in another slot. The case's state is its algorithm
+ * undone on a solved cube, and a case is told by where the slot's pair is
+ * (anywhere — top layer or any slot) and how it's turned, up to a U turn
+ * (only pieces in the top layer move with it). Cases the set lists twice
+ * under the same pair position keep the first; `duplicates` names the rest.
+ */
+export declare class F2LCaseTable {
+    readonly slot: F2LSlot;
+    private readonly table;
+    readonly duplicates: string[];
+    constructor(slot: F2LSlot, cases: readonly F2LCaseSource[]);
+    get size(): number;
+    recognize(s: State): F2LSetMatch | null;
+}
+/** Is a piece of the slot's pair in another slot (not the top layer, not its own) — an "advanced F2L" case? */
+export declare function isTrappedF2L(s: State, slot: F2LSlot): boolean;

package/cfop/f2l.js

@@ -86,3 +86,55 @@ export function recognizeF2L(s, slot) {
     }) ?? "";
     return { id: e.kase.id, group: e.kase.group, slot, preAuf, alg: e.kase.algs[slot] };
 }
+/**
+ * Recognition for any set of F2L cases — e.g. "advanced F2L", where a piece
+ * of the pair is stuck in another slot. The case's state is its algorithm
+ * undone on a solved cube, and a case is told by where the slot's pair is
+ * (anywhere — top layer or any slot) and how it's turned, up to a U turn
+ * (only pieces in the top layer move with it). Cases the set lists twice
+ * under the same pair position keep the first; `duplicates` names the rest.
+ */
+export class F2LCaseTable {
+    slot;
+    table = new Map();
+    duplicates = [];
+    constructor(slot, cases) {
+        this.slot = slot;
+        for (const source of cases) {
+            let s;
+            try {
+                s = applyMoves(solvedState(), invert(parseAlg(source.alg)));
+            }
+            catch {
+                continue;
+            }
+            const k = key(s, slot);
+            const p = pairOf(s, slot);
+            if (!k || !p)
+                continue;
+            if (this.table.has(k))
+                this.duplicates.push(source.id);
+            else
+                this.table.set(k, { source, raw: pairText(p) });
+        }
+    }
+    get size() {
+        return this.table.size;
+    }
+    recognize(s) {
+        const k = key(s, this.slot);
+        const e = k ? this.table.get(k) : undefined;
+        if (!e)
+            return null;
+        const preAuf = AUFS.find((u) => {
+            const q = pairOf(u ? applyMoves(s, u) : s, this.slot);
+            return q !== null && pairText(q) === e.raw;
+        }) ?? "";
+        return { id: e.source.id, slot: this.slot, preAuf, alg: e.source.alg };
+    }
+}
+/** Is a piece of the slot's pair in another slot (not the top layer, not its own) — an "advanced F2L" case? */
+export function isTrappedF2L(s, slot) {
+    const p = pairOf(s, slot);
+    return !!p && !isStandardF2L(s, slot);
+}

package/core/algMatch.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which algorithm was done — by what it does, not how it's written.
+ *
+ * An algorithm's EFFECT is the permutation its face turns make, relative to
+ * the centres (as a smart cube reports them — toFaceTurns): M' = r R' =
+ * R' L; L R' = R' L (turns on one axis commute); U U = U2 = U2';
+ * rotations don't count (only where the pieces go relative to the
+ * centres). So two writings of one algorithm are one effect, and a solve's
+ * moves match it however they were done — with slips undone, in any order
+ * on an axis.
+ *
+ *   const m = new AlgMatcher<string>();
+ *   m.add("R U R' U' R' F R2 U' R' U' R U R' F'", "T-perm");
+ *   m.matchSuffix(solveMoves)   // { data: "T-perm", start: 12, preAuf: "U", postAuf: "" } — moves 0–11 were a setup
+ *
+ * Up to a turn of the AUF face (U) before and after: an algorithm done from
+ * another angle, or finished with an AUF, is the same algorithm.
+ */
+import { type Face } from "./geometry.js";
+import { type Move } from "./moves.js";
+export interface AlgMatch<T> {
+    data: T;
+    /** Index of the first move of the match; the moves before it are a setup. */
+    start: number;
+    /** The AUF turn done before the algorithm ("" / "U" / "U2" / "U'"), as the moves were held. */
+    preAuf: string;
+    /** The AUF turn after it. */
+    postAuf: string;
+}
+/** The effect of `moves` (any notation) as a key: where every sticker goes, relative to the centres. */
+export declare function effectKey(moves: readonly Move[] | string): string;
+export declare class AlgMatcher<T> {
+    private readonly effects;
+    private readonly aufs;
+    private readonly longest;
+    /** @param aufFace the face turned for AUF (U for a last layer, or F2L's top). */
+    constructor(aufFace?: Face);
+    /** An algorithm and what it stands for; the first added wins a shared effect. Returns false when it can't be read. */
+    add(alg: string, data: T): boolean;
+    get size(): number;
+    /** The algorithm whose effect is exactly that of `moves` (any notation), or null. */
+    match(moves: readonly Move[] | string): Omit<AlgMatch<T>, "start"> | null;
+    /**
+     * The longest ending of `moves` that is one of the algorithms — what was
+     * done last, and where it began (the moves before it: a setup, an
+     * extraction…). Endings up to a few moves longer than the longest
+     * algorithm are tried (slips, AUFs inside). Null when none is.
+     */
+    matchSuffix(moves: readonly Move[] | string, slack?: number): AlgMatch<T> | null;
+}

package/core/algMatch.js

@@ -0,0 +1,85 @@
+/**
+ * Which algorithm was done — by what it does, not how it's written.
+ *
+ * An algorithm's EFFECT is the permutation its face turns make, relative to
+ * the centres (as a smart cube reports them — toFaceTurns): M' = r R' =
+ * R' L; L R' = R' L (turns on one axis commute); U U = U2 = U2';
+ * rotations don't count (only where the pieces go relative to the
+ * centres). So two writings of one algorithm are one effect, and a solve's
+ * moves match it however they were done — with slips undone, in any order
+ * on an axis.
+ *
+ *   const m = new AlgMatcher<string>();
+ *   m.add("R U R' U' R' F R2 U' R' U' R U R' F'", "T-perm");
+ *   m.matchSuffix(solveMoves)   // { data: "T-perm", start: 12, preAuf: "U", postAuf: "" } — moves 0–11 were a setup
+ *
+ * Up to a turn of the AUF face (U) before and after: an algorithm done from
+ * another angle, or finished with an AUF, is the same algorithm.
+ */
+import { formatMove } from "./moves.js";
+import { parseAlg } from "./notation.js";
+import { OrientationTracker, toFaceTurns } from "./physical.js";
+import { applyMoves, solvedState } from "./state.js";
+const key = (s) => String.fromCharCode(...s);
+/** The effect of `moves` (any notation) as a key: where every sticker goes, relative to the centres. */
+export function effectKey(moves) {
+    return key(applyMoves(solvedState(), toFaceTurns(moves).moves));
+}
+export class AlgMatcher {
+    effects = new Map();
+    aufs;
+    longest = { moves: 0 };
+    /** @param aufFace the face turned for AUF (U for a last layer, or F2L's top). */
+    constructor(aufFace = "U") {
+        this.aufs = ["", aufFace, `${aufFace}2`, `${aufFace}'`];
+    }
+    /** An algorithm and what it stands for; the first added wins a shared effect. Returns false when it can't be read. */
+    add(alg, data) {
+        let faceTurns;
+        try {
+            faceTurns = toFaceTurns(parseAlg(alg.replace(/[()]/g, " "))).moves;
+        }
+        catch {
+            return false;
+        }
+        if (faceTurns.length === 0)
+            return false;
+        this.longest.moves = Math.max(this.longest.moves, faceTurns.length);
+        const body = faceTurns.map(formatMove).join(" ");
+        for (const preAuf of this.aufs)
+            for (const postAuf of this.aufs) {
+                const k = key(applyMoves(solvedState(), [preAuf, body, postAuf].filter(Boolean).join(" ")));
+                if (!this.effects.has(k))
+                    this.effects.set(k, { data, preAuf, postAuf });
+            }
+        return true;
+    }
+    get size() {
+        return this.effects.size;
+    }
+    /** The algorithm whose effect is exactly that of `moves` (any notation), or null. */
+    match(moves) {
+        const e = this.effects.get(effectKey(moves));
+        return e ? { ...e } : null;
+    }
+    /**
+     * The longest ending of `moves` that is one of the algorithms — what was
+     * done last, and where it began (the moves before it: a setup, an
+     * extraction…). Endings up to a few moves longer than the longest
+     * algorithm are tried (slips, AUFs inside). Null when none is.
+     */
+    matchSuffix(moves, slack = 6) {
+        const list = typeof moves === "string" ? parseAlg(moves) : moves;
+        // One tracker over the whole list: a rotation or wide move keeps holding for the moves after it.
+        const t = new OrientationTracker();
+        const faceTurns = list.map((m) => t.push(m));
+        const from = Math.max(0, list.length - (this.longest.moves + slack));
+        for (let start = from; start < list.length; start++) {
+            const tail = faceTurns.slice(start).flat();
+            const e = this.effects.get(key(applyMoves(solvedState(), tail)));
+            if (e)
+                return { ...e, start };
+        }
+        return null;
+    }
+}

package/core/index.d.ts

@@ -17,3 +17,4 @@ export * from "./sequence.js";
 export * from "./practice.js";
 export * from "./arrows.js";
 export * from "./stages.js";
+export * from "./algMatch.js";

package/core/index.js

@@ -17,3 +17,4 @@ export * from "./sequence.js";
 export * from "./practice.js";
 export * from "./arrows.js";
 export * from "./stages.js";
+export * from "./algMatch.js";

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "A 3×3×3 cube library for the web, built around smart (Bluetooth) cubes: state, notation, methods, solvers and scrambles, a three.js renderer with skins, pictures, web components, React bindings.",
   "license": "MPL-2.0",
   "author": "Tomasz Wodzikowski <wodziszczakow@gmail.com>",