@wodzik/cubecore 0.1.0

package/bld/memo.js

@@ -0,0 +1,139 @@
+/**
+ * Old Pochmann memorisation. Starting from the buffer, follow where each
+ * sticker belongs: the sticker in the buffer belongs at A → remember A; the
+ * sticker at A belongs at B → remember B; … until the buffer's own piece
+ * comes back. Pieces left unsolved start new cycles (a cycle break: shoot
+ * to one of their stickers, follow, and finish on that piece again) — which
+ * also covers flipped edges and twisted corners in place.
+ *
+ * Executing: each letter is one swap of the buffer piece with the lettered
+ * sticker's piece (edges: T-perm with setup moves, corners: Y-perm). An odd
+ * number of edge letters means parity (an extra algorithm between edges and
+ * corners).
+ *
+ * Buffers: UR for edges, ULB for corners (the usual OP buffers).
+ */
+import { CORNER_FACELETS, EDGE_FACELETS, applyMove, applyMoves, parseAlg, relativeState, solvedState } from "../core/index.js";
+import { RUWIX } from "./scheme.js";
+/** Edge buffer: the U sticker of UR. */
+export const EDGE_BUFFER = 5;
+/** Corner buffer: the U sticker of ULB. */
+export const CORNER_BUFFER = 0;
+/** Sticker positions of each piece, rotated so a given sticker comes first (clockwise for corners). */
+function pieces(groups) {
+    const pieceOf = new Map();
+    groups.forEach((g, i) => g.forEach((f) => pieceOf.set(f, i)));
+    const from = (sticker) => {
+        const g = groups[pieceOf.get(sticker)];
+        const k = g.indexOf(sticker);
+        return [...g.slice(k), ...g.slice(0, k)];
+    };
+    return { pieceOf, from };
+}
+const EDGES = pieces(EDGE_FACELETS);
+const CORNERS = pieces(CORNER_FACELETS);
+/** Targets (sticker positions) for one kind of piece. */
+function trace(state, kind, buffer, order) {
+    const piece = (f) => kind.pieceOf.get(f);
+    const bufferPiece = piece(buffer);
+    const solved = (p) => kind.from(order.find((f) => piece(f) === p)).every((f) => state[f] === f);
+    const visited = new Set([bufferPiece]);
+    const targets = [];
+    // The first cycle, from the buffer.
+    let t = state[buffer];
+    while (piece(t) !== bufferPiece) {
+        targets.push(t);
+        visited.add(piece(t));
+        t = state[t];
+    }
+    // Cycle breaks: unsolved pieces not reached yet, in letter order.
+    for (const start of order) {
+        const p = piece(start);
+        if (visited.has(p) || solved(p))
+            continue;
+        targets.push(start);
+        visited.add(p);
+        t = state[start];
+        while (piece(t) !== p) {
+            targets.push(t);
+            visited.add(piece(t));
+            t = state[t];
+        }
+        targets.push(t);
+    }
+    return targets;
+}
+/** Sticker positions of a kind, in the scheme's letter order (cycle breaks go to the lowest letter). */
+const letterOrder = (letters) => Object.keys(letters)
+    .map(Number)
+    .sort((a, b) => letters[a].localeCompare(letters[b]));
+const CENTRES = [4, 13, 22, 31, 40, 49];
+/** The 24 whole-cube rotations as states (a solved cube turned in your hands). */
+const ROTATIONS = (() => {
+    const out = [solvedState()];
+    const seen = new Set([out[0].join(",")]);
+    const turns = parseAlg("x y");
+    for (let i = 0; i < out.length; i++) {
+        for (const t of turns) {
+            const next = applyMove(out[i], t);
+            const key = next.join(",");
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(next);
+            }
+        }
+    }
+    return out;
+})();
+/**
+ * The state with positions and sticker names as held: turned by `rotation`
+ * if given, and with the centres where they are now counted as home (a
+ * state after rotations, e.g. "… x2 y'", reads the way the cube is now held).
+ */
+export function asHeld(state, rotation) {
+    const s = rotation ? applyMoves(state, rotation) : new Uint8Array(state);
+    const turned = ROTATIONS.find((r) => CENTRES.every((c) => r[c] === s[c]));
+    return turned ? relativeState(s, turned) : s;
+}
+/** The letters to remember for `state`. */
+export function memo(input, options = {}) {
+    const state = asHeld(input, options.rotation);
+    const scheme = options.scheme ?? RUWIX;
+    const edgeTargets = trace(state, EDGES, options.edgeBuffer ?? EDGE_BUFFER, letterOrder(scheme.edges));
+    const cornerTargets = trace(state, CORNERS, options.cornerBuffer ?? CORNER_BUFFER, letterOrder(scheme.corners));
+    return {
+        edges: edgeTargets.map((f) => scheme.edges[f]),
+        corners: cornerTargets.map((f) => scheme.corners[f]),
+        edgeTargets,
+        cornerTargets,
+        parity: edgeTargets.length % 2 === 1,
+    };
+}
+/** Letters in pairs, the usual way to write memo: "QU SR NX IV PR DE". */
+export const formatMemo = (letters) => letters.reduce((out, l, i) => out + (i > 0 && i % 2 === 0 ? " " : "") + l, "");
+/**
+ * The effect of one letter on the pieces of its kind: the buffer piece and
+ * the target's piece swap, the buffer sticker going to the target sticker
+ * (what the setup + T-perm / Y-perm + undo do to that kind of piece).
+ */
+export function swapToTarget(state, kind, target, buffer = kind === "edge" ? EDGE_BUFFER : CORNER_BUFFER) {
+    const k = kind === "edge" ? EDGES : CORNERS;
+    const b = k.from(buffer), t = k.from(target);
+    const out = new Uint8Array(state);
+    b.forEach((bf, i) => {
+        out[t[i]] = state[bf];
+        out[bf] = state[t[i]];
+    });
+    return out;
+}
+/** Sticker positions of edges / corners (to compare only one kind of piece). */
+export const EDGE_POSITIONS = EDGE_FACELETS.flat();
+export const CORNER_POSITIONS = CORNER_FACELETS.flat();
+export const samePieces = (a, b, positions) => positions.every((p) => a[p] === b[p]);
+/** Two sticker positions on the same edge / corner. */
+export const samePiece = (kind, a, b) => {
+    const k = kind === "edge" ? EDGES : CORNERS;
+    return k.pieceOf.get(a) === k.pieceOf.get(b);
+};
+/** The whole-cube rotation state with these centres (a solved cube as held), or null. */
+export const rotationState = (rotation) => applyMoves(solvedState(), rotation);

package/bld/scheme.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Letter schemes: a letter for each corner sticker and each edge sticker
+ * (24 + 24; centres have none). Positions are facelet indices of the cube as
+ * held (U = the up face).
+ *
+ * Both built-ins letter each face clockwise from its top-left corner / top
+ * edge, looking at the face in the usual net (U with B at its top, side
+ * faces with U at the top, D with F at its top) — A B C D on the first face,
+ * E F G H on the second, … — they differ only in the order of the faces.
+ */
+import { type Face } from "../core/index.js";
+export interface LetterScheme {
+    name: string;
+    /** Letter of each corner sticker position (facelet index → letter). */
+    corners: Record<number, string>;
+    /** Letter of each edge sticker position. */
+    edges: Record<number, string>;
+}
+/** A scheme lettering the faces in `order`, four letters each, clockwise from the top-left. */
+export declare function schemeByFaces(name: string, order: readonly Face[]): LetterScheme;
+/** Speffz: U, L, F, R, B, D. */
+export declare const SPEFFZ: LetterScheme;
+/** The ruwix.com tutorial's scheme: U, F, R, B, L, D. */
+export declare const RUWIX: LetterScheme;
+export declare const SCHEMES: {
+    readonly speffz: LetterScheme;
+    readonly ruwix: LetterScheme;
+};
+/** Letter of any sticker position (corner or edge), or "" for a centre. */
+export declare const letterAt: (scheme: LetterScheme, position: number) => string;

package/bld/scheme.js

@@ -0,0 +1,35 @@
+/**
+ * Letter schemes: a letter for each corner sticker and each edge sticker
+ * (24 + 24; centres have none). Positions are facelet indices of the cube as
+ * held (U = the up face).
+ *
+ * Both built-ins letter each face clockwise from its top-left corner / top
+ * edge, looking at the face in the usual net (U with B at its top, side
+ * faces with U at the top, D with F at its top) — A B C D on the first face,
+ * E F G H on the second, … — they differ only in the order of the faces.
+ */
+import { FACES } from "../core/index.js";
+/** Within a face (row-major 0..8): corners and edges, clockwise from the top-left. */
+const CORNER_CELLS = [0, 2, 8, 6];
+const EDGE_CELLS = [1, 5, 7, 3];
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWX";
+/** A scheme lettering the faces in `order`, four letters each, clockwise from the top-left. */
+export function schemeByFaces(name, order) {
+    const corners = {};
+    const edges = {};
+    order.forEach((face, i) => {
+        const base = FACES.indexOf(face) * 9;
+        for (let j = 0; j < 4; j++) {
+            corners[base + CORNER_CELLS[j]] = ALPHABET[i * 4 + j];
+            edges[base + EDGE_CELLS[j]] = ALPHABET[i * 4 + j];
+        }
+    });
+    return { name, corners, edges };
+}
+/** Speffz: U, L, F, R, B, D. */
+export const SPEFFZ = schemeByFaces("Speffz", ["U", "L", "F", "R", "B", "D"]);
+/** The ruwix.com tutorial's scheme: U, F, R, B, L, D. */
+export const RUWIX = schemeByFaces("ruwix", ["U", "F", "R", "B", "L", "D"]);
+export const SCHEMES = { speffz: SPEFFZ, ruwix: RUWIX };
+/** Letter of any sticker position (corner or edge), or "" for a centre. */
+export const letterAt = (scheme, position) => scheme.corners[position] ?? scheme.edges[position] ?? "";

package/bld/skin.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A skin with the scheme's letters on the stickers. Each sticker carries the
+ * letter of its HOME position and keeps it wherever it goes — so the letter
+ * showing in the buffer is the next letter to remember.
+ *
+ *   player.skin = letterSkin(SKINS.default);                       // colours + letters
+ *   player.skin = letterSkin(SKINS.default, { alwaysShow: true });   // letters stay on masked (grey) stickers too
+ */
+import { type Move } from "../core/index.js";
+import type { Skin } from "../skin/index.js";
+import { type LetterScheme } from "./scheme.js";
+export interface LetterSkinOptions {
+    scheme?: LetterScheme;
+    /** Letter colour. Default near-black with a white edge (reads on every sticker colour). */
+    color?: string;
+    outline?: string | null;
+    /** Letter size as a fraction of the tile. Default 0.62. */
+    size?: number;
+    /** Keep the letters on stickers a mask greys out (a "letters only" cube). Default false. */
+    alwaysShow?: boolean;
+    /** How the cube is held (as in `memo`): letters by the positions as held, upright for the holder. */
+    rotation?: string | readonly Move[];
+}
+/** The SVG of one letter (square, transparent). */
+export declare function letterSvg(letter: string, color?: string, outline?: string | null): string;
+export declare function letterSkin(base: Skin, options?: LetterSkinOptions): Skin;

package/bld/skin.js

@@ -0,0 +1,46 @@
+/**
+ * A skin with the scheme's letters on the stickers. Each sticker carries the
+ * letter of its HOME position and keeps it wherever it goes — so the letter
+ * showing in the buffer is the next letter to remember.
+ *
+ *   player.skin = letterSkin(SKINS.default);                       // colours + letters
+ *   player.skin = letterSkin(SKINS.default, { alwaysShow: true });   // letters stay on masked (grey) stickers too
+ */
+import { FACELETS, FACE_BASIS, applyMoves, solvedState } from "../core/index.js";
+import { RUWIX, letterAt } from "./scheme.js";
+const escape = (s) => s.replace(/[<&"]/g, (c) => ({ "<": "&lt;", "&": "&amp;", '"': "&quot;" })[c]);
+/** The SVG of one letter (square, transparent). */
+export function letterSvg(letter, color = "#111111", outline = "#ffffff") {
+    const stroke = outline ? ` stroke="${escape(outline)}" stroke-width="7" paint-order="stroke" stroke-linejoin="round"` : "";
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text x="50" y="52" text-anchor="middle" dominant-baseline="central" font-family="Arial, Helvetica, sans-serif" font-weight="700" font-size="78" fill="${escape(color)}"${stroke}>${escape(letter)}</text></svg>`;
+}
+const same = (a, b) => a.every((v, i) => Math.abs(v - b[i]) < 1e-9);
+const minus = (a, b) => a.map((v, i) => v - b[i]);
+const neg = (a) => a.map((v) => -v);
+export function letterSkin(base, options = {}) {
+    const scheme = options.scheme ?? RUWIX;
+    // Held position of each sticker (a solved cube turned as held), and how its face is turned for the holder.
+    const rot = options.rotation ? applyMoves(solvedState(), options.rotation) : solvedState();
+    const heldAt = new Map();
+    rot.forEach((sticker, pos) => heldAt.set(sticker, pos));
+    const decals = [];
+    for (const f of FACELETS) {
+        const held = heldAt.get(f.index);
+        const letter = letterAt(scheme, held);
+        if (!letter)
+            continue;
+        // The sticker's own "right" (centre → right edge of its face), as seen on the held face.
+        const face = Math.floor(f.index / 9) * 9;
+        const right = minus(FACELETS[heldAt.get(face + 5)].pos, FACELETS[heldAt.get(face + 4)].pos);
+        const { a, b } = FACE_BASIS[FACELETS[held].face];
+        const rotate = same(right, a) ? 0 : same(right, b) ? 3 : same(right, neg(a)) ? 2 : 1;
+        decals.push({
+            select: { stickers: [f.index] },
+            rotate,
+            image: letterSvg(letter, options.color, options.outline === undefined ? "#ffffff" : options.outline),
+            size: options.size ?? 0.62,
+            onlyRegular: !options.alwaysShow,
+        });
+    }
+    return { ...base, decals: [...(base.decals ?? []), ...decals] };
+}

package/bld/tracker.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Following an Old Pochmann execution on a smart cube, letter by letter.
+ *
+ * A letter counts as done when that kind of piece is exactly where the swap
+ * leaves it: edges after an edge letter, corners after a corner letter. Only
+ * one kind is compared — the swap algorithms move a couple of pieces of the
+ * other kind on the side (T-perm two corners, Y-perm two edges), which the
+ * next letters / parity put back. Any algorithm doing the same swap counts.
+ *
+ * Parity (odd letters): edges first — after the edges the two corners the
+ * T-perms moved are still swapped; the parity step is done when the corners
+ * are back as they were at the start. Corners first (`order: "corners"`) —
+ * the same the other way round: after the corners the two edges the Y-perms
+ * moved are swapped; parity is done when the edges are back.
+ *
+ * A swap with a different letter than the one due is reported (`wrong`).
+ */
+import { type Move, type State } from "../core/index.js";
+import { type Memo, type MemoOptions } from "./memo.js";
+export type BldStepKind = "edge" | "parity" | "corner";
+export interface BldStep {
+    kind: BldStepKind;
+    /** The letter ("" for parity). */
+    letter: string;
+    /** Sticker position shot to (-1 for parity). */
+    target: number;
+}
+export interface BldProgress {
+    steps: BldStep[];
+    /** Steps done (the next one to do is steps[done]). */
+    done: number;
+    status: ("done" | "current" | "todo")[];
+    /** The last finished swap went to another letter than the one due. */
+    wrong: {
+        expected: string;
+        got: string;
+        kind: BldStepKind;
+    } | null;
+    /** Every letter done. */
+    complete: boolean;
+    /** The cube is solved. */
+    solved: boolean;
+}
+export interface BldTrackerOptions extends MemoOptions {
+    /** Which kind is solved first. Default "edges". */
+    order?: "edges" | "corners";
+}
+export declare class BldTracker {
+    readonly memo: Memo;
+    readonly steps: BldStep[];
+    private readonly checkpoints;
+    private readonly start;
+    private readonly held;
+    private readonly toHeld;
+    private readonly options;
+    private cur;
+    private doneCount;
+    private wrong;
+    constructor(start: State, options?: BldTrackerOptions);
+    get state(): State;
+    /** A face turn from the cube. */
+    push(move: Move): BldProgress;
+    /** A swap with another letter than the due one, just finished? */
+    private wrongSwap;
+    /** Where that kind of piece should be before the due step. */
+    private previousOfKind;
+    get progress(): BldProgress;
+}

package/bld/tracker.js

@@ -0,0 +1,145 @@
+/**
+ * Following an Old Pochmann execution on a smart cube, letter by letter.
+ *
+ * A letter counts as done when that kind of piece is exactly where the swap
+ * leaves it: edges after an edge letter, corners after a corner letter. Only
+ * one kind is compared — the swap algorithms move a couple of pieces of the
+ * other kind on the side (T-perm two corners, Y-perm two edges), which the
+ * next letters / parity put back. Any algorithm doing the same swap counts.
+ *
+ * Parity (odd letters): edges first — after the edges the two corners the
+ * T-perms moved are still swapped; the parity step is done when the corners
+ * are back as they were at the start. Corners first (`order: "corners"`) —
+ * the same the other way round: after the corners the two edges the Y-perms
+ * moved are swapped; parity is done when the edges are back.
+ *
+ * A swap with a different letter than the one due is reported (`wrong`).
+ */
+import { applyMove, applyMoves, isSolved, solvedState } from "../core/index.js";
+import { asHeld } from "./memo.js";
+import { CORNER_BUFFER, CORNER_POSITIONS, EDGE_BUFFER, EDGE_POSITIONS, samePiece as sameKindPiece, memo, samePieces, swapToTarget } from "./memo.js";
+import { RUWIX } from "./scheme.js";
+export class BldTracker {
+    memo;
+    steps;
+    checkpoints;
+    start;
+    held;
+    toHeld;
+    options;
+    cur;
+    doneCount = 0;
+    wrong = null;
+    constructor(start, options = {}) {
+        const scheme = options.scheme ?? RUWIX;
+        // Work as held: moves are turned into the held frame as they come.
+        this.held = asHeld(start, options.rotation);
+        this.memo = memo(this.held);
+        this.start = this.held;
+        this.cur = new Uint8Array(this.held);
+        this.toHeld = heldMoveMap(options.rotation);
+        this.steps = [];
+        this.checkpoints = [];
+        const edges = () => {
+            let s = new Uint8Array(this.held);
+            this.memo.edgeTargets.forEach((t, i) => {
+                s = swapToTarget(s, "edge", t, options.edgeBuffer);
+                this.steps.push({ kind: "edge", letter: this.memo.edges[i], target: t });
+                this.checkpoints.push({ positions: EDGE_POSITIONS, state: s });
+            });
+        };
+        const corners = () => {
+            let c = new Uint8Array(this.held);
+            this.memo.cornerTargets.forEach((t, i) => {
+                c = swapToTarget(c, "corner", t, options.cornerBuffer);
+                this.steps.push({ kind: "corner", letter: this.memo.corners[i], target: t });
+                this.checkpoints.push({ positions: CORNER_POSITIONS, state: c });
+            });
+        };
+        // Parity: the other kind — moved on the side by the first kind's swaps — back as it was.
+        const parity = (other) => {
+            if (!this.memo.parity)
+                return;
+            this.steps.push({ kind: "parity", letter: "", target: -1 });
+            this.checkpoints.push({ positions: other, state: new Uint8Array(this.held) });
+        };
+        if (options.order === "corners") {
+            corners();
+            parity(EDGE_POSITIONS);
+            edges();
+        }
+        else {
+            edges();
+            parity(CORNER_POSITIONS);
+            corners();
+        }
+        this.options = { ...options, scheme };
+    }
+    get state() {
+        return this.cur;
+    }
+    /** A face turn from the cube. */
+    push(move) {
+        this.cur = applyMove(this.cur, this.toHeld(move));
+        // Done with the next step (or several: e.g. parity needs nothing when the corners came back on their own).
+        while (this.doneCount < this.steps.length) {
+            const cp = this.checkpoints[this.doneCount];
+            if (!samePieces(this.cur, cp.state, cp.positions))
+                break;
+            this.doneCount++;
+            this.wrong = null;
+        }
+        this.wrong = this.doneCount < this.steps.length ? this.wrongSwap() : null;
+        return this.progress;
+    }
+    /** A swap with another letter than the due one, just finished? */
+    wrongSwap() {
+        const step = this.steps[this.doneCount];
+        if (step.kind === "parity")
+            return null;
+        const prev = this.previousOfKind(step.kind);
+        const positions = step.kind === "edge" ? EDGE_POSITIONS : CORNER_POSITIONS;
+        const letters = step.kind === "edge" ? this.options.scheme.edges : this.options.scheme.corners;
+        for (const [pos, letter] of Object.entries(letters)) {
+            const t = Number(pos);
+            if (t === step.target || sameKindPiece(step.kind, t, step.kind === "edge" ? (this.options.edgeBuffer ?? EDGE_BUFFER) : (this.options.cornerBuffer ?? CORNER_BUFFER)))
+                continue;
+            const buffer = step.kind === "edge" ? this.options.edgeBuffer : this.options.cornerBuffer;
+            const after = swapToTarget(prev, step.kind, t, buffer);
+            if (samePieces(this.cur, after, positions) && !samePieces(after, prev, positions))
+                return { expected: step.letter, got: letter, kind: step.kind };
+        }
+        return null;
+    }
+    /** Where that kind of piece should be before the due step. */
+    previousOfKind(kind) {
+        for (let i = this.doneCount - 1; i >= 0; i--)
+            if (this.steps[i].kind === kind)
+                return this.checkpoints[i].state;
+        return this.start;
+    }
+    get progress() {
+        return {
+            steps: this.steps,
+            done: this.doneCount,
+            status: this.steps.map((_, i) => (i < this.doneCount ? "done" : i === this.doneCount ? "current" : "todo")),
+            wrong: this.wrong,
+            complete: this.doneCount === this.steps.length,
+            solved: isSolved(this.cur),
+        };
+    }
+}
+/**
+ * A face turn of the cube (its own faces) as the face it is for the holder:
+ * the cube's R is the held L after y2, and so on.
+ */
+function heldMoveMap(rotation) {
+    if (!rotation)
+        return (m) => m;
+    const rot = applyMoves(solvedState(), rotation);
+    const faceAt = new Map();
+    for (let pos = 0; pos < 6; pos++)
+        faceAt.set(FACE_NAMES[(rot[pos * 9 + 4] / 9) | 0], FACE_NAMES[pos]);
+    return (m) => (faceAt.has(m.family) ? { ...m, family: faceAt.get(m.family) } : m);
+}
+const FACE_NAMES = "URFDLB";

package/bluetooth/clock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Move times you can trust. Browsers deliver Bluetooth notifications late
+ * and in bursts (a backgrounded tab, a busy main thread), and moves a GAN
+ * cube re-sends after a dropped packet arrive with no local time at all —
+ * so "when the notification arrived" can be seconds off. Cubes that report
+ * their own clock (GAN gen2+ and others) let us do better: map the cube's
+ * clock onto the page's (`performance.now()`) with the smallest observed
+ * difference, i.e. the least delayed notification.
+ */
+export declare class ClockSync {
+    private readonly window;
+    private samples;
+    /** @param window how many recent samples the offset is estimated from (the cube clock drifts slowly). */
+    constructor(window?: number);
+    /** Offset (local − cube) estimated so far, or null before the first sample. */
+    get offset(): number | null;
+    /** Feed one event: its cube time and, if it has one, the local time it arrived. */
+    observe(cubeTime: number, localTime: number | null): void;
+    /** The cube time on the page's clock (null until an offset is known). */
+    toLocal(cubeTime: number): number | null;
+    reset(): void;
+}

package/bluetooth/clock.js

@@ -0,0 +1,37 @@
+/**
+ * Move times you can trust. Browsers deliver Bluetooth notifications late
+ * and in bursts (a backgrounded tab, a busy main thread), and moves a GAN
+ * cube re-sends after a dropped packet arrive with no local time at all —
+ * so "when the notification arrived" can be seconds off. Cubes that report
+ * their own clock (GAN gen2+ and others) let us do better: map the cube's
+ * clock onto the page's (`performance.now()`) with the smallest observed
+ * difference, i.e. the least delayed notification.
+ */
+export class ClockSync {
+    window;
+    samples = [];
+    /** @param window how many recent samples the offset is estimated from (the cube clock drifts slowly). */
+    constructor(window = 64) {
+        this.window = window;
+    }
+    /** Offset (local − cube) estimated so far, or null before the first sample. */
+    get offset() {
+        return this.samples.length ? Math.min(...this.samples) : null;
+    }
+    /** Feed one event: its cube time and, if it has one, the local time it arrived. */
+    observe(cubeTime, localTime) {
+        if (localTime === null)
+            return;
+        this.samples.push(localTime - cubeTime);
+        if (this.samples.length > this.window)
+            this.samples.shift();
+    }
+    /** The cube time on the page's clock (null until an offset is known). */
+    toLocal(cubeTime) {
+        const o = this.offset;
+        return o === null ? null : cubeTime + o;
+    }
+    reset() {
+        this.samples = [];
+    }
+}

package/bluetooth/cubeSkins.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which skin suits the connected cube. Rules match the protocol id and the
+ * device / hardware name the cube reports; the first match wins, so rules an
+ * app registers (e.g. skins made for particular models) go before the
+ * built-in defaults:
+ *
+ *   GAN                          → gan
+ *   QiYi QY-SC (name QY-QYSC…)   → qiyiSC
+ *   MoYu (name WCU_MY…)          → moyu
+ *   anything else                → default (stickerless, as most smart cubes are)
+ *
+ * Only looks are chosen here — nothing depends on it.
+ */
+import { SKINS, type Skin } from "../skin/index.js";
+export interface CubeSkinRule {
+    /** Protocol id (smartcube-web-bluetooth: "gan-gen4", "moyu32", "qiyi"…) — string = prefix, or a RegExp. */
+    protocol?: string | RegExp;
+    /** Device or hardware name (as the cube advertises it). */
+    name?: RegExp;
+    skin: Skin | keyof typeof SKINS;
+}
+/** Add a rule ahead of the built-in ones (later registrations win over earlier ones). */
+export declare function registerCubeSkin(rule: CubeSkinRule): void;
+/** The skin for a cube: its protocol and the names it reported. */
+export declare function skinForCube(cube: {
+    protocol: {
+        id: string;
+    };
+    name?: string;
+    hardwareName?: string;
+}): Skin;

package/bluetooth/cubeSkins.js

@@ -0,0 +1,32 @@
+/**
+ * Which skin suits the connected cube. Rules match the protocol id and the
+ * device / hardware name the cube reports; the first match wins, so rules an
+ * app registers (e.g. skins made for particular models) go before the
+ * built-in defaults:
+ *
+ *   GAN                          → gan
+ *   QiYi QY-SC (name QY-QYSC…)   → qiyiSC
+ *   MoYu (name WCU_MY…)          → moyu
+ *   anything else                → default (stickerless, as most smart cubes are)
+ *
+ * Only looks are chosen here — nothing depends on it.
+ */
+import { SKINS } from "../skin/index.js";
+const test = (m, value) => m === undefined || (typeof m === "string" ? value.startsWith(m) : m.test(value));
+const BUILT_IN = [
+    { protocol: "gan", skin: "gan" },
+    { protocol: "qiyi", name: /^QY-QYSC/i, skin: "qiyiSC" },
+    { protocol: "moyu", name: /^WCU_MY/i, skin: "moyu" },
+    { skin: "default" },
+];
+const registered = [];
+/** Add a rule ahead of the built-in ones (later registrations win over earlier ones). */
+export function registerCubeSkin(rule) {
+    registered.unshift(rule);
+}
+/** The skin for a cube: its protocol and the names it reported. */
+export function skinForCube(cube) {
+    const names = [cube.name ?? "", cube.hardwareName ?? ""];
+    const rule = [...registered, ...BUILT_IN].find((r) => test(r.protocol, cube.protocol.id) && (!r.name || names.some((n) => r.name.test(n))));
+    return typeof rule.skin === "string" ? SKINS[rule.skin] : rule.skin;
+}

package/bluetooth/gyro.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Gyroscope → renderer orientation. A smart cube reports its rotation as a
+ * quaternion in its own axes; the renderer (`CubeRenderer.setOrientation`)
+ * wants one in ours (x right, y up, z towards you) where identity = the cube
+ * as drawn. `calibrate` (or the first reading) says "the cube is held as
+ * shown right now".
+ */
+export interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export declare const IDENTITY: Quat;
+export declare function multiply(a: Quat, b: Quat): Quat;
+export declare const conjugate: (q: Quat) => Quat;
+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;
+export declare class GyroCalibrator {
+    private readonly axes;
+    private basis;
+    private last;
+    constructor(axes?: AxisMap);
+    /** A raw reading → the orientation to show (identity at calibration). The first reading calibrates. */
+    orientation(raw: Quat): Quat;
+    /** "Held as shown now": the latest reading becomes identity. */
+    calibrate(): void;
+    reset(): void;
+}