@wodzik/cubecore 0.1.4 → 0.1.5

package/README.md

@@ -24,7 +24,7 @@ headless packages also run in Node / Bun / workers.
 | `@wodzik/cubecore/bld` | Blindfolded (Old Pochmann): letter schemes (ruwix, Speffz), memo, execution followed letter by letter, a skin with letters |
 | `@wodzik/cubecore/analyze` | scramble analysis — CFOP: per cross colour the optimal cross / Cross+1…3, the best pair order (fewest moves or by F2L algorithms), OLL / PLL cases, coverage of known algorithms; Roux: per block side FB, second square + block, CMLL case, optimal LSE; ZZ: EOCross, R U L pairs, OCLL + PLL; worker |
 | `@wodzik/cubecore/element` | `<cube-player>` (algorithms at a tempo or timed solves; controls, progress bar with stage sections, 2D views, live mode), `<cube-scramble>` (follows a scramble on a smart cube; paste your own), `<cube-alg-practice>` (algorithm practice: hidden moves, hints, mistakes, TPS), `<cube-bld>` (blindfolded memo and execution), `<cube-alg>` (the text in sync) |
-| `@wodzik/cubecore/bluetooth` | `SmartCubeSession` over smartcube-web-bluetooth (GAN, MoYu, QiYi, GoCube, Giiker): moves timed by the cube's clock, resync, gyro, battery; skin per cube; `SimulatedCube` |
+| `@wodzik/cubecore/bluetooth` | `SmartCubeSession` over smartcube-web-bluetooth (GAN, MoYu, QiYi, GoCube, Giiker): moves timed by the cube's clock, resync, gyro (calibration, drift, other brands' axes), battery; rotations / slices / wide moves read back with the gyro (`GripRecorder`, `heldTokens`); skin per cube; `SimulatedCube` |
 | `@wodzik/cubecore/react` | `<CubePlayer>`, `<CubeScramble>`, `<CubeAlgPractice>`, `<CubeAlg>`, `useSmartCube()`, `useSolverWorker()` |
 
 ## Quick start

package/bluetooth/grips.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Grips — how a smart cube is held (which physical face is on top, which
+ * faces you), read from its gyroscope — and the cube rotations (x, y, z)
+ * between them. The orientation is the session's (calibrated: identity =
+ * the cube as drawn, U up and F front) — CubeRenderer.setOrientation's axes.
+ *
+ * A grip is a cubecore Frame: `grip.face.U` is the physical face on top,
+ * `grip.face.F` the one towards you (frameFor(bottom, front)). The identity
+ * grip is the cube as drawn — physical U up, F front (white top, green front
+ * in the western scheme) — which is also how "Reset gyro" expects it held.
+ *
+ * Physical moves (as the smart cube reports them) re-lettered for a grip are
+ * the moves as the solver saw them: with orange (L) in front, an L turn is
+ * "F" (rotations.ts heldMove).
+ */
+import { type Face, type Frame, type Vec3 } from "../core/index.js";
+import type { Quat } from "./gyro.js";
+export type Grip = Frame;
+export declare const IDENTITY_GRIP: Grip;
+/** The grip with `top` up and `front` towards you. */
+export declare const gripOf: (top: Face, front: Face) => Grip;
+/** `v` turned by `q` (q v q*). */
+export declare function rotateVec(q: Quat, v: Vec3): Vec3;
+export interface GripReading {
+    grip: Grip;
+    /** The worse of the top / front faces' angle (degrees) from straight up / straight at you. */
+    offDeg: number;
+}
+/** The grip nearest to the cube turned by `q` (the calibrated gyro orientation, as CubeRenderer.setOrientation takes it). */
+export declare function readGrip(q: Quat): GripReading;
+/** The quaternion that turns the drawn cube so `frame`'s faces sit where the holder sees them. */
+export declare function frameQuaternion(frame: Frame): {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+/** The orientation (as readGrip takes it) of a cube held exactly in `grip`. */
+export declare const gripQuaternion: (grip: Grip) => Quat;
+/** The grip after a rotation ("x", "y'", "z2", or several: "x y"). */
+export declare function rotateGrip(grip: Grip, rotation: string): Grip;
+/** The shortest rotation from one grip to another ("" when the same). */
+export declare function rotationBetween(from: Grip, to: Grip): string;
+export interface GripChange {
+    from: Grip;
+    to: Grip;
+    /** When the new grip was first reached (before the dwell confirmed it). */
+    at: number;
+    /** The `mark` passed with the reading that first reached it (GripRecorder: how many moves had come). */
+    mark: number;
+    rotation: string;
+}
+/**
+ * Grip changes from a stream of gyro readings, with hysteresis: a new grip
+ * counts once the cube has sat within `maxOffDeg` of it for `dwellMs` — a
+ * wobble during a turn, or passing through a grip on the way to another
+ * (x2 through x), is not a rotation.
+ */
+export declare class GripTracker {
+    private readonly maxOffDeg;
+    private readonly dwellMs;
+    grip: Grip | null;
+    private candidate;
+    constructor(maxOffDeg?: number, dwellMs?: number);
+    /** A reading at time `t`; `mark` is kept with the moment a new grip is first reached (see GripChange.mark). */
+    update(q: Quat, t: number, mark?: number): GripChange | null;
+    reset(): void;
+}
+/** All 24 grips (for tests and pickers). */
+export declare const ALL_GRIPS: readonly Grip[];
+/** "white top, green front"-style label of a grip, in physical face letters: "U/F". */
+export declare const gripLabel: (g: Grip) => string;

package/bluetooth/grips.js

@@ -0,0 +1,156 @@
+/**
+ * Grips — how a smart cube is held (which physical face is on top, which
+ * faces you), read from its gyroscope — and the cube rotations (x, y, z)
+ * between them. The orientation is the session's (calibrated: identity =
+ * the cube as drawn, U up and F front) — CubeRenderer.setOrientation's axes.
+ *
+ * A grip is a cubecore Frame: `grip.face.U` is the physical face on top,
+ * `grip.face.F` the one towards you (frameFor(bottom, front)). The identity
+ * grip is the cube as drawn — physical U up, F front (white top, green front
+ * in the western scheme) — which is also how "Reset gyro" expects it held.
+ *
+ * Physical moves (as the smart cube reports them) re-lettered for a grip are
+ * the moves as the solver saw them: with orange (L) in front, an L turn is
+ * "F" (rotations.ts heldMove).
+ */
+import { FACES, FACE_NORMAL, FRAMES, IDENTITY_FRAME, frameFor } from "../core/index.js";
+export const IDENTITY_GRIP = IDENTITY_FRAME;
+const OPPOSITE = { U: "D", D: "U", R: "L", L: "R", F: "B", B: "F" };
+/** The grip with `top` up and `front` towards you. */
+export const gripOf = (top, front) => frameFor(OPPOSITE[top], front);
+/** `v` turned by `q` (q v q*). */
+export function rotateVec(q, v) {
+    const [vx, vy, vz] = v;
+    // t = 2 (q.xyz × v); v' = v + w t + q.xyz × t
+    const tx = 2 * (q.y * vz - q.z * vy);
+    const ty = 2 * (q.z * vx - q.x * vz);
+    const tz = 2 * (q.x * vy - q.y * vx);
+    return [vx + q.w * tx + (q.y * tz - q.z * ty), vy + q.w * ty + (q.z * tx - q.x * tz), vz + q.w * tz + (q.x * ty - q.y * tx)];
+}
+/** The grip nearest to the cube turned by `q` (the calibrated gyro orientation, as CubeRenderer.setOrientation takes it). */
+export function readGrip(q) {
+    let top = "U";
+    let front = "F";
+    let bestUp = -2;
+    let bestFront = -2;
+    for (const f of FACES) {
+        const n = rotateVec(q, FACE_NORMAL[f]);
+        if (n[1] > bestUp)
+            [bestUp, top] = [n[1], f];
+        if (n[2] > bestFront)
+            [bestFront, front] = [n[2], f];
+    }
+    const deg = (c) => (Math.acos(Math.max(-1, Math.min(1, c))) * 180) / Math.PI;
+    // top and front can only clash far from any grip (≈ 45° off on two axes).
+    if (OPPOSITE[top] === front || top === front)
+        return { grip: IDENTITY_GRIP, offDeg: 90 };
+    return { grip: gripOf(top, front), offDeg: Math.max(deg(bestUp), deg(bestFront)) };
+}
+/** The quaternion that turns the drawn cube so `frame`'s faces sit where the holder sees them. */
+export function frameQuaternion(frame) {
+    // physical = M · canonical → turn the picture by Mᵀ.
+    const M = frame.matrix;
+    const m = [0, 1, 2].map((r) => [0, 1, 2].map((c) => M[c][r]));
+    const tr = m[0][0] + m[1][1] + m[2][2];
+    if (tr > 0) {
+        const s = Math.sqrt(tr + 1) * 2;
+        return { w: s / 4, x: (m[2][1] - m[1][2]) / s, y: (m[0][2] - m[2][0]) / s, z: (m[1][0] - m[0][1]) / s };
+    }
+    if (m[0][0] > m[1][1] && m[0][0] > m[2][2]) {
+        const s = Math.sqrt(1 + m[0][0] - m[1][1] - m[2][2]) * 2;
+        return { w: (m[2][1] - m[1][2]) / s, x: s / 4, y: (m[0][1] + m[1][0]) / s, z: (m[0][2] + m[2][0]) / s };
+    }
+    if (m[1][1] > m[2][2]) {
+        const s = Math.sqrt(1 + m[1][1] - m[0][0] - m[2][2]) * 2;
+        return { w: (m[0][2] - m[2][0]) / s, x: (m[0][1] + m[1][0]) / s, y: s / 4, z: (m[1][2] + m[2][1]) / s };
+    }
+    const s = Math.sqrt(1 + m[2][2] - m[0][0] - m[1][1]) * 2;
+    return { w: (m[1][0] - m[0][1]) / s, x: (m[0][2] + m[2][0]) / s, y: (m[1][2] + m[2][1]) / s, z: s / 4 };
+}
+/** The orientation (as readGrip takes it) of a cube held exactly in `grip`. */
+export const gripQuaternion = (grip) => frameQuaternion(grip);
+/** Where each rotation takes the grip: [new top, new front] as canonical faces of the old grip. */
+const ROTATION_STEP = {
+    x: ["F", "D"], // the front comes up
+    y: ["U", "R"], // the right comes to the front
+    z: ["L", "F"], // the left comes up
+};
+/** The grip after a rotation ("x", "y'", "z2", or several: "x y"). */
+export function rotateGrip(grip, rotation) {
+    let g = grip;
+    for (const token of rotation.split(/\s+/).filter(Boolean)) {
+        const axis = token[0];
+        const step = ROTATION_STEP[axis];
+        if (!step)
+            throw new Error(`Not a rotation: ${token}`);
+        const turns = token.endsWith("2") ? 2 : token.endsWith("'") ? 3 : 1;
+        for (let i = 0; i < turns; i++)
+            g = gripOf(g.face[step[0]], g.face[step[1]]);
+    }
+    return g;
+}
+const SINGLES = ["x", "x'", "x2", "y", "y'", "y2", "z", "z'", "z2"];
+/** Every grip from every other: one rotation, else two (x or z first, then y — the usual "x y'" shape). */
+const CANDIDATES = [
+    "",
+    ...SINGLES,
+    ...["x", "x'", "x2", "z", "z'"].flatMap((a) => ["y", "y'", "y2"].map((b) => `${a} ${b}`)),
+    ...["x", "x'"].flatMap((a) => ["z", "z'", "z2"].map((b) => `${a} ${b}`)),
+];
+/** The shortest rotation from one grip to another ("" when the same). */
+export function rotationBetween(from, to) {
+    if (from.id === to.id)
+        return "";
+    const r = CANDIDATES.find((c) => rotateGrip(from, c).id === to.id);
+    if (r === undefined)
+        throw new Error("unreachable grip");
+    return r;
+}
+/**
+ * Grip changes from a stream of gyro readings, with hysteresis: a new grip
+ * counts once the cube has sat within `maxOffDeg` of it for `dwellMs` — a
+ * wobble during a turn, or passing through a grip on the way to another
+ * (x2 through x), is not a rotation.
+ */
+export class GripTracker {
+    maxOffDeg;
+    dwellMs;
+    grip = null;
+    candidate = null;
+    constructor(maxOffDeg = 35, dwellMs = 150) {
+        this.maxOffDeg = maxOffDeg;
+        this.dwellMs = dwellMs;
+    }
+    /** A reading at time `t`; `mark` is kept with the moment a new grip is first reached (see GripChange.mark). */
+    update(q, t, mark = 0) {
+        const { grip, offDeg } = readGrip(q);
+        if (offDeg > this.maxOffDeg) {
+            this.candidate = null;
+            return null;
+        }
+        if (!this.grip) {
+            this.grip = grip;
+            return null;
+        }
+        if (grip.id === this.grip.id) {
+            this.candidate = null;
+            return null;
+        }
+        if (this.candidate?.grip.id !== grip.id)
+            this.candidate = { grip, since: t, mark };
+        if (t - this.candidate.since < this.dwellMs)
+            return null;
+        const change = { from: this.grip, to: grip, at: this.candidate.since, mark: this.candidate.mark, rotation: rotationBetween(this.grip, grip) };
+        this.grip = grip;
+        this.candidate = null;
+        return change;
+    }
+    reset() {
+        this.grip = null;
+        this.candidate = null;
+    }
+}
+/** All 24 grips (for tests and pickers). */
+export const ALL_GRIPS = FRAMES;
+/** "white top, green front"-style label of a grip, in physical face letters: "U/F". */
+export const gripLabel = (g) => `${g.face.U}/${g.face.F}`;

package/bluetooth/gyro.d.ts

@@ -18,14 +18,53 @@ export declare function normalize(q: Quat): Quat;
 /** A cube's gyro axes → ours. GAN cubes: (x, z, −y). */
 export type AxisMap = (q: Quat) => Quat;
 export declare const GAN_AXES: AxisMap;
+/**
+ * Other brands report their axes differently (MoYu…): a signed permutation
+ * of the vector part after GAN's map. "x,y,z" = GAN's; "-y,z,x" = the new x
+ * is the reading's −y, and so on — 48 in all (rotations and mirrorings).
+ * Find a cube's with `detectAxes`.
+ */
+export declare const DEFAULT_AXES_SPEC = "x,y,z";
+export declare const AXES_SPECS: readonly string[];
+/** A signed permutation of a quaternion's vector part. */
+export declare function permuteAxes(spec: string, q: Quat): Quat;
+/** GAN's map, then `spec`. */
+export declare const axesFromSpec: (spec: string) => AxisMap;
+/**
+ * A cube's axes from raw readings (GyroCalibrator.raw): held as drawn, then
+ * after turning the whole cube to `expectA`, then (back, and) to `expectB` —
+ * the orientations those should read (e.g. grips.gripQuaternion of the grip
+ * after an x, and after a y). Best first, with how far off (degrees) each is.
+ */
+export declare function detectAxes(start: Quat, afterA: Quat, afterB: Quat, expectA: Quat, expectB: Quat): {
+    spec: string;
+    errorDeg: number;
+}[];
+/**
+ * Raw readings → the orientation to show. The first reading (or `calibrate`)
+ * is "held as shown": identity by default, or the orientation of the view it
+ * was shown in (`calibrate(shown)` — e.g. a view with yellow on top). The
+ * calibration is kept as a raw reading, so new axes (`setAxes`) apply to it
+ * too. `align` snaps out drift (the yaw of a gyro wanders): the reading now
+ * is taken to be exactly `to`.
+ */
 export declare class GyroCalibrator {
-    private readonly axes;
+    private axes;
     private basis;
-    private last;
+    private raw;
+    private shown;
+    private anchor;
     constructor(axes?: AxisMap);
-    /** A raw reading → the orientation to show (identity at calibration). The first reading calibrates. */
+    /** A raw reading → the orientation to show. The first reading calibrates. */
     orientation(raw: Quat): Quat;
-    /** "Held as shown now": the latest reading becomes identity. */
-    calibrate(): void;
+    /** The orientation now (null before any reading). */
+    get current(): Quat | null;
+    /** The latest raw reading, as the cube sent it. */
+    get lastRaw(): Quat | null;
+    /** "Held as shown now" — as drawn (identity), or as `shown`. */
+    calibrate(shown?: Quat): void;
+    /** The reading now is exactly `to` (drift out; the cube is held square). */
+    align(to: Quat): void;
+    setAxes(axes: AxisMap): void;
     reset(): void;
 }

package/bluetooth/gyro.js

@@ -20,27 +20,123 @@ export function normalize(q) {
     return { x: q.x / l, y: q.y / l, z: q.z / l, w: q.w / l };
 }
 export const GAN_AXES = (q) => ({ x: q.x, y: q.z, z: -q.y, w: q.w });
+/**
+ * Other brands report their axes differently (MoYu…): a signed permutation
+ * of the vector part after GAN's map. "x,y,z" = GAN's; "-y,z,x" = the new x
+ * is the reading's −y, and so on — 48 in all (rotations and mirrorings).
+ * Find a cube's with `detectAxes`.
+ */
+export const DEFAULT_AXES_SPEC = "x,y,z";
+export const AXES_SPECS = (() => {
+    const perms = [
+        ["x", "y", "z"],
+        ["x", "z", "y"],
+        ["y", "x", "z"],
+        ["y", "z", "x"],
+        ["z", "x", "y"],
+        ["z", "y", "x"],
+    ];
+    const out = [];
+    for (const p of perms)
+        for (let s = 0; s < 8; s++)
+            out.push(p.map((a, i) => ((s >> i) & 1 ? `-${a}` : a)).join(","));
+    return out;
+})();
+const AXIS_INDEX = { x: 0, y: 1, z: 2 };
+/** A signed permutation of a quaternion's vector part. */
+export function permuteAxes(spec, q) {
+    if (spec === DEFAULT_AXES_SPEC)
+        return q;
+    const v = [q.x, q.y, q.z];
+    const [x, y, z] = spec.split(",").map((t) => {
+        const value = v[AXIS_INDEX[t.replace("-", "")]];
+        return t.startsWith("-") ? -value : value;
+    });
+    return { x, y, z, w: q.w };
+}
+/** GAN's map, then `spec`. */
+export const axesFromSpec = (spec) => (spec === DEFAULT_AXES_SPEC ? GAN_AXES : (q) => permuteAxes(spec, GAN_AXES(q)));
+/** An odd signed permutation (a mirror): on a tie with a rotation, the rotation is the likelier. */
+function isMirror(spec) {
+    const t = spec.split(",");
+    const order = t.map((a) => AXIS_INDEX[a.replace("-", "")]);
+    const inversions = (order[0] > order[1] ? 1 : 0) + (order[0] > order[2] ? 1 : 0) + (order[1] > order[2] ? 1 : 0);
+    return (inversions + t.filter((a) => a.startsWith("-")).length) % 2 === 1;
+}
+const angleDeg = (a, b) => {
+    const d = Math.abs(a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w);
+    return (2 * Math.acos(Math.min(1, d)) * 180) / Math.PI;
+};
+/**
+ * A cube's axes from raw readings (GyroCalibrator.raw): held as drawn, then
+ * after turning the whole cube to `expectA`, then (back, and) to `expectB` —
+ * the orientations those should read (e.g. grips.gripQuaternion of the grip
+ * after an x, and after a y). Best first, with how far off (degrees) each is.
+ */
+export function detectAxes(start, afterA, afterB, expectA, expectB) {
+    const rel = (spec, a, b) => {
+        const map = axesFromSpec(spec);
+        return normalize(multiply(conjugate(normalize(map(a))), normalize(map(b))));
+    };
+    return AXES_SPECS.map((spec) => ({ spec, errorDeg: Math.max(angleDeg(rel(spec, start, afterA), expectA), angleDeg(rel(spec, start, afterB), expectB)) })).sort((a, b) => Math.round(a.errorDeg - b.errorDeg) || Number(isMirror(a.spec)) - Number(isMirror(b.spec)));
+}
+/**
+ * Raw readings → the orientation to show. The first reading (or `calibrate`)
+ * is "held as shown": identity by default, or the orientation of the view it
+ * was shown in (`calibrate(shown)` — e.g. a view with yellow on top). The
+ * calibration is kept as a raw reading, so new axes (`setAxes`) apply to it
+ * too. `align` snaps out drift (the yaw of a gyro wanders): the reading now
+ * is taken to be exactly `to`.
+ */
 export class GyroCalibrator {
     axes;
     basis = null;
-    last = null;
+    raw = null;
+    shown = IDENTITY;
+    anchor = IDENTITY;
     constructor(axes = GAN_AXES) {
         this.axes = axes;
     }
-    /** A raw reading → the orientation to show (identity at calibration). The first reading calibrates. */
+    /** A raw reading → the orientation to show. The first reading calibrates. */
     orientation(raw) {
-        const q = normalize(this.axes(raw));
-        this.last = q;
-        this.basis ??= conjugate(q);
-        return normalize(multiply(this.basis, q));
+        this.raw = raw;
+        this.basis ??= raw;
+        return this.current;
+    }
+    /** The orientation now (null before any reading). */
+    get current() {
+        if (!this.raw || !this.basis)
+            return null;
+        const rel = normalize(multiply(conjugate(normalize(this.axes(this.basis))), normalize(this.axes(this.raw))));
+        // The turn since calibrating is in the cube's axes as it was held then
+        // (`shown`): in ours it's shown·rel·shown⁻¹, applied to `shown`.
+        return normalize(multiply(this.anchor, multiply(this.shown, rel)));
+    }
+    /** The latest raw reading, as the cube sent it. */
+    get lastRaw() {
+        return this.raw;
     }
-    /** "Held as shown now": the latest reading becomes identity. */
-    calibrate() {
-        if (this.last)
-            this.basis = conjugate(this.last);
+    /** "Held as shown now" — as drawn (identity), or as `shown`. */
+    calibrate(shown = IDENTITY) {
+        if (this.raw)
+            this.basis = this.raw;
+        this.shown = shown;
+        this.anchor = IDENTITY;
+    }
+    /** The reading now is exactly `to` (drift out; the cube is held square). */
+    align(to) {
+        const now = this.current;
+        if (!now)
+            return;
+        this.anchor = normalize(multiply(multiply(to, conjugate(now)), this.anchor));
+    }
+    setAxes(axes) {
+        this.axes = axes;
     }
     reset() {
         this.basis = null;
-        this.last = null;
+        this.raw = null;
+        this.shown = IDENTITY;
+        this.anchor = IDENTITY;
     }
 }

package/bluetooth/index.d.ts

@@ -3,3 +3,5 @@ export * from "./gyro.js";
 export * from "./session.js";
 export * from "./simulated.js";
 export * from "./cubeSkins.js";
+export * from "./grips.js";
+export * from "./rotations.js";

package/bluetooth/index.js

@@ -3,3 +3,5 @@ export * from "./gyro.js";
 export * from "./session.js";
 export * from "./simulated.js";
 export * from "./cubeSkins.js";
+export * from "./grips.js";
+export * from "./rotations.js";

package/bluetooth/rotations.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Cube rotations with a smart cube's moves: what the solver actually did.
+ *
+ * A smart cube reports face turns relative to its core (the centres) — so
+ * after a y regrip an "R" is what the solver called F, and a slice or wide
+ * move arrives as face turns while the core turns with it (S = F' B + z,
+ * r = L + x, M2 = R' L R' L + x2 when done as two quarters). With the
+ * gyroscope (the core's orientation) both can be read back:
+ *
+ *   const rec = new GripRecorder(session);       // follows grips as moves come in
+ *   …
+ *   const r = rec.forMoves(first, count, t0);     // { startRotation, rotations } of those moves
+ *   heldTokens(moves, r.startRotation, r.rotations)
+ *     // → [R, U, y, F, M2, …] — moves as the solver named them, regrips, slices
+ *
+ * GripRecorder marks each rotation with the number of moves that had come
+ * before it in the session's stream — the order the cube sent them in, far
+ * more reliable than comparing times (a gyro reading carries its arrival
+ * time; a move its time on the cube's own clock). heldTokens still allows
+ * a slice's rotation to come in a little early or late (a cube held loosely
+ * while recognising the next case settles late).
+ */
+import { type Grip } from "./grips.js";
+import type { SmartCubeSession } from "./session.js";
+/** A face turn as reported (physical face letters) and when (ms, any origin — the same as the rotations'). */
+export interface TimedMove {
+    move: string;
+    t: number;
+}
+/** A cube rotation among a list of moves. */
+export interface RotationRecord {
+    /** How many of the moves came before it. */
+    after: number;
+    /** When (ms, the moves' origin). */
+    t: number;
+    /** "x", "y'", "z2", or two: "x y". */
+    move: string;
+}
+export type HeldToken = {
+    kind: "rotation";
+    move: string;
+    t: number;
+    after: number;
+} | {
+    kind: "move";
+    /** As the solver named it (a slice / wide move for a group). */
+    move: string;
+    t: number;
+    /** Index of its (first) reported move. */
+    index: number;
+    /** A slice / wide move made of several reported moves: the last one's index. */
+    lastIndex?: number;
+};
+/** A reported (physical) move ("L'", "R2") as the holder of `grip` names it. */
+export declare function heldMove(move: string, grip: Grip): string;
+/**
+ * The moves as the solver saw them: re-lettered for the grip each was made
+ * in (`startRotation` from white top / green front — U up, F front — then
+ * the rotations), rotations between them (back-to-back ones combined: y y =
+ * y2, y y' = nothing), and slices / wide moves read from face moves with
+ * the core's rotation.
+ */
+export declare function heldTokens(moves: readonly TimedMove[], startRotation: string, rotations: readonly RotationRecord[]): HeldToken[];
+/** A rotation and the face moves around it that make a slice / wide move → that move. */
+export declare function mergeSlicesAndWides(tokens: readonly HeldToken[]): HeldToken[];
+export interface GripEvent {
+    /** Moves the session had reported before it (its stream position). */
+    after: number;
+    /** When it was first reached (performance.now()). */
+    time: number;
+    grip: Grip;
+    /** From the grip before ("" for the first reading). */
+    rotation: string;
+}
+export interface GripRecorderOptions {
+    /** A grip counts when held within this many degrees of it … */
+    maxOffDeg?: number;
+    /** … for this long (ms). */
+    dwellMs?: number;
+    /** Grip changes and move times kept (the latest). */
+    keep?: number;
+}
+/**
+ * Follows a session's grips (gyro) alongside its moves; `forMoves` gives
+ * the rotations of any stretch of moves — a solve, an attempt.
+ */
+export declare class GripRecorder {
+    private readonly session;
+    readonly history: GripEvent[];
+    private readonly tracker;
+    /** Times of the session's latest moves; moveTimes[i] is move number firstMove + i. */
+    private moveTimes;
+    private firstMove;
+    private readonly keep;
+    private readonly listeners;
+    private readonly offs;
+    constructor(session: SmartCubeSession, options?: GripRecorderOptions);
+    /** The grip now (null before the gyro has read one). */
+    get grip(): Grip | null;
+    /** On every grip change (and the first grip). */
+    onChange(fn: (e: GripEvent) => void): () => void;
+    /** Forget the grip (after a recalibration: the next reading starts again). */
+    reset(): void;
+    stop(): void;
+    private reading;
+    /** The session's number of the (first) move reported at `time` — a move event's time — or null if not kept. Moves can share a time (a slice's two faces). */
+    moveNumberAt(time: number): number | null;
+    /** The grip in effect before move number `n`, or null. */
+    gripBefore(n: number): Grip | null;
+    /**
+     * The rotations of `count` moves from move number `first`: how the cube
+     * was held when they started (`startRotation`, from U up / F front) and
+     * each rotation among them (`after` counted within them, `t` from
+     * `startTime`). Null without a grip then.
+     */
+    forMoves(first: number, count: number, startTime: number): {
+        startRotation: string;
+        rotations: RotationRecord[];
+    } | null;
+}

package/bluetooth/rotations.js

@@ -0,0 +1,267 @@
+/**
+ * Cube rotations with a smart cube's moves: what the solver actually did.
+ *
+ * A smart cube reports face turns relative to its core (the centres) — so
+ * after a y regrip an "R" is what the solver called F, and a slice or wide
+ * move arrives as face turns while the core turns with it (S = F' B + z,
+ * r = L + x, M2 = R' L R' L + x2 when done as two quarters). With the
+ * gyroscope (the core's orientation) both can be read back:
+ *
+ *   const rec = new GripRecorder(session);       // follows grips as moves come in
+ *   …
+ *   const r = rec.forMoves(first, count, t0);     // { startRotation, rotations } of those moves
+ *   heldTokens(moves, r.startRotation, r.rotations)
+ *     // → [R, U, y, F, M2, …] — moves as the solver named them, regrips, slices
+ *
+ * GripRecorder marks each rotation with the number of moves that had come
+ * before it in the session's stream — the order the cube sent them in, far
+ * more reliable than comparing times (a gyro reading carries its arrival
+ * time; a move its time on the cube's own clock). heldTokens still allows
+ * a slice's rotation to come in a little early or late (a cube held loosely
+ * while recognising the next case settles late).
+ */
+import { applyMoves, solvedState } from "../core/index.js";
+import { GripTracker, IDENTITY_GRIP, rotateGrip, rotationBetween } from "./grips.js";
+/** A reported (physical) move ("L'", "R2") as the holder of `grip` names it. */
+export function heldMove(move, grip) {
+    const face = move[0];
+    const canonical = Object.keys(grip.face).find((c) => grip.face[c] === face);
+    return canonical ? canonical + move.slice(1) : move;
+}
+/**
+ * The moves as the solver saw them: re-lettered for the grip each was made
+ * in (`startRotation` from white top / green front — U up, F front — then
+ * the rotations), rotations between them (back-to-back ones combined: y y =
+ * y2, y y' = nothing), and slices / wide moves read from face moves with
+ * the core's rotation.
+ */
+export function heldTokens(moves, startRotation, rotations) {
+    let grip = rotateGrip(IDENTITY_GRIP, startRotation);
+    const rots = snapToSlices(moves, grip, [...rotations].sort((a, b) => a.after - b.after || a.t - b.t));
+    const tokens = [];
+    let r = 0;
+    for (let i = 0; i <= moves.length; i++) {
+        let target = grip;
+        let t = 0;
+        while (r < rots.length && rots[r].after <= i) {
+            target = rotateGrip(target, rots[r].move);
+            t = rots[r].t;
+            r++;
+        }
+        const net = rotationBetween(grip, target);
+        if (net)
+            tokens.push({ kind: "rotation", move: net, t, after: i });
+        grip = target;
+        if (i < moves.length)
+            tokens.push({ kind: "move", move: heldMove(moves[i].move, grip), t: moves[i].t, index: i });
+    }
+    return mergeSlicesAndWides(tokens);
+}
+// ─── slices and wide moves ──────────────────────────────────────────────
+/** A slice / wide move's face moves and its rotation, reported this far apart (ms), are one move. */
+const SAME_MOMENT_MS = 500;
+/** How far (ms) a rotation is looked for from the face moves of a wide move. */
+const SNAP_MS = 600;
+/** Face moves one slice / wide move can come as: a half slice turn done as two quarters is four (R' L R' L). */
+const MAX_GROUP = 4;
+/** A slice's rotation can come in this late (ms) — past a couple of other moves — when the cube wasn't held still. */
+const SLICE_LATE_MS = 2500;
+const SLICE_SKIP = 2;
+const AXIS_FACES = { x: ["R", "L"], y: ["U", "D"], z: ["F", "B"] };
+const SLICE_WIDE = ["M", "E", "S", "r", "l", "u", "d", "f", "b"].flatMap((f) => [f, `${f}'`, `${f}2`]);
+const effect = (alg) => applyMoves(solvedState(), alg).join();
+const SLICE_WIDE_EFFECT = new Map();
+/** The slice / wide move the group (held letters and a rotation) amounts to, or null. */
+function sliceOrWide(group) {
+    if (SLICE_WIDE_EFFECT.size === 0)
+        for (const m of SLICE_WIDE)
+            SLICE_WIDE_EFFECT.set(effect(m), m);
+    return SLICE_WIDE_EFFECT.get(effect(group.join(" "))) ?? null;
+}
+/**
+ * The consecutive run (up to MAX_GROUP) of moves on the axis nearest to
+ * `from` going `dir`, skipping at most SLICE_SKIP other moves before it,
+ * within SLICE_LATE_MS of the rotation.
+ */
+function axisRun(moves, from, dir, onAxis, t) {
+    let j = from;
+    let skipped = 0;
+    while (j >= 0 && j < moves.length && !onAxis(j) && skipped < SLICE_SKIP && Math.abs(moves[j].t - t) <= SLICE_LATE_MS) {
+        j += dir;
+        skipped++;
+    }
+    const run = [];
+    while (j >= 0 && j < moves.length && onAxis(j) && run.length < MAX_GROUP && Math.abs(moves[j].t - t) <= SLICE_LATE_MS) {
+        if (dir === -1)
+            run.unshift(j);
+        else
+            run.push(j);
+        j += dir;
+    }
+    return run;
+}
+/**
+ * A slice's rotation can come in a move or two away from its face moves
+ * (F' B U L z): put it right after (or before) the moves on its axis it
+ * makes a slice / wide move with — the moves in between, made after the
+ * centres had turned, get lettered accordingly. Far from them, only a
+ * slice's signature (both faces of the axis) is trusted: one face and a
+ * rotation could as well be a face turn and a real regrip.
+ */
+function snapToSlices(moves, startGrip, rotations) {
+    let grip = startGrip;
+    const out = rotations.map((r) => ({ ...r }));
+    for (const r of out) {
+        const faces = AXIS_FACES[r.move[0]];
+        if (faces && !/\s/.test(r.move)) {
+            const physical = faces.map((f) => grip.face[f]);
+            const onAxis = (j) => physical.includes(moves[j].move[0]);
+            const letters = (idx) => idx.map((j) => heldMove(moves[j].move, grip));
+            const back = axisRun(moves, r.after - 1, -1, onAxis, r.t);
+            const fwd = axisRun(moves, r.after, 1, onAxis, r.t);
+            const tries = [];
+            for (let n = MAX_GROUP; n >= 1; n--)
+                if (back.length >= n)
+                    tries.push([back.slice(-n), back.at(-1) + 1]);
+            for (let n = MAX_GROUP; n >= 1; n--)
+                if (fwd.length >= n)
+                    tries.push([fwd.slice(0, n), fwd[0]]);
+            for (const [idx, after] of tries) {
+                const far = idx.some((j) => Math.abs(moves[j].t - r.t) > SNAP_MS);
+                if (far && new Set(idx.map((j) => moves[j].move[0])).size < 2)
+                    continue;
+                if (sliceOrWide([...letters(idx), r.move])) {
+                    r.after = after;
+                    // It happened with those moves: its time is theirs.
+                    r.t = moves[after > idx[0] ? idx.at(-1) : idx[0]].t;
+                    break;
+                }
+            }
+        }
+        grip = rotateGrip(grip, r.move);
+    }
+    return out.sort((a, b) => a.after - b.after || a.t - b.t);
+}
+/** A rotation and the face moves around it that make a slice / wide move → that move. */
+export function mergeSlicesAndWides(tokens) {
+    const out = [...tokens];
+    for (let k = 0; k < out.length; k++) {
+        const rot = out[k];
+        if (rot.kind !== "rotation" || /\s/.test(rot.move))
+            continue;
+        // The most moves around it first — a slice half turn made of quarters
+        // is four (M2: R' L R' L + x2), a slice two, a wide move one.
+        const windows = [];
+        for (let n = MAX_GROUP; n >= 1; n--)
+            for (let o = 0; o <= n; o++)
+                windows.push([k - n + o, k + o]);
+        for (const [a, b] of windows) {
+            if (a < 0 || b >= out.length)
+                continue;
+            const group = out.slice(a, b + 1);
+            const groupMoves = group.filter((t) => t.kind === "move");
+            if (groupMoves.length !== group.length - 1 || groupMoves.some((m) => Math.abs(m.t - rot.t) > SAME_MOMENT_MS))
+                continue;
+            const merged = sliceOrWide(group.map((t) => t.move));
+            if (!merged)
+                continue;
+            const first = groupMoves[0];
+            out.splice(a, b - a + 1, { kind: "move", move: merged, t: first.t, index: first.index, lastIndex: groupMoves.at(-1).index });
+            k = a;
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * Follows a session's grips (gyro) alongside its moves; `forMoves` gives
+ * the rotations of any stretch of moves — a solve, an attempt.
+ */
+export class GripRecorder {
+    session;
+    history = [];
+    tracker;
+    /** Times of the session's latest moves; moveTimes[i] is move number firstMove + i. */
+    moveTimes = [];
+    firstMove = 0;
+    keep;
+    listeners = new Set();
+    offs;
+    constructor(session, options = {}) {
+        this.session = session;
+        this.tracker = new GripTracker(options.maxOffDeg ?? 35, options.dwellMs ?? 150);
+        this.keep = options.keep ?? 1000;
+        this.offs = [
+            session.on("move", (e) => {
+                this.moveTimes.push(e.time);
+                if (this.moveTimes.length > this.keep) {
+                    this.moveTimes.shift();
+                    this.firstMove++;
+                }
+            }),
+            session.on("orientation", (q) => this.reading(q, performance.now())),
+        ];
+    }
+    /** The grip now (null before the gyro has read one). */
+    get grip() {
+        return this.tracker.grip;
+    }
+    /** On every grip change (and the first grip). */
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    /** Forget the grip (after a recalibration: the next reading starts again). */
+    reset() {
+        this.tracker.reset();
+    }
+    stop() {
+        this.offs.forEach((off) => off());
+    }
+    reading(q, now) {
+        const count = this.session.moveCount;
+        const wasEmpty = this.tracker.grip === null;
+        const change = this.tracker.update(q, now, count);
+        let e = null;
+        if (wasEmpty && this.tracker.grip)
+            e = { after: count, time: now, grip: this.tracker.grip, rotation: "" };
+        else if (change)
+            e = { after: change.mark, time: change.at, grip: change.to, rotation: change.rotation };
+        if (!e)
+            return;
+        this.history.push(e);
+        if (this.history.length > this.keep)
+            this.history.shift();
+        this.listeners.forEach((l) => l(e));
+    }
+    /** The session's number of the (first) move reported at `time` — a move event's time — or null if not kept. Moves can share a time (a slice's two faces). */
+    moveNumberAt(time) {
+        const i = this.moveTimes.indexOf(time);
+        return i < 0 ? null : this.firstMove + i;
+    }
+    /** The grip in effect before move number `n`, or null. */
+    gripBefore(n) {
+        let g = null;
+        for (const e of this.history) {
+            if (e.after > n)
+                break;
+            g = e.grip;
+        }
+        return g;
+    }
+    /**
+     * The rotations of `count` moves from move number `first`: how the cube
+     * was held when they started (`startRotation`, from U up / F front) and
+     * each rotation among them (`after` counted within them, `t` from
+     * `startTime`). Null without a grip then.
+     */
+    forMoves(first, count, startTime) {
+        const start = this.gripBefore(first);
+        if (!start)
+            return null;
+        const rotations = this.history
+            .filter((e) => e.rotation && e.after > first && e.after < first + count)
+            .map((e) => ({ after: e.after - first, t: Math.max(0, Math.round(e.time - startTime)), move: e.rotation }));
+        return { startRotation: rotationBetween(IDENTITY_GRIP, start), rotations };
+    }
+}

package/bluetooth/session.d.ts

@@ -17,6 +17,7 @@ import { type Move, type State } from "../core/index.js";
 import type { ConnectSmartCubeOptions, SmartCubeCapabilities, SmartCubeCommand, SmartCubeEvent } from "./vendor/smartcube-web-bluetooth/index.js";
 import type { Skin } from "../skin/index.js";
 import { type AxisMap, type Quat } from "./gyro.js";
+import { type Grip } from "./grips.js";
 /** What the session needs from a connection — smartcube-web-bluetooth's, or a SimulatedCube. */
 export interface CubeConnection {
     readonly deviceName: string;
@@ -67,8 +68,8 @@ interface Events {
 export interface SessionOptions {
     /** A move is `late` when it arrives this much after it happened. Default 1000 ms. */
     lateMs?: number;
-    /** Gyro axes of this cube (default: GAN). */
-    axes?: AxisMap;
+    /** Gyro axes of this cube (default: GAN) — a map, or a signed permutation after GAN's ("x,y,z"…, see gyro.ts AXES_SPECS). */
+    axes?: AxisMap | string;
     /**
      * For a cube that can't reset its own state (QiYi…): the state of it that
      * counts as solved, kept from an earlier connection (the `base` event) —
@@ -90,6 +91,7 @@ export declare class SmartCubeSession {
     private readonly subscription;
     private readonly lateMs;
     private connected;
+    private moves;
     /** Ask the browser for a cube and connect (needs a user gesture; Chrome / Edge / Bluefy). */
     static connect(options?: ConnectSmartCubeOptions, session?: SessionOptions): Promise<SmartCubeSession>;
     constructor(connection: CubeConnection, options?: SessionOptions);
@@ -109,8 +111,25 @@ export declare class SmartCubeSession {
     get suggestedSkin(): Skin;
     get isConnected(): boolean;
     on<K extends keyof Events>(type: K, listener: (e: Events[K]) => void): () => void;
-    /** "Held as shown now" for the gyro. */
-    calibrate(): void;
+    /**
+     * "Held as shown now" for the gyro: as drawn (U up, F front), or as
+     * `shown` — the orientation of the view the cube is shown in.
+     */
+    calibrate(shown?: Quat): void;
+    /** The gyro's orientation now (calibrated), or null (none yet / no gyro). */
+    get orientation(): Quat | null;
+    /** The latest gyro reading as the cube sent it (for finding a cube's axes — gyro.ts detectAxes). */
+    get rawOrientation(): Quat | null;
+    /** Another brand's gyro axes, while connected — the calibration is kept. */
+    setAxes(axes: AxisMap | string): void;
+    /**
+     * The cube is held square now — snap the gyro onto the nearest grip (its
+     * yaw drifts over minutes). Nothing when it's more than `maxOffDeg` off
+     * any grip. Returns the grip, or null.
+     */
+    alignToGrip(maxOffDeg?: number): Grip | null;
+    /** Moves reported so far on this connection (a move event's number is the count before it). */
+    get moveCount(): number;
     /**
      * Tell the session (and the cube, if it can) that the cube is solved now.
      * Cubes that can't reset their own state (QiYi, …) keep reporting it: the

package/bluetooth/session.js

@@ -16,7 +16,8 @@
 import { applyMove, parseAlg, relativeState, solvedState, stateFromFacelets, statesEqual } from "../core/index.js";
 import { ClockSync } from "./clock.js";
 import { skinForCube } from "./cubeSkins.js";
-import { GAN_AXES, GyroCalibrator } from "./gyro.js";
+import { GAN_AXES, GyroCalibrator, axesFromSpec } from "./gyro.js";
+import { gripQuaternion, readGrip } from "./grips.js";
 export class SmartCubeSession {
     connection;
     listeners = new Map();
@@ -28,6 +29,7 @@ export class SmartCubeSession {
     subscription;
     lateMs;
     connected = true;
+    moves = 0;
     /** Ask the browser for a cube and connect (needs a user gesture; Chrome / Edge / Bluefy). */
     static async connect(options, session) {
         const { connectSmartCube } = await import("./vendor/smartcube-web-bluetooth/index.js");
@@ -36,7 +38,7 @@ export class SmartCubeSession {
     constructor(connection, options = {}) {
         this.connection = connection;
         this.lateMs = options.lateMs ?? 1000;
-        this.gyro = new GyroCalibrator(options.axes ?? GAN_AXES);
+        this.gyro = new GyroCalibrator(typeof options.axes === "string" ? axesFromSpec(options.axes) : (options.axes ?? GAN_AXES));
         const base = typeof options.base === "function" ? options.base({ name: connection.deviceName, mac: connection.deviceMAC ?? null }) : options.base;
         this._base = base ?? null;
         this.subscription = connection.events$.subscribe((e) => this.onEvent(e));
@@ -74,9 +76,43 @@ export class SmartCubeSession {
         set.add(listener);
         return () => set.delete(listener);
     }
-    /** "Held as shown now" for the gyro. */
-    calibrate() {
-        this.gyro.calibrate();
+    /**
+     * "Held as shown now" for the gyro: as drawn (U up, F front), or as
+     * `shown` — the orientation of the view the cube is shown in.
+     */
+    calibrate(shown) {
+        this.gyro.calibrate(shown);
+    }
+    /** The gyro's orientation now (calibrated), or null (none yet / no gyro). */
+    get orientation() {
+        return this.gyro.current;
+    }
+    /** The latest gyro reading as the cube sent it (for finding a cube's axes — gyro.ts detectAxes). */
+    get rawOrientation() {
+        return this.gyro.lastRaw;
+    }
+    /** Another brand's gyro axes, while connected — the calibration is kept. */
+    setAxes(axes) {
+        this.gyro.setAxes(typeof axes === "string" ? axesFromSpec(axes) : axes);
+    }
+    /**
+     * The cube is held square now — snap the gyro onto the nearest grip (its
+     * yaw drifts over minutes). Nothing when it's more than `maxOffDeg` off
+     * any grip. Returns the grip, or null.
+     */
+    alignToGrip(maxOffDeg = 35) {
+        const now = this.gyro.current;
+        if (!now)
+            return null;
+        const { grip, offDeg } = readGrip(now);
+        if (offDeg > maxOffDeg)
+            return null;
+        this.gyro.align(gripQuaternion(grip));
+        return grip;
+    }
+    /** Moves reported so far on this connection (a move event's number is the count before it). */
+    get moveCount() {
+        return this.moves;
     }
     /**
      * Tell the session (and the cube, if it can) that the cube is solved now.
@@ -147,6 +183,7 @@ export class SmartCubeSession {
                 }
                 const state = applyMove(this._state, move);
                 this._state = state;
+                this.moves++;
                 this.emit("move", { move, time, cubeTime: e.cubeTimestamp, late: e.timestamp - time > this.lateMs, state });
                 this.emit("state", { state, reason: "move" });
                 break;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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>",